Specify that the build-system table is optional

The 'requires' key in the build-system table is still required if the table is specified, though.
This commit is contained in:
Brett Cannon 2018-07-20 17:00:13 -07:00 committed by GitHub
parent 1ed3043948
commit af73627e58
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 37 additions and 17 deletions

View File

@ -21,11 +21,11 @@ Abstract
========
This PEP specifies how Python software packages should specify what
dependencies they have in order to execute their chosen build system.
As part of this specification, a new configuration file is introduced
for software packages to use to specify their build dependencies (with
the expectation that the same configuration file will be used for
future configuration details).
build dependencies they have in order to execute their chosen build
system. As part of this specification, a new configuration file is
introduced for software packages to use to specify their build
dependencies (with the expectation that the same configuration file
will be used for future configuration details).
Rationale
@ -87,7 +87,7 @@ of issues, such as:
may support different package formats or determine the latest
version differently.
This has cumulated in a situation where use of ``setup_requires``
This has culminated in a situation where use of ``setup_requires``
is rare, where projects tend to either simply copy and paste snippets
between ``setup.py`` files or they eschew it all together in favor
of simply documenting elsewhere what they expect the user to have
@ -119,11 +119,11 @@ To provide more context and motivation for this PEP, think of the
2. Installation of the build system.
3. Execute the build system.
This PEP covers step #2. It is fully expected that a future PEP will
cover step #3, including how to have the build system dynamically
specify more dependencies that the build system requires to perform
its job. The purpose of this PEP though, is to specify the minimal set
of requirements for the build system to simply begin execution.
This PEP covers step #2. PEP 517 covers step #3, including how to have
the build system dynamically specify more dependencies that the build
system requires to perform its job. The purpose of this PEP though, is
to specify the minimal set of requirements for the build system to
simply begin execution.
Specification
@ -143,8 +143,11 @@ already in use by the Rust community as part of their
Cargo package manager [#cargo]_ and in private email stated they have
been quite happy with their choice of TOML. A more thorough
discussion as to why various alternatives were not chosen can be read
in the `Other file formats`_ section.
in the `Other file formats`_ section. The authors do realize, though,
that choice of configuration file format is ultimately subjective and
a choice had to be made and the authors prefer TOML for this situation.
Below we list the tables that tools are expected to recognize/respect.
Tables not specified in this PEP are reserved for future use by other
PEPs.
@ -152,10 +155,10 @@ build-system table
------------------
The ``[build-system]`` table is used to store build-related data.
Initially only one key of the table will be valid and mandatory:
``requires``. This key must have a value of a list of strings
representing PEP 508 dependencies required to execute the build
system (currently that means what dependencies are required to
Initially only one key of the table will be valid and is mandatory
for the table: ``requires``. This key must have a value of a list
of strings representing PEP 508 dependencies required to execute the
build system (currently that means what dependencies are required to
execute a ``setup.py`` file).
For the vast majority of Python projects that rely upon setuptools,
@ -170,6 +173,23 @@ community at the moment, build tools are expected to use the example
configuration file above as their default semantics when a
``pyproject.toml`` file is not present.
Tools should not require the existence of the ``[build-system]``
table. A ``pyproject.toml`` file may be used to store configuration
details other than build-related data and thus lack a
``[build-system]`` table legitimately. It is up to the tool to decide
how to handle this case. Potential options are:
1. Act as if the ``pyproject.toml`` file does not exist.
2. Assume the table exists with the default values specified above.
While subtle, there is a difference in these two options depending on
whether the existence of a ``pyproject.toml`` file has special
significance to the tool (e.g. pip currently triggers build isolation
for a project when a ``pyproject.toml`` file is found). If help is
desired in choosing an option for a tool then this PEP suggests the
second option to help people move over to ``pyproject.toml`` files.
tool table
----------
@ -536,7 +556,7 @@ References
.. [#jsonschema] JSON Schema
(http://json-schema.org/)
.. [#file_formats] Nathaniel J. Smith's file format review
(https://gist.github.com/njsmith/78f68204c5d969f8c8bc645ef77d4a8f)