PEP 517: latest round of updates (#384)

* Backends can define UnsupportedOperation exc type
* More rejected alternatives
* Specify srcdir not on sys.path

pep-0517.txt

@@ -149,6 +149,12 @@ And we import ``module_path`` and then lookup
 ``module_path.object_path`` (or just ``module_path`` if
 ``object_path`` is missing).
 
+When importing the module path, we do *not* look in the directory containing the
+source tree, unless that would be on ``sys.path`` anyway (e.g. because it is
+specified in PYTHONPATH). Although Python automatically adds the working
+directory to ``sys.path`` in some situations, code to resolve the backend should
+not be affected by this.
+
 If the ``pyproject.toml`` file is absent, or the ``build-backend``
 key is missing, the source tree is not using this specification, and
 tools should fall back to running ``setup.py``.
@@ -194,13 +200,11 @@ Backends which do not provide the ``prepare_metadata_for_build_wheel`` hook may
 either silently ignore the ``metadata_directory`` parameter to ``build_wheel``,
 or else raise an exception when it is set to anything other than ``None``.
 
-Wheels built by this hook should, as far as possible, be equivalent to
-first building an sdist and then building a wheel from that sdist.
-Frontends which want to protect against backends violating this expectation
-may call ``build_sdist`` (see below) first, and then call ``build_wheel``
-in the unpacked sdist. But if build_sdist fails with NotImplementedError,
-they will fall back to calling build_wheel in the source directory,
-and rely on the backend to produce an equivalent wheel.
+To ensure that wheels from different sources are built the same way, frontends
+may call ``build_sdist`` first, and then call ``build_wheel`` in the unpacked
+sdist. But if the backend indicates that it is missing some requirements for
+creating an sdist (see below), the frontend will fall back to calling
+``build_wheel`` in the source directory.
 
 The source directory may be read-only. Backends should therefore be
 prepared to build without creating or modifying any files in the source
@@ -239,9 +243,16 @@ specifies UTF-8 based file names. This is not yet the default for the tarfile
 module shipped with Python 3.6, so backends using the tarfile module need to
 explicitly pass ``format=tarfile.PAX_FORMAT``.
 
-Frontends performing a local installation may want to produce an sdist as an
-intermediate, but are advised to be prepared to use a fallback if it fails, as
-e.g. some backends may require version control tools to build an sdist.
+Some backends may have extra requirements for creating sdists, such as version
+control tools. However, some frontends may prefer to make intermediate sdists
+when producing wheels, to ensure consistency.
+If the backend cannot produce an sdist because a dependency is missing, or
+for another well understood reason, it should raise an exception of a specific
+type which it makes available as ``UnsupportedOperation`` on the backend object.
+If the frontend gets this exception while building an sdist as an intermediate
+for a wheel, it should fall back to building a wheel directly.
+The backend does not need to define this exception type if it would never raise
+it.
 
 Optional hooks
 ==============
@@ -573,8 +584,22 @@ automatically upgrade packages to the new format:
   unpacked distribution will be more common than those requiring an archive.
 * We considered an extra hook to copy files to a build directory before invoking
   ``build_wheel``. Looking at existing build systems, we found that passing
-  a build directory into ``build_wheel`` makes more sense for many tools than
+  a build directory into ``build_wheel`` made more sense for many tools than
   pre-emptively copying files into a build directory.
+* The idea of passing ``build_wheel`` a build directory was then also deemed an
+  unnecessary complication. Build tools can use a temporary directory or a cache
+  directory to store intermediate files while building. If there is a need, a
+  frontend-controlled cache directory could be added in the future.
+* For ``build_sdist`` to signal a failure for an expected reason, various
+  options were debated at great length, including raising
+  ``NotImplementedError`` and returning either ``NotImplemented`` or ``None``.
+  Please do not attempt to reopen this discussion without an *extremely* good
+  reason, because we are quite tired of it.
+* Allowing the backend to be imported from files in the source tree would be
+  more consistent with the way Python imports often work. However, not allowing
+  this prevents confusing errors from clashing module names. Projects which
+  need to provide their own backend could use a special proxy backend which
+  loads the hooks from the source tree, so the flexibility is not lost.
 
 ===================================
  Appendix A: Comparison to PEP 516