Merge pull request #1396 from jeanas/unified-pyroject-spec

A unified pyproject.toml specification

Author: pradyunsg

source/flow.rst

@@ -96,11 +96,13 @@ required in the :file:`pyproject.toml` file. For example, you might specify:
 
 * a ``[project]`` table containing project
   :doc:`Core Metadata </specifications/core-metadata/>`
-  (name, version, author and so forth); see
-  :doc:`Declaring project metadata </specifications/declaring-project-metadata/>`
-  for more detail
+  (name, version, author and so forth),
+
+* a ``[tool]`` table containing tool-specific configuration options.
+
+Refer to the :ref:`pyproject.toml guide <writing-pyproject-toml>` for a
+complete guide to ``pyproject.toml`` configuration.
 
-* a ``[tool]`` table containing tool-specific configuration options
 
 Build artifacts
 ===============

source/specifications/declaring-build-dependencies.rst

@@ -1,23 +1,107 @@
-.. _declaring-project-metadata:
+.. _pyproject-toml-spec:
 
-==========================
-Declaring project metadata
-==========================
-
-:pep:`621` specifies how to write a project's
-:ref:`core metadata <core-metadata>` in a ``pyproject.toml`` file for
-packaging-related tools to consume. It defines the following
-specification as the canonical source for the format used.
+================================
+``pyproject.toml`` specification
+================================
 
 .. warning::
 
    This is a **technical, formal specification**. For a gentle,
    user-friendly guide to ``pyproject.toml``, see
    :ref:`writing-pyproject-toml`.
 
+The ``pyproject.toml`` file acts as a configuration file for packaging-related
+tools (as well as other tools).
+
+.. note:: This specification was originally defined in :pep:`518` and :pep:`621`.
+
+The ``pyproject.toml`` file is written in `TOML <https://toml.io>`_. Three
+tables are currently specified, namely
+:ref:`[build-system] <pyproject-build-system-table>`,
+:ref:`[project] <pyproject-project-table>` and
+:ref:`[tool] <pyproject-tool-table>`. Other tables are reserved for future
+use (tool-specific configuration should use the ``[tool]`` table).
+
+.. _pyproject-build-system-table:
+
+Declaring build system dependencies: the ``[build-system]`` table
+=================================================================
+
+The ``[build-system]`` table declares any Python level dependencies that
+must be installed in order to run the project's build system
+successfully.
+
+.. TODO: merge with PEP 517
+
+The ``[build-system]`` table is used to store build-related data.
+Initially, only one key of the table is valid and is mandatory
+for the table: ``requires``. This key must have a value of a list
+of strings representing dependencies required to execute the
+build system. The strings in this list follow the :ref:`version specifier
+specification <version-specifiers>`.
+
+An example ``[build-system]`` table for a project built with
+``setuptools`` is:
+
+.. code-block:: toml
+
+   [build-system]
+   # Minimum requirements for the build system to execute.
+   requires = ["setuptools"]
+
+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. If the file exists but is lacking the ``[build-system]``
+table then the default values as specified above should be used.
+If the table is specified but is missing required fields then the tool
+should consider it an error.
+
+
+To provide a type-specific representation of the resulting data from
+the TOML file for illustrative purposes only, the following
+`JSON Schema <https://json-schema.org>`_ would match the data format:
+
+.. code-block:: json
+
+   {
+       "$schema": "http://json-schema.org/schema#",
 
-Specification
-=============
+       "type": "object",
+       "additionalProperties": false,
+
+       "properties": {
+           "build-system": {
+               "type": "object",
+               "additionalProperties": false,
+
+               "properties": {
+                   "requires": {
+                       "type": "array",
+                       "items": {
+                           "type": "string"
+                       }
+                   }
+               },
+               "required": ["requires"]
+           },
+
+           "tool": {
+               "type": "object"
+           }
+       }
+   }
+
+
+.. _pyproject-project-table:
+
+Declaring project metadata: the ``[project]`` table
+===================================================
+
+The ``[project]`` table specifies the project's :ref:`core metadata <core-metadata>`.
 
 There are two kinds of metadata: *static* and *dynamic*. Static
 metadata is specified in the ``pyproject.toml`` file directly and
@@ -27,12 +111,6 @@ by the metadata). Dynamic metadata is listed via the ``dynamic`` key
 (defined later in this specification) and represents metadata that a
 tool will later provide.
 
-The keys defined in this specification MUST be in a table named
-``[project]`` in ``pyproject.toml``. No tools may add keys to this
-table which are not defined by this specification. For tools wishing
-to store their own settings in ``pyproject.toml``, they may use the
-``[tool]`` table as defined in the
-:ref:`build dependency declaration specification <declaring-build-dependencies>`.
 The lack of a ``[project]`` table implicitly means the :term:`build backend <Build Backend>`
 will dynamically provide all keys.
 
@@ -340,4 +418,31 @@ provided via tooling later on.
 
 
 
+.. _pyproject-tool-table:
+
+Arbitrary tool configuration: the ``[tool]`` table
+==================================================
+
+The ``[tool]`` table is where any tool related to your Python
+project, not just build tools, can have users specify configuration
+data as long as they use a sub-table within ``[tool]``, e.g. the
+`flit <https://pypi.python.org/pypi/flit>`_ tool would store its
+configuration in ``[tool.flit]``.
+
+A mechanism is needed to allocate names within the ``tool.*``
+namespace, to make sure that different projects do not attempt to use
+the same sub-table and collide. Our rule is that a project can use
+the subtable ``tool.$NAME`` if, and only if, they own the entry for
+``$NAME`` in the Cheeseshop/PyPI.
+
+
+
+History
+=======
+
+This specification was originally defined in :pep:`518` (``[build-system]``
+and ``[tool]`` tables) and :pep:`621` (``[project]`` table).
+
+
+
 .. _TOML: https://toml.io

source/specifications/declaring-project-metadata.rst renamed to source/specifications/pyproject-toml.rst

@@ -9,7 +9,6 @@ Package Distribution Metadata
    core-metadata
    version-specifiers
    dependency-specifiers
-   declaring-build-dependencies
-   declaring-project-metadata
+   pyproject-toml
    inline-script-metadata
    platform-compatibility-tags

source/specifications/section-distribution-metadata.rst

@@ -58,7 +58,7 @@ A ``.tar.gz`` source distribution (sdist) contains a single top-level directory
 called ``{name}-{version}`` (e.g. ``foo-1.0``), containing the source files of
 the package. The name and version MUST match the metadata stored in the file.
 This directory must also contain a :file:`pyproject.toml` in the format defined in
-:ref:`declaring-build-dependencies`, and a ``PKG-INFO`` file containing
+:ref:`pyproject-toml-spec`, and a ``PKG-INFO`` file containing
 metadata in the format described in the :ref:`core-metadata` specification. The
 metadata MUST conform to at least version 2.2 of the metadata specification.