From d9203698145fb3f079327c2a51006d1e9f91afa5 Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Wed, 8 Nov 2023 16:36:18 +0100 Subject: [PATCH 1/8] Move declaring-build-dependencies.rst verbatim into declaring-project-metadata.rst --- .../declaring-build-dependencies.rst | 105 ------------------ .../declaring-project-metadata.rst | 104 +++++++++++++++++ source/specifications/index.rst | 1 - 3 files changed, 104 insertions(+), 106 deletions(-) delete mode 100644 source/specifications/declaring-build-dependencies.rst diff --git a/source/specifications/declaring-build-dependencies.rst b/source/specifications/declaring-build-dependencies.rst deleted file mode 100644 index 1d8045eda..000000000 --- a/source/specifications/declaring-build-dependencies.rst +++ /dev/null @@ -1,105 +0,0 @@ - -.. _declaring-build-dependencies: - -=================================== -Declaring build system dependencies -=================================== - -The ``pyproject.toml`` file is written in `TOML `_. -Among other metadata (such as :ref:`project metadata `), -it declares any Python level dependencies that must be installed in order to -run the project's build system successfully. - -.. TODO: move this sentence elsewhere - -Tables not defined by PyPA specifications are reserved for future use. - - -build-system table ------------------- - -.. 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 `. - -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. - - -.. TODO: move elsewhere - -.. _pyproject-tool-table: - -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 `_ 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. - -JSON Schema ------------ - -To provide a type-specific representation of the resulting data from -the TOML file for illustrative purposes only, the following -`JSON Schema `_ would match the data format: - -.. code-block:: json - - { - "$schema": "http://json-schema.org/schema#", - - "type": "object", - "additionalProperties": false, - - "properties": { - "build-system": { - "type": "object", - "additionalProperties": false, - - "properties": { - "requires": { - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": ["requires"] - }, - - "tool": { - "type": "object" - } - } - } diff --git a/source/specifications/declaring-project-metadata.rst b/source/specifications/declaring-project-metadata.rst index 0c1070b68..8d7186a46 100644 --- a/source/specifications/declaring-project-metadata.rst +++ b/source/specifications/declaring-project-metadata.rst @@ -16,6 +16,110 @@ specification as the canonical source for the format used. :ref:`writing-pyproject-toml`. +.. _declaring-build-dependencies: + +=================================== +Declaring build system dependencies +=================================== + +The ``pyproject.toml`` file is written in `TOML `_. +Among other metadata (such as :ref:`project metadata `), +it declares any Python level dependencies that must be installed in order to +run the project's build system successfully. + +.. TODO: move this sentence elsewhere + +Tables not defined by PyPA specifications are reserved for future use. + +build-system table +------------------ + +.. 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 `. + +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. + + +.. TODO: move elsewhere + +.. _pyproject-tool-table: + +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 `_ 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. + +JSON Schema +----------- + +To provide a type-specific representation of the resulting data from +the TOML file for illustrative purposes only, the following +`JSON Schema `_ would match the data format: + +.. code-block:: json + + { + "$schema": "http://json-schema.org/schema#", + + "type": "object", + "additionalProperties": false, + + "properties": { + "build-system": { + "type": "object", + "additionalProperties": false, + + "properties": { + "requires": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": ["requires"] + }, + + "tool": { + "type": "object" + } + } + } + Specification ============= diff --git a/source/specifications/index.rst b/source/specifications/index.rst index fb1a1fee2..a68dd11db 100644 --- a/source/specifications/index.rst +++ b/source/specifications/index.rst @@ -19,7 +19,6 @@ Package Distribution Metadata core-metadata version-specifiers dependency-specifiers - declaring-build-dependencies declaring-project-metadata inline-script-metadata platform-compatibility-tags From 54cb4157d0f8d2f3d2ddf9f92b5f643caf0953c4 Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Tue, 14 Nov 2023 22:06:56 +0100 Subject: [PATCH 2/8] Link to pyproject.toml guide (instead of specification) in packaging flow doc --- source/flow.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/source/flow.rst b/source/flow.rst index 974cfd6e9..947c399db 100644 --- a/source/flow.rst +++ b/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 ` - (name, version, author and so forth); see - :doc:`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 ` for a +complete guide to ``pyproject.toml`` configuration. -* a ``[tool]`` table containing tool-specific configuration options Build artifacts =============== From 39d6b779b58156fee3d194e41c96c2b217b46aee Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Tue, 14 Nov 2023 22:08:56 +0100 Subject: [PATCH 3/8] Rename "Declaring project metadata" to "pyproject.toml specification" to match new content Adjust references accordingly. --- source/specifications/index.rst | 2 +- ...{declaring-project-metadata.rst => pyproject-toml.rst} | 8 ++++---- source/specifications/source-distribution-format.rst | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) rename source/specifications/{declaring-project-metadata.rst => pyproject-toml.rst} (99%) diff --git a/source/specifications/index.rst b/source/specifications/index.rst index a68dd11db..6e8af699e 100644 --- a/source/specifications/index.rst +++ b/source/specifications/index.rst @@ -19,9 +19,9 @@ Package Distribution Metadata core-metadata version-specifiers dependency-specifiers - declaring-project-metadata inline-script-metadata platform-compatibility-tags + pyproject-toml Package Installation Environment Metadata ----------------------------------------- diff --git a/source/specifications/declaring-project-metadata.rst b/source/specifications/pyproject-toml.rst similarity index 99% rename from source/specifications/declaring-project-metadata.rst rename to source/specifications/pyproject-toml.rst index 8d7186a46..2d6200ffb 100644 --- a/source/specifications/declaring-project-metadata.rst +++ b/source/specifications/pyproject-toml.rst @@ -1,8 +1,8 @@ -.. _declaring-project-metadata: +.. _pyproject-toml-spec: -========================== -Declaring project metadata -========================== +================================ +``pyproject.toml`` specification +================================ :pep:`621` specifies how to write a project's :ref:`core metadata ` in a ``pyproject.toml`` file for diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst index 8ef55df96..55737dc07 100644 --- a/source/specifications/source-distribution-format.rst +++ b/source/specifications/source-distribution-format.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. From 66460e3661beb2128d7169f42e3b90b16524600c Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Tue, 14 Nov 2023 22:11:11 +0100 Subject: [PATCH 4/8] pyproject.toml spec: Update history and move to the end --- source/specifications/pyproject-toml.rst | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst index 2d6200ffb..7f9907a29 100644 --- a/source/specifications/pyproject-toml.rst +++ b/source/specifications/pyproject-toml.rst @@ -4,17 +4,14 @@ ``pyproject.toml`` specification ================================ -:pep:`621` specifies how to write a project's -:ref:`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. - .. 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). .. _declaring-build-dependencies: @@ -444,4 +441,12 @@ provided via tooling later on. +History +======= + +This specification was originally defined in :pep:`518` (``[build-system]`` +and ``[tool]`` tables) and :pep:`621` (``[project]`` table). + + + .. _TOML: https://toml.io From 441d38e535a2e16e16b7b1293d5c5634e84ab27d Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Tue, 14 Nov 2023 22:16:03 +0100 Subject: [PATCH 5/8] pyproject.toml specification: Harmonize structure Move the description of the tool table to its own section, and use consistent titles and labels. --- source/specifications/pyproject-toml.rst | 59 +++++++++++------------- 1 file changed, 28 insertions(+), 31 deletions(-) diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst index 7f9907a29..03e617d97 100644 --- a/source/specifications/pyproject-toml.rst +++ b/source/specifications/pyproject-toml.rst @@ -13,11 +13,11 @@ The ``pyproject.toml`` file acts as a configuration file for packaging-related tools (as well as other tools). -.. _declaring-build-dependencies: -=================================== -Declaring build system dependencies -=================================== +.. _pyproject-build-system-table: + +Declaring build system dependencies: the ``[build-system]`` table +================================================================= The ``pyproject.toml`` file is written in `TOML `_. Among other metadata (such as :ref:`project metadata `), @@ -28,9 +28,6 @@ run the project's build system successfully. Tables not defined by PyPA specifications are reserved for future use. -build-system table ------------------- - .. TODO: merge with PEP 517 The ``[build-system]`` table is used to store build-related data. @@ -61,28 +58,6 @@ If the table is specified but is missing required fields then the tool should consider it an error. -.. TODO: move elsewhere - -.. _pyproject-tool-table: - -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 `_ 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. - -JSON Schema ------------ - To provide a type-specific representation of the resulting data from the TOML file for illustrative purposes only, the following `JSON Schema `_ would match the data format: @@ -117,8 +92,11 @@ the TOML file for illustrative purposes only, the following } } -Specification -============= + +.. _pyproject-project-table: + +Declaring project metadata: the ``[project]`` table +=================================================== There are two kinds of metadata: *static* and *dynamic*. Static metadata is specified in the ``pyproject.toml`` file directly and @@ -441,6 +419,25 @@ 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 `_ 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 ======= From d1a760af196df564fc943980823983ad130e8e1a Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Tue, 14 Nov 2023 22:20:16 +0100 Subject: [PATCH 6/8] pyproject.toml spec: Further harmonize --- source/specifications/pyproject-toml.rst | 27 +++++++++++------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst index 03e617d97..d484ad040 100644 --- a/source/specifications/pyproject-toml.rst +++ b/source/specifications/pyproject-toml.rst @@ -13,20 +13,21 @@ The ``pyproject.toml`` file acts as a configuration file for packaging-related tools (as well as other tools). +The ``pyproject.toml`` file is written in `TOML `_. Three +tables are currently specified, namely +:ref:`[build-system] `, +:ref:`[project] ` and +:ref:`[tool] `. 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 ``pyproject.toml`` file is written in `TOML `_. -Among other metadata (such as :ref:`project metadata `), -it declares any Python level dependencies that must be installed in order to -run the project's build system successfully. - -.. TODO: move this sentence elsewhere - -Tables not defined by PyPA specifications are reserved for future use. +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 @@ -37,7 +38,7 @@ of strings representing dependencies required to execute the build system. The strings in this list follow the :ref:`version specifier specification `. -An example ``build-system`` table for a project built with +An example ``[build-system]`` table for a project built with ``setuptools`` is: .. code-block:: toml @@ -98,6 +99,8 @@ the TOML file for illustrative purposes only, the following Declaring project metadata: the ``[project]`` table =================================================== +The ``[project]`` table specifies the project's :ref:`core metadata `. + There are two kinds of metadata: *static* and *dynamic*. Static metadata is specified in the ``pyproject.toml`` file directly and cannot be specified or changed by a tool (this includes data @@ -106,12 +109,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 `. The lack of a ``[project]`` table implicitly means the :term:`build backend ` will dynamically provide all keys. From 6513f06d2636c96f8275884da27d650c3e7d3125 Mon Sep 17 00:00:00 2001 From: Jean Abou-Samra Date: Wed, 15 Nov 2023 11:53:41 +0100 Subject: [PATCH 7/8] Stray space Co-authored-by: Carol Willing --- source/specifications/pyproject-toml.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst index d484ad040..91ad8e4ce 100644 --- a/source/specifications/pyproject-toml.rst +++ b/source/specifications/pyproject-toml.rst @@ -32,7 +32,7 @@ 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 +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 From 17eacbada0c5321fb3c3782f683b128b4e714d9c Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Thu, 16 Nov 2023 00:30:50 +0100 Subject: [PATCH 8/8] Add note about original PEPs --- source/specifications/pyproject-toml.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/specifications/pyproject-toml.rst b/source/specifications/pyproject-toml.rst index 91ad8e4ce..21cd2340d 100644 --- a/source/specifications/pyproject-toml.rst +++ b/source/specifications/pyproject-toml.rst @@ -13,6 +13,8 @@ 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 `_. Three tables are currently specified, namely :ref:`[build-system] `,