PEP 660: shorten names and add prepare_metadata_for_build_editable (GH-2004)

pep-0660.rst

@@ -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``.
@@ -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
 ------------------------
@@ -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 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 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``
+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.