codekingpro/portable-devtools

1from __future__ import annotations2 3from typing import Protocol4 5from ..dist import Distribution6 7from distutils.command.build import build as _build8 9_ORIGINAL_SUBCOMMANDS = {"build_py", "build_clib", "build_ext", "build_scripts"}10 11 12class build(_build):13    distribution: Distribution  # override distutils.dist.Distribution with setuptools.dist.Distribution14 15    # copy to avoid sharing the object with parent class16    sub_commands = _build.sub_commands[:]17 18 19class SubCommand(Protocol):20    """In order to support editable installations (see :pep:`660`) all21    build subcommands **SHOULD** implement this protocol. They also **MUST** inherit22    from ``setuptools.Command``.23 24    When creating an :pep:`editable wheel <660>`, ``setuptools`` will try to evaluate25    custom ``build`` subcommands using the following procedure:26 27    1. ``setuptools`` will set the ``editable_mode`` attribute to ``True``28    2. ``setuptools`` will execute the ``run()`` command.29 30       .. important::31          Subcommands **SHOULD** take advantage of ``editable_mode=True`` to adequate32          its behaviour or perform optimisations.33 34          For example, if a subcommand doesn't need to generate an extra file and35          all it does is to copy a source file into the build directory,36          ``run()`` **SHOULD** simply "early return".37 38          Similarly, if the subcommand creates files that would be placed alongside39          Python files in the final distribution, during an editable install40          the command **SHOULD** generate these files "in place" (i.e. write them to41          the original source directory, instead of using the build directory).42          Note that ``get_output_mapping()`` should reflect that and include mappings43          for "in place" builds accordingly.44 45    3. ``setuptools`` use any knowledge it can derive from the return values of46       ``get_outputs()`` and ``get_output_mapping()`` to create an editable wheel.47       When relevant ``setuptools`` **MAY** attempt to use file links based on the value48       of ``get_output_mapping()``. Alternatively, ``setuptools`` **MAY** attempt to use49       :doc:`import hooks <python:reference/import>` to redirect any attempt to import50       to the directory with the original source code and other files built in place.51 52    Please note that custom sub-commands **SHOULD NOT** rely on ``run()`` being53    executed (or not) to provide correct return values for ``get_outputs()``,54    ``get_output_mapping()`` or ``get_source_files()``. The ``get_*`` methods should55    work independently of ``run()``.56    """57 58    editable_mode: bool = False59    """Boolean flag that will be set to ``True`` when setuptools is used for an60    editable installation (see :pep:`660`).61    Implementations **SHOULD** explicitly set the default value of this attribute to62    ``False``.63    When subcommands run, they can use this flag to perform optimizations or change64    their behaviour accordingly.65    """66 67    build_lib: str68    """String representing the directory where the build artifacts should be stored,69    e.g. ``build/lib``.70    For example, if a distribution wants to provide a Python module named ``pkg.mod``,71    then a corresponding file should be written to ``{build_lib}/package/module.py``.72    A way of thinking about this is that the files saved under ``build_lib``73    would be eventually copied to one of the directories in :obj:`site.PREFIXES`74    upon installation.75 76    A command that produces platform-independent files (e.g. compiling text templates77    into Python functions), **CAN** initialize ``build_lib`` by copying its value from78    the ``build_py`` command. On the other hand, a command that produces79    platform-specific files **CAN** initialize ``build_lib`` by copying its value from80    the ``build_ext`` command. In general this is done inside the ``finalize_options``81    method with the help of the ``set_undefined_options`` command::82 83        def finalize_options(self):84            self.set_undefined_options("build_py", ("build_lib", "build_lib"))85            ...86    """87 88    def initialize_options(self) -> None:89        """(Required by the original :class:`setuptools.Command` interface)"""90        ...91 92    def finalize_options(self) -> None:93        """(Required by the original :class:`setuptools.Command` interface)"""94        ...95 96    def run(self) -> None:97        """(Required by the original :class:`setuptools.Command` interface)"""98        ...99 100    def get_source_files(self) -> list[str]:101        """102        Return a list of all files that are used by the command to create the expected103        outputs.104        For example, if your build command transpiles Java files into Python, you should105        list here all the Java files.106        The primary purpose of this function is to help populating the ``sdist``107        with all the files necessary to build the distribution.108        All files should be strings relative to the project root directory.109        """110        ...111 112    def get_outputs(self) -> list[str]:113        """114        Return a list of files intended for distribution as they would have been115        produced by the build.116        These files should be strings in the form of117        ``"{build_lib}/destination/file/path"``.118 119        .. note::120           The return value of ``get_output()`` should include all files used as keys121           in ``get_output_mapping()`` plus files that are generated during the build122           and don't correspond to any source file already present in the project.123        """124        ...125 126    def get_output_mapping(self) -> dict[str, str]:127        """128        Return a mapping between destination files as they would be produced by the129        build (dict keys) into the respective existing (source) files (dict values).130        Existing (source) files should be represented as strings relative to the project131        root directory.132        Destination files should be strings in the form of133        ``"{build_lib}/destination/file/path"``.134        """135        ...136