WIP: Add sdist format specification and metadata field (PEP 643)

source/specifications/binary-distribution-format.rst

@@ -0,0 +1,8 @@
+
+.. _binary-distribution-format:
+
+==========================
+Binary distribution format
+==========================
+
+The binary distribution format (:term:`wheel <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
 
 
 .. _core-metadata-name:
@@ -86,6 +83,36 @@ Example::
     Version: 1.0a2
 
 
+Dynamic (multiple use)
+======================
+
+.. versionadded:: 2.2
+
+A string containing the name of another core metadata field. The field
+names ``Name`` and ``Version`` may not be specified in this field.
+
+When found in the metadata of a source distribution, the following
+rules apply:
+
+1. If a field is *not* marked as ``Dynamic``, then the value of the field
+   in any wheel built from the sdist MUST match the value in the sdist.
+   If the field is not in the sdist, and not marked as ``Dynamic``, then
+   it MUST NOT be present in the wheel.
+2. If a field is marked as ``Dynamic``, it may contain any valid value in
+   a wheel built from the sdist (including not being present at all).
+
+If the sdist metadata version is older than version 2.2, then all fields should
+be treated as if they were specified with ``Dynamic`` (i.e. there are no special
+restrictions on the metadata of wheels built from the sdist).
+
+In any context other than a source distribution, ``Dynamic`` is for information
+only, and indicates that the field value was calculated at wheel build time,
+and may not be the same as the value in the sdist or in other wheels for the
+project.
+
+Full details of the semantics of ``Dynamic`` are described in :pep:`643`.
+
+
 Platform (multiple use)
 =======================
 

source/specifications/index.rst

@@ -20,12 +20,21 @@ Package Distribution Metadata
    dependency-specifiers
    declaring-build-dependencies
    declaring-project-metadata
-   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/source-distribution-format.rst

@@ -0,0 +1,49 @@
+
+.. _source-distribution-format:
+
+==========================
+Source distribution format
+==========================
+
+The current standard format of source distribution format is identified by the
+presence of a :file:`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
+:command:`setup.py sdist`. This document does not attempt to standardise this
+format, except to note that if a legacy source distribution contains a
+``PKG-INFO`` file using metadata version 2.2 or later, then it MUST follow
+the rules applicable to source distributions defined in 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) with ``-``
+characters replaced with ``_``, 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 :file:`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.