219 lines
8.6 KiB
ReStructuredText
219 lines
8.6 KiB
ReStructuredText
PEP: 660
|
||
Title: Editable installs for PEP 517 style build backends
|
||
Author: Daniel Holth <dholth@gmail.com>, Stéphane Bidoul <stephane.bidoul@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
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Content-Type: text/x-rst
|
||
Created: 30-Mar-2021
|
||
Post-History:
|
||
|
||
|
||
Abstract
|
||
========
|
||
|
||
This document describes a PEP 517 style method for the installation of packages
|
||
in editable mode.
|
||
|
||
Motivation
|
||
==========
|
||
|
||
Python programmers want to be able to develop packages without having to
|
||
install (i.e. copy) them into ``site-packages``, for example, by working in a
|
||
checkout of the source repository.
|
||
|
||
While this can be done by adding the relevant source directories to
|
||
``PYTHONPATH``, ``setuptools`` provides the ``setup.py develop`` mechanism that
|
||
makes the process easier, and also installs dependencies and entry points such
|
||
as console scripts. ``pip`` exposes this mechanism via its ``pip install
|
||
--editable`` option.
|
||
|
||
The installation of projects in such a way that the python code being
|
||
imported remains in the source directory is known as the *editable*
|
||
installation mode.
|
||
|
||
Now that PEP 517 provides a mechanism to create alternatives to setuptools, and
|
||
decouple installation front ends from build backends, we need a new mechanism
|
||
to install packages in editable mode.
|
||
|
||
Rationale
|
||
=========
|
||
|
||
PEP 517 deferred "Editable installs", meaning non-``setup.py``
|
||
distributions lacked that feature. The only way to retain ``editable`` installs
|
||
for these distributions was to provide a compatible ``setup.py develop``
|
||
implementation. By definining an editable hook other build frontends gain
|
||
parity with ``setup.py``.
|
||
|
||
Terminology and goals
|
||
=====================
|
||
|
||
The editable installation mode implies that the source code of the project
|
||
being installed is available in a local directory.
|
||
|
||
Once the project is installed in editable mode, users expect that changes to
|
||
the project *python* code in the local source tree become effective without the
|
||
need of a new installation step.
|
||
|
||
Some kind of changes, such as the addition or modification of entry points, or
|
||
the addition of new dependencies, require a new installation step to become
|
||
effective. These changes are typically made in build backend configuration
|
||
files (such as ``pyproject.toml``), so it is consistent with the general user
|
||
expectation that *python* source code is imported from the source tree.
|
||
|
||
The modification of non-python source code such a C extension modules obviously
|
||
require a compilation and/or installation step to become effective. The exact
|
||
steps to perform will remain specific to the build backend used.
|
||
|
||
When a project is installed in editable mode, users expect the installation to
|
||
behave identically as a regular installation. 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
|
||
=============
|
||
|
||
This PEP adds a single optional hook to the PEP 517 backend interface. The hook
|
||
is used to build a wheel that, when installed, allows that distribution to be
|
||
imported from its source folder.
|
||
|
||
build_wheel_for_editable
|
||
------------------------
|
||
|
||
::
|
||
|
||
def build_wheel_for_editable(
|
||
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``.
|
||
It must return the basename (not the full path) of the .whl file it creates, as
|
||
a unicode string.
|
||
|
||
May do an in-place build of the distribution as a side effect so that any
|
||
extension modules or other built artifacts are ready to be used.
|
||
|
||
The .whl file must comply with the Wheel binary file format specification (PEP
|
||
427). In particular it must contain a compliant .dist-info directory.
|
||
Metadata must be identical as the one that would have been produced by
|
||
``build_wheel`` or ``prepare_metadata_for_build_wheel``, except for
|
||
``Requires-Dist`` which may differ slightly as explained below.
|
||
|
||
Build-backends must produce wheels that have the same dependencies
|
||
(``Requires-Dist`` metadata) as wheels produced by the ``build_wheel`` hook,
|
||
with the exception that they can add dependencies necessary for their editable
|
||
mechanism to function at runtime (such as `editables`_).
|
||
|
||
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
|
||
compatible with the system.
|
||
|
||
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
|
||
the build backend install anything directly. This wheel must not be exposed
|
||
to end users, nor cached, nor distributed.
|
||
|
||
get_requires_for_build_wheel_for_editable
|
||
-----------------------------------------
|
||
|
||
::
|
||
|
||
def get_requires_for_build_wheel_for_editable(config_settings=None):
|
||
...
|
||
|
||
This hook MUST return an additional list of strings containing PEP 508
|
||
dependency specifications, above and beyond those specified in the
|
||
``pyproject.toml`` file, to be installed when calling the
|
||
``build_wheel_for_editable`` hooks.
|
||
|
||
If not defined, the default implementation is equivalent to ``return []``.
|
||
|
||
|
||
What to put in the wheel
|
||
------------------------
|
||
|
||
Build backends may use different techniques to achive the goals of an editable
|
||
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,
|
||
containing the root directory of the source tree. This approach is simple but
|
||
not very precise, although it may be considered good enough (especially when
|
||
using the ``src`` layout) and is similar to what ``setup.py develop``
|
||
currently does.
|
||
* The `editables`_ library shows how to build proxy modules that
|
||
provide a high quality editable installation. It accepts a list of modules
|
||
to include, and hide. When imported, these proxy modules replace themselves
|
||
with the code from the source tree. Path-based methods make all scripts under
|
||
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
|
||
can achieve a higher level of fidelity than path-based methods.
|
||
|
||
Frontend requirements
|
||
---------------------
|
||
|
||
Frontends must install editable wheels in the same way as regular wheels.
|
||
This also means uninstallation of editables does not require any special treatment.
|
||
|
||
Frontends must create a ``direct_url.json`` file in the ``.dist-info``
|
||
directory of the installed distribution, in compliance with PEP 610. The
|
||
``url`` value must be a ``file://`` url pointing to the project directory
|
||
(i.e. the directory containing ``pyproject.toml``), and the ``dir_info`` value
|
||
must be ``{'editable': true}``.
|
||
|
||
Frontends must execute ``get_requires_for_build_wheel_for_editable`` hooks in
|
||
an environment which contains the bootstrap requirements specified in the
|
||
``pyproject.toml`` file.
|
||
|
||
Frontends must execute the ``build_wheel_for_editable`` hook in an environment
|
||
which contains the bootstrap requirements from ``pyproject.toml`` and those
|
||
specified by the ``get_requires_for_build_wheel_for_editable`` hook.
|
||
|
||
Frontends must not rely on the ``prepare_metadata_for_build_wheel`` hook when
|
||
installing in editable mode. They must use ``build_wheel_for_editable`` and
|
||
inspect the resulting wheel.
|
||
|
||
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
|
||
cached nor distributed.
|
||
|
||
Rejected ideas
|
||
==============
|
||
|
||
The ideas of having build backends append or modify the local version
|
||
identifier to include the ``editable`` string has been rejected because it
|
||
would not satisfy ``==`` version speicifier that include the local version
|
||
identifier. In other workds ``pkg==1.0+local`` is not satisfied by version
|
||
``1.0+local.editable``.
|
||
|
||
References
|
||
==========
|
||
|
||
.. _`editables`: https://pypi.org/project/editables/
|
||
|
||
Copyright
|
||
=========
|
||
|
||
This document is placed in the public domain or under the
|
||
CC0-1.0-Universal license, whichever is more permissive.
|
||
|
||
|
||
|
||
..
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
sentence-end-double-space: t
|
||
fill-column: 70
|
||
coding: utf-8
|
||
End:
|