Add sdist format specification and metadata field (PEP 643)

Author: pfmoore

source/specifications/binary-distribution-format.rst

@@ -0,0 +1,8 @@
+
+.. _binary-distribution-format:
+
+==========================
+Binary distribution format
+==========================
+
+The binary distribution format (``wheel``) is defined in :pep:`427`.

source/specifications/core-metadata.rst

@@ -4,10 +4,6 @@
 Core metadata specifications
 ============================
 
-The current core metadata file format, version 2.1, is specified in :pep:`566`.
-It defines the following specification as the canonical source for the core
-metadata file format.
-
 Fields defined in the following specification should be considered valid,
 complete and not subject to change. The required fields are:
 
@@ -32,7 +28,8 @@ Metadata-Version
 
 .. versionadded:: 1.0
 
-Version of the file format; legal values are "1.0", "1.1", "1.2" and "2.1".
+Version of the file format; legal values are "1.0", "1.1", "1.2", "2.1"
+and "2.2".
 
 Automated tools consuming metadata SHOULD warn if ``metadata_version`` is
 greater than the highest version they support, and MUST fail if
@@ -46,7 +43,7 @@ all of the needed fields.
 
 Example::
 
-    Metadata-Version: 2.1
+    Metadata-Version: 2.2
 
 
 Name
@@ -82,6 +79,30 @@ Example::
     Version: 1.0a2
 
 
+Dynamic (multiple use)
+======================
+
+.. versionadded:: 2.2
+
+Only permitted in source distribution (sdist) file metadata.
+
+A string containing the name of another core metadata field. Only the following
+metadata field names may be used as the value of the ``Dynamic`` field.
+
+* ``Platform``
+* ``Supported-Platform``
+* ``Requires-Dist``
+* ``Requires-External``
+* ``Provides-Extra``
+* ``Provides-Dist``
+* ``Obsoletes-Dist``
+
+Unless specified via ``Dynamic``, *all* metadata in a wheel must be identical to
+the metadata of the sdist from which the wheel was built. If a field is named in
+``Dynamic`` in the sdist, then there is no constraint on what value that field
+may have in wheels built from the sdist.
+
+
 Platform (multiple use)
 =======================
 

source/specifications/distribution-formats.rst

@@ -19,12 +19,21 @@ Package Distribution Metadata
    version-specifiers
    dependency-specifiers
    declaring-build-dependencies
-   distribution-formats
    platform-compatibility-tags
    recording-installed-packages
    entry-points
 
 
+Package Distribution File Formats
+---------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   source-distribution-format
+   binary-distribution-format
+
+
 Package Index Interfaces
 ------------------------
 

source/specifications/index.rst

@@ -0,0 +1,48 @@
+
+.. _source-distribution-format:
+
+==========================
+Source distribution format
+==========================
+
+The current standard format of source distribution format is identified by the
+presence of a ``pyproject.toml`` file in the distribution archive.  The layout
+of such a distribution was originally specified in :pep:`517` and is formally
+documented here.
+
+There is also the legacy source distribution format, implicitly defined by the
+behaviour of ``distutils`` module in the standard library, when executing
+``setup.py sdist``. This document does not attempt to standardise this format,
+except to note that if a legacy sdist contains a ``PKG-INFO`` file holding
+metadata version 2.2 or later, that sdist MUST follow the rules for sdists
+defined by the metadata specification.
+
+Source distributions are also known as *sdists* for short.
+
+Source distribution file name
+=============================
+
+The file name of a sdist is not currently standardised, although the *de facto*
+form is ``{name}-{version}.tar.gz``, where ``{name}`` is the canonicalized form
+of the project name (see :pep:`503` for the canonicalization rules) and
+``{version}`` is the project version.
+
+The name and version components of the filename MUST match the values stored
+in the metadata contained in the file.
+
+Source distribution file format
+===============================
+
+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 ``pyproject.toml`` in the format defined in
+:ref:`declaring-build-dependencies`, 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.
+
+No other content of a sdist is required or defined. Build systems can store
+whatever information they need in the sdist to build the project.
+
+The tarball should use the modern POSIX.1-2001 pax tar format, which specifies
+UTF-8 based file names.