Updates to PEP 660 (GH-1978)
This commit is contained in:
parent
82cd151074
commit
f06a8c73d8
104
pep-0660.rst
104
pep-0660.rst
|
@ -1,5 +1,5 @@
|
||||||
PEP: 660
|
PEP: 660
|
||||||
Title: Editable installs for PEP 517 style build backends
|
Title: Editable installs for pyproject.toml based builds
|
||||||
Author: Daniel Holth <dholth@gmail.com>, Stéphane Bidoul <stephane.bidoul@gmail.com>
|
Author: Daniel Holth <dholth@gmail.com>, Stéphane Bidoul <stephane.bidoul@gmail.com>
|
||||||
Sponsor: Paul Moore <p.f.moore@gmail.com>
|
Sponsor: Paul Moore <p.f.moore@gmail.com>
|
||||||
Discussions-To: https://discuss.python.org/t/draft-pep-editable-installs-for-pep-517-style-build-backends/8510
|
Discussions-To: https://discuss.python.org/t/draft-pep-editable-installs-for-pep-517-style-build-backends/8510
|
||||||
|
@ -67,11 +67,14 @@ require a compilation and/or installation step to become effective. The exact
|
||||||
steps to perform will remain specific to the build backend used.
|
steps to perform will remain specific to the build backend used.
|
||||||
|
|
||||||
When a project is installed in editable mode, users expect the installation to
|
When a project is installed in editable mode, users expect the installation to
|
||||||
behave identically as a regular installation. Depending on the way build
|
behave identically as a regular installation. In particular the code must be
|
||||||
backends implement this specification, some minor differences may be visible
|
importable by other code, and metadata must be available to standard mechanisms
|
||||||
such as the presence of additional files that are in the source tree and would
|
such as ``importlib.metadata``.
|
||||||
not be part of a regular install. Build backends are encouraged to document
|
|
||||||
such potential differences.
|
Depending on the way build backends implement this specification, some minor
|
||||||
|
differences may be visible such as the presence of additional files that are in
|
||||||
|
the source tree and would not be part of a regular install. Build backends are
|
||||||
|
encouraged to document such potential differences.
|
||||||
|
|
||||||
The Mechanism
|
The Mechanism
|
||||||
=============
|
=============
|
||||||
|
@ -85,17 +88,9 @@ build_wheel_for_editable
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
def build_wheel_for_editable(
|
def build_wheel_for_editable(wheel_directory, config_settings=None):
|
||||||
wheel_directory,
|
|
||||||
scheme=scheme,
|
|
||||||
config_settings=None):
|
|
||||||
...
|
...
|
||||||
|
|
||||||
``scheme``: a dictionary of installation categories ``{ 'purelib':
|
|
||||||
'/home/py/.../site-packages', 'platlib': '...'}``. This makes it possible to
|
|
||||||
use relative paths to the source code, which might help the interpreter find
|
|
||||||
the package after the root path changes with ``chroot`` or similar.
|
|
||||||
|
|
||||||
Must build a ``.whl`` file, and place it in the specified ``wheel_directory``.
|
Must build a ``.whl`` file, and place it in the specified ``wheel_directory``.
|
||||||
It must return the basename (not the full path) of the .whl file it creates, as
|
It must return the basename (not the full path) of the .whl file it creates, as
|
||||||
a unicode string.
|
a unicode string.
|
||||||
|
@ -114,11 +109,11 @@ Build-backends must produce wheels that have the same dependencies
|
||||||
with the exception that they can add dependencies necessary for their editable
|
with the exception that they can add dependencies necessary for their editable
|
||||||
mechanism to function at runtime (such as `editables`_).
|
mechanism to function at runtime (such as `editables`_).
|
||||||
|
|
||||||
The filename for the “editable” wheel needs to be PEP 427 compliant too. It
|
The filename for the "editable" wheel needs to be PEP 427 compliant too. It
|
||||||
does not need to use the same tags as ``build_wheel`` but it must be tagged as
|
does not need to use the same tags as ``build_wheel`` but it must be tagged as
|
||||||
compatible with the system.
|
compatible with the system.
|
||||||
|
|
||||||
An “editable” wheel uses the wheel format not for distribution but as ephemeral
|
An "editable" wheel uses the wheel format not for distribution but as ephemeral
|
||||||
communication between the build system and the front end. This avoids having
|
communication between the build system and the front end. This avoids having
|
||||||
the build backend install anything directly. This wheel must not be exposed
|
the build backend install anything directly. This wheel must not be exposed
|
||||||
to end users, nor cached, nor distributed.
|
to end users, nor cached, nor distributed.
|
||||||
|
@ -142,7 +137,8 @@ If not defined, the default implementation is equivalent to ``return []``.
|
||||||
What to put in the wheel
|
What to put in the wheel
|
||||||
------------------------
|
------------------------
|
||||||
|
|
||||||
Build backends may use different techniques to achive the goals of an editable
|
Build backends must populate the generated wheel with files that when installed will result in an editable install.
|
||||||
|
Build backends may use different techniques to achieve the goals of an editable
|
||||||
install. This section provides examples and is not normative.
|
install. This section provides examples and is not normative.
|
||||||
|
|
||||||
* Build backends may choose to place a ``.pth`` file at the root of the ``.whl`` file,
|
* Build backends may choose to place a ``.pth`` file at the root of the ``.whl`` file,
|
||||||
|
@ -157,11 +153,21 @@ install. This section provides examples and is not normative.
|
||||||
a path importable, often including the project's own ``setup.py`` and other
|
a path importable, often including the project's own ``setup.py`` and other
|
||||||
scripts that would not be part of a normal installation. The proxy strategy
|
scripts that would not be part of a normal installation. The proxy strategy
|
||||||
can achieve a higher level of fidelity than path-based methods.
|
can achieve a higher level of fidelity than path-based methods.
|
||||||
|
* Symbolic links are another useful mechanism to realize editable installs.
|
||||||
|
Since, at the time this writing, the ``wheel`` specification does not support
|
||||||
|
symbolic links, they are not directly usable to set-up symbolic links in the
|
||||||
|
target environment. It is however possible for the backend to create a
|
||||||
|
symlink structure in some ``build`` directory of the source tree, and add
|
||||||
|
that directory to the python path via a ``.pth`` file in the "editable"
|
||||||
|
wheel. If some files linked in this manner depend on python implementation or
|
||||||
|
version, ABI or platform, care must be taken to generate the link structure
|
||||||
|
in different directories depending on compatibility tags, so the same project
|
||||||
|
tree can be installed in editable mode in multiple environments.
|
||||||
|
|
||||||
Frontend requirements
|
Frontend requirements
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
Frontends must install editable wheels in the same way as regular wheels.
|
Frontends must install "editable" wheels in the same way as regular wheels.
|
||||||
This also means uninstallation of editables does not require any special treatment.
|
This also means uninstallation of editables does not require any special treatment.
|
||||||
|
|
||||||
Frontends must create a ``direct_url.json`` file in the ``.dist-info``
|
Frontends must create a ``direct_url.json`` file in the ``.dist-info``
|
||||||
|
@ -186,15 +192,73 @@ Frontends must not expose the wheel obtained from ``build_wheel_for_editable``
|
||||||
to end users. The wheel must be discarded after installation and must not be
|
to end users. The wheel must be discarded after installation and must not be
|
||||||
cached nor distributed.
|
cached nor distributed.
|
||||||
|
|
||||||
|
Limitations
|
||||||
|
===========
|
||||||
|
|
||||||
|
With regard to the wheel ``.data`` directory, this PEP focuses on making the
|
||||||
|
``purelib`` and ``platlib`` categories (installed into site-packages)
|
||||||
|
"editable". It does not make special provision for the other categories such as
|
||||||
|
``headers``, ``data`` and ``scripts``. Package authors are encouraged to use
|
||||||
|
``console_scripts``, make their ``scripts`` tiny wrappers around library
|
||||||
|
functionality, or manage these from the source checkout during development.
|
||||||
|
|
||||||
Rejected ideas
|
Rejected ideas
|
||||||
==============
|
==============
|
||||||
|
|
||||||
|
``editable`` local version identifier
|
||||||
|
-------------------------------------
|
||||||
|
|
||||||
The ideas of having build backends append or modify the local version
|
The ideas of having build backends append or modify the local version
|
||||||
identifier to include the ``editable`` string has been rejected because it
|
identifier to include the ``editable`` string has been rejected because it
|
||||||
would not satisfy ``==`` version speicifier that include the local version
|
would not satisfy ``==`` version speicifier that include the local version
|
||||||
identifier. In other workds ``pkg==1.0+local`` is not satisfied by version
|
identifier. In other words ``pkg==1.0+local`` is not satisfied by version
|
||||||
``1.0+local.editable``.
|
``1.0+local.editable``.
|
||||||
|
|
||||||
|
Virtual wheel
|
||||||
|
-------------
|
||||||
|
|
||||||
|
Another approach was proposed in PEP 662, where
|
||||||
|
the build backend returns a mapping from source files and directories to the
|
||||||
|
installed layout. It is then up to the installer frontend to realize the
|
||||||
|
editable installation by whatever means it deems adequate for its users.
|
||||||
|
|
||||||
|
In terms of capabilities, both proposals provide the core "editable" feature.
|
||||||
|
|
||||||
|
The key difference is that PEP 662 leaves it to the frontend to decide how the
|
||||||
|
editable installation will be realized, while with this PEP, the choice must be
|
||||||
|
made by the backend. Both approaches can in principle provide several editable
|
||||||
|
installation methods for a given project, and let the developer choose one at
|
||||||
|
install time.
|
||||||
|
|
||||||
|
At the time of writing this PEP, it is clear that the community has a wide
|
||||||
|
range of theoretical and practical expectations about editable installs. The
|
||||||
|
reality is that the only one there is wide experience with is path insertion
|
||||||
|
via .pth (i.e. what setup.py develop does).
|
||||||
|
|
||||||
|
We believe that PEP 660 better addresses these "unknown unknowns" today in the
|
||||||
|
most reliable way, by letting project authors select the backend or implement
|
||||||
|
the method that provides the editable mechanism that best suit their
|
||||||
|
requirements, and test it works correctly. Since the frontend has no latitude
|
||||||
|
in *how* to install the "editable" wheel, in case of issue, there is only one
|
||||||
|
place to investigate: the build backend.
|
||||||
|
|
||||||
|
With PEP 662, issues need to be investigated in the frontend,
|
||||||
|
the backend and possiblty the specification. There is also a high probability
|
||||||
|
that different frontends, implementing the specification in different ways,
|
||||||
|
will produce installations that behave differently than project authors
|
||||||
|
intended, creating confusion, or worse, projects that only work with specific
|
||||||
|
frontends or IDEs.
|
||||||
|
|
||||||
|
Unpacked wheel
|
||||||
|
--------------
|
||||||
|
|
||||||
|
A `prototype <https://github.com/pypa/pip/pull/8154/files>`_ was made that
|
||||||
|
created an unpacked wheel in a temporary directory, to be copied to the target
|
||||||
|
environment by the frontend. This approach was not pursued because a wheel
|
||||||
|
archive is easy to create for the backend, and using a wheel as communication
|
||||||
|
mechanism is a better fit with the PEP 517 philosophy, and therefore keeps
|
||||||
|
things simpler for the frontend.
|
||||||
|
|
||||||
References
|
References
|
||||||
==========
|
==========
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue