PEP 517: Add hook for sdist build deps (#297)

- Add get_build_sdist_requires
- Rename hooks that had become ambiguous given
  two distinct build hooks
- Clarify expected environments for the various hooks

pep-0517.txt

@@ -166,14 +166,14 @@ The build backend object is expected to have attributes which provide
 some or all of the following hooks. The common ``config_settings``
 argument is described after the individual hooks::
 
-  def get_build_requires(config_settings):
+  def get_build_wheel_requires(config_settings):
       ...
 
 This hook MUST return an additional list of strings containing PEP 508
 dependency specifications, above and beyond those specified in the
-``pyproject.toml`` file. Example::
+``pyproject.toml`` file, to be installed when building a wheel. Example::
 
-  def get_build_requires(config_settings):
+  def get_build_wheel_requires(config_settings):
       return ["wheel >= 0.25", "setuptools"]
 
 Optional. If not defined, the default implementation is equivalent to
@@ -202,6 +202,32 @@ Optional. If a build frontend needs this information and the method is
 not defined, it should call ``build_wheel`` and look at the resulting
 metadata directly.
 
+::
+
+  def prepare_wheel_build_files(build_directory, config_settings):
+      ...
+
+Must copy or create any files needed to build a wheel of this package into
+``build_directory``. For instance, ``pyproject.toml`` should
+be copied unmodified into the root of this directory. For tools such
+as `setuptools_scm <https://github.com/pypa/setuptools_scm>`_, this may include
+extracting some information from a version control system.
+The ``build_wheel`` hook will subsequently be run from the ``build_directory``
+populated by this hook. The contents of the resulting wheel should be the same
+whether ``build_wheel`` is invoked in an original source directory, the build
+directory populated by this hook, or an unpacked sdist directory.
+
+Because the wheel will be built from a temporary build directory, ``build_wheel``
+may create intermediate files in the working directory, and does not need to
+take care to clean them up.
+
+The return value will be ignored.
+
+Optional. If this hook is not defined, frontends may call ``build_sdist``
+and unpack the archive to use as a build directory. Backends in which
+building an sdist has additional requirements should define
+``prepare_wheel_build_files``.
+
 ::
 
   def build_wheel(wheel_directory, config_settings, metadata_directory=None):
@@ -223,6 +249,19 @@ creates, as a unicode string.
 
 Mandatory.
 
+::
+
+  def get_build_sdist_requires(config_settings):
+    ...
+
+This hook MUST return an additional list of strings containing PEP 508
+dependency specifications, above and beyond those specified in the
+``pyproject.toml`` file. These dependencies will be installed for building an
+sdist.
+
+Optional. If not defined, the default implementation is equivalent to
+``return []``.
+
 ::
 
   def build_sdist(sdist_directory, config_settings):
@@ -252,32 +291,6 @@ creates, as a unicode string.
 Mandatory, but it may not succeed in all situations: for instance, some tools
 can only build an sdist from a VCS checkout.
 
-::
-
-  def prepare_build_files(build_directory, config_settings):
-      ...
-
-Must copy or create any files needed to build a wheel of this package into
-``build_directory``. For instance, ``pyproject.toml`` should
-be copied unmodified into the root of this directory. For tools such
-as `setuptools_scm <https://github.com/pypa/setuptools_scm>`_, this may include
-extracting some information from a version control system.
-The ``build_wheel`` hook will subsequently be run from the ``build_directory``
-populated by this hook. The contents of the resulting wheel should be the same
-whether ``build_wheel`` is invoked in an original source directory, the build
-directory populated by this hook, or an unpacked sdist directory.
-
-Because the wheel will be built from a temporary build directory, ``build_wheel``
-may create intermediate files in the working directory, and does not need to
-take care to clean them up.
-
-The return value will be ignored.
-
-Optional. If this hook is not defined, frontends may call ``build_sdist``
-and unpack the archive to use as a build directory. Backends in which
-building an sdist has additional requirements should define
-``prepare_build_files``.
-
 .. note:: Editable installs
 
    This PEP originally specified another hook, ``install_editable``, to do an
@@ -359,13 +372,18 @@ following criteria:
 - All requirements specified by the project's build-requirements must
   be available for import from Python. In particular:
 
-  - The ``get_build_requires`` hook is executed in an environment
+  - The ``get_build_wheel_requires`` and ``get_build_sdist_requires`` hooks are
-    which contains the bootstrap requirements specified in the
+    executed in an environment which contains the bootstrap requirements
-    ``pyproject.toml`` file.
+    specified in the ``pyproject.toml`` file.
 
-  - All other hooks are executed in an environment which contains both
+  - The ``prepare_wheel_metadata``, ``prepare_wheel_build_files`` and
-    the bootstrap requirements specified in the ``pyproject.toml``
+    ``build_wheel`` hooks are executed in an environment which contains the
-    hook and those specified by the ``get_build_requires`` hook.
+    bootstrap requirements from ``pyproject.toml`` and those specified by the
+    ``get_build_wheel_requires`` hook.
+
+  - The ``build_sdist`` hook is executed in an environment which contains the
+    bootstrap requirements from ``pyproject.toml`` and those specified by the
+    ``get_build_sdist_requires`` hook.
 
 - This must remain true even for new Python subprocesses spawned by
   the build environment, e.g. code like::