Merge branch 'main' into ajnelson-nist-single-sourcing-version-warning

Author: ajnelson-nist

.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Test
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+
+      - name: pip cache
+        uses: actions/cache@v2
+        with:
+          path: ~/.cache/pip
+          key:
+            ${{ matrix.os }}-${{ matrix.python-version }}-${{ hashFiles('**/requirements.txt') }}-${{ hashFiles('noxfile.py') }}
+          restore-keys: |
+            ${{ matrix.os }}-${{ matrix.python-version }}-
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade nox virtualenv
+
+      - name: Nox build
+        run: |
+          python -m nox -s build

.travis.yml

@@ -1,4 +1,5 @@
 sphinx==3.2.0
 sphinx-autobuild==0.7.1
+sphinx-inline-tabs==2020.10.19b4
 git+https://github.com/python/python-docs-theme.git#egg=python-docs-theme
 git+https://github.com/pypa/pypa-docs-theme.git#egg=pypa-docs-theme

requirements.txt

@@ -34,6 +34,7 @@
     'sphinx.ext.extlinks',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
+    'sphinx_inline_tabs',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -375,6 +376,7 @@
     'python': ('https://docs.python.org/3', None),
     'python2': ('https://docs.python.org/2', None),
     'pip': ('https://pip.pypa.io/en/latest/', None),
+    'setuptools': ('https://setuptools.rtfd.io/en/latest/', None),
 }
 
 

source/conf.py

@@ -38,13 +38,13 @@ Get started
 Essential tools and concepts for working within the Python
 development ecosystem are covered in our :doc:`tutorials/index` section:
 
-* to learn how to install packages, see the
+* To learn how to install packages, see the
   :doc:`tutorial on installing packages <tutorials/installing-packages>`.
-* to learn how to manage dependencies in a version controlled project, see the
+* To learn how to manage dependencies in a version controlled project, see the
   :doc:`tutorial on managing application dependencies <tutorials/managing-dependencies>`.
-* to learn how to package and distribute your projects, see the
-  :doc:`tutorial on packaging and distributing <tutorials/packaging-projects>`
-* to get an overview of packaging options for Python libraries and
+* To learn how to package and distribute your projects, see the
+  :doc:`tutorial on packaging and distributing <tutorials/packaging-projects>`.
+* To get an overview of packaging options for Python libraries and
   applications, see the :doc:`Overview of Python Packaging <overview>`.
 
 
@@ -53,11 +53,11 @@ Learn more
 
 Beyond our :doc:`tutorials/index`, this guide has several other resources:
 
-* the :doc:`guides/index` section for walk throughs, such as
-  :doc:`guides/installing-using-linux-tools` or :doc:`guides/packaging-binary-extensions`
-* the :doc:`discussions/index` section for in-depth references on topics such as
-  :doc:`discussions/deploying-python-applications` or :doc:`discussions/pip-vs-easy-install`
-* the :doc:`specifications/index` section for packaging interoperability specifications
+* The :doc:`guides/index` section for walk throughs, such as
+  :doc:`guides/installing-using-linux-tools` or :doc:`guides/packaging-binary-extensions`.
+* The :doc:`discussions/index` section for in-depth references on topics such as
+  :doc:`discussions/deploying-python-applications` or :doc:`discussions/pip-vs-easy-install`.
+* The :doc:`specifications/index` section for packaging interoperability specifications.
 
 Additionally, there is a list of :doc:`other projects <key_projects>` maintained
 by members of the Python Packaging Authority.

source/index.rst

@@ -450,7 +450,7 @@ ride. This impression is mostly a byproduct of Python's
 versatility. Once you understand the natural boundaries between each
 packaging solution, you begin to realize that the varied landscape is
 a small price Python programmers pay for using one of the most
-balanced, flexible language available.
+balanced, flexible languages available.
 
 
 .. Editing notes:
@@ -503,7 +503,7 @@ balanced, flexible language available.
 
    - Avoid words that trivialize using JupyterLab
    such as “simply” or “just.” Tasks that developers find simple or
-   easy may not be for users."
+   easy may not be for users.
 
    Among other useful points. Read more here:
    https://jupyterlab.readthedocs.io/en/latest/developer/documentation.html

source/overview.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/binary-distribution-format.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)
 =======================