diff --git a/pep-0517.txt b/pep-0517.txt index 917767e93..4bdf212f3 100644 --- a/pep-0517.txt +++ b/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