Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PEP 660: shorten names and add prepare_metadata_for_build_editable #2004

Merged
merged 1 commit into from Jun 25, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
66 changes: 49 additions & 17 deletions pep-0660.rst
Expand Up @@ -79,16 +79,16 @@ encouraged to document such potential differences.
The Mechanism
=============

This PEP adds two optional hooks to the PEP 517 backend interface. These hooks
This PEP adds three optional hooks to the PEP 517 backend interface. These hooks
are used to build a wheel that, when installed, allows that distribution to be
imported from its source folder.

build_wheel_for_editable
------------------------
build_editable
--------------

::

def build_wheel_for_editable(wheel_directory, config_settings=None):
def build_editable(wheel_directory, config_settings=None, metadata_directory=None):
...

Must build a ``.whl`` file, and place it in the specified ``wheel_directory``.
Expand All @@ -113,26 +113,61 @@ 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.

If the build frontend has previously called ``prepare_metadata_for_build_editable``
and depends on the wheel resulting from this call to have metadata
matching this earlier call, then it should provide the path to the created
``.dist-info`` directory as the ``metadata_directory`` argument. If this
argument is provided, then ``build_editable`` MUST produce a wheel with identical
metadata. The directory passed in by the build frontend MUST be
identical to the directory created by ``prepare_metadata_for_build_editable``,
including any unrecognized files it created.

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
-----------------------------------------
get_requires_for_build_editable
-------------------------------

::

def get_requires_for_build_wheel_for_editable(config_settings=None):
def get_requires_for_build_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.
``build_editable`` hooks.

If not defined, the default implementation is equivalent to ``return []``.

prepare_metadata_for_build_editable
-----------------------------------

::

def prepare_metadata_for_build_editable(metadata_directory, config_settings=None):
...

Must create a ``.dist-info`` directory containing wheel metadata
inside the specified ``metadata_directory`` (i.e., creates a directory
like ``{metadata_directory}/{package}-{version}.dist-info/``). This
directory MUST be a valid ``.dist-info`` directory as defined in the
wheel specification, except that it need not contain ``RECORD`` or
signatures. The hook MAY also create other files inside this
directory, and a build frontend MUST preserve, but otherwise ignore, such files;
the intention
here is that in cases where the metadata depends on build-time
decisions, the build backend may need to record these decisions in
some convenient format for re-use by the actual wheel-building step.

This must return the basename (not the full path) of the ``.dist-info``
directory it creates, as a unicode string.

If a build frontend needs this information and the method is
not defined, it should call ``build_editable`` and look at the resulting
metadata directly.

What to put in the wheel
------------------------
Expand Down Expand Up @@ -176,19 +211,16 @@ directory of the installed distribution, in compliance with PEP 610. The
(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
Frontends must execute ``get_requires_for_build_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 execute the ````prepare_metadata_for_build_editable`` and
``build_editable`` hooks in an environment which contains the bootstrap
requirements from ``pyproject.toml`` and those specified by the
``get_requires_for_build_editable`` hook.

Frontends must not expose the wheel obtained from ``build_wheel_for_editable``
Frontends must not expose the wheel obtained from ``build_editable``
to end users. The wheel must be discarded after installation and must not be
cached nor distributed.

Expand Down