Merge branch 'main' into added_obsolete

venthur · web-flow · commit 5b851433d90d · 2023-08-16T15:59:04.000+02:00
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -1,6 +1,6 @@
 name: Test
 
-on: 
+on:
   push:
   pull_request:
   schedule:
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,5 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.4.0
+  hooks:
+  - id: trailing-whitespace
diff --git a/noxfile.py b/noxfile.py
@@ -18,13 +18,14 @@ def translation(session):
     session.install("-r", "requirements.txt")
     target_dir = "locales"
     session.run(
-        "sphinx-build", 
+        "sphinx-build",
         "-b", "gettext",  # build gettext-style message catalogs (.pot file)
         "-d", ".nox/.doctrees/", # path to put the cache
         "source/",  # where the rst files are located
         target_dir, # where to put the .pot file
     )
 
+
 @nox.session()
 def build(session, autobuild=False):
     """
@@ -75,10 +76,24 @@ def linkcheck(session):
     """
     session.install("-r", "requirements.txt")
     session.run(
-        "sphinx-build", 
+        "sphinx-build",
         "-b", "linkcheck", # use linkcheck builder
         "--color",
         "-n", "-W", "--keep-going",  # be strict
         "source", # where the rst files are located
         "build", # where to put the check output
     )
+
+
+@nox.session()
+def checkqa(session):
+    """
+    Format the guide using pre-commit.
+    """
+    session.install("pre-commit")
+    session.run(
+        "pre-commit",
+        "run",
+        "--all-files",
+        "--show-diff-on-failure",
+    )
diff --git a/source/discussions/deploying-python-applications.rst b/source/discussions/deploying-python-applications.rst
@@ -92,12 +92,12 @@ py2exe
 ^^^^^^
 
 `py2exe <https://pypi.org/project/py2exe/>`__ is a distutils extension which
-allows to build standalone Windows executable programs (32-bit and 64-bit) 
-from Python scripts. Python versions included in the official development 
+allows to build standalone Windows executable programs (32-bit and 64-bit)
+from Python scripts. Python versions included in the official development
 cycle are supported (refers to `Status of Python branches`__). py2exe can
 build console executables and windows (GUI) executables. Building windows
 services, and DLL/EXE COM servers might work but it is not actively supported.
-The distutils extension is released under the MIT-licence and Mozilla 
+The distutils extension is released under the MIT-licence and Mozilla
 Public License 2.0.
 
 .. __: https://devguide.python.org/#status-of-python-branches
@@ -108,8 +108,8 @@ macOS
 py2app
 ^^^^^^
 
-`py2app <https://pypi.org/project/py2app/>`__ is a Python setuptools 
-command which will allow you to make standalone macOS application 
+`py2app <https://pypi.org/project/py2app/>`__ is a Python setuptools
+command which will allow you to make standalone macOS application
 bundles and plugins from Python scripts. Note that py2app MUST be used
 on macOS to build applications, it cannot create Mac applications on other
 platforms. py2app is released under the MIT-license.
@@ -120,11 +120,11 @@ Unix (including Linux and macOS)
 pex
 ^^^
 
-`pex <https://pypi.org/project/pex/>`__ is  a library for generating .pex 
-(Python EXecutable) files which are executable Python environments in the 
-spirit of virtualenvs. pex is an expansion upon the ideas outlined in :pep:`441` 
-and makes the deployment of Python applications as simple as cp. pex files may 
-even include multiple platform-specific Python distributions, meaning that a 
+`pex <https://pypi.org/project/pex/>`__ is  a library for generating .pex
+(Python EXecutable) files which are executable Python environments in the
+spirit of virtualenvs. pex is an expansion upon the ideas outlined in :pep:`441`
+and makes the deployment of Python applications as simple as cp. pex files may
+even include multiple platform-specific Python distributions, meaning that a
 single pex file can be portable across Linux and macOS. pex is released under the
 Apache License 2.0.
 
diff --git a/source/discussions/wheel-vs-egg.rst b/source/discussions/wheel-vs-egg.rst
@@ -44,6 +44,10 @@ Here's a breakdown of the important differences between :term:`Wheel` and :term:
   <https://docs.python.org/2/library/sysconfig.html#installation-paths>`_,
   therefore making it easier to convert to other formats.
 
+* :term:`Egg` uploads have been disabled for upload to PyPI, per :pep:`715`.
+  Read the `deprecation notice <https://blog.pypi.org/posts/2023-06-26-deprecate-egg-uploads/>`_
+  for more information.
+
 ----
 
 .. [1] Circumstantially, in some cases, wheels can be used as an importable
diff --git a/source/glossary.rst b/source/glossary.rst
@@ -42,7 +42,7 @@ Glossary
     Egg
 
         A :term:`Built Distribution` format introduced by :ref:`setuptools`,
-        which is being replaced by :term:`Wheel`.  For details, see 
+        which is being replaced by :term:`Wheel`.  For details, see
         :doc:`The Internal Structure of Python Eggs <setuptools:deprecated/python_eggs>` and
         `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_
 
diff --git a/source/guides/dropping-older-python-versions.rst b/source/guides/dropping-older-python-versions.rst
@@ -6,7 +6,7 @@ Dropping support for older Python versions
 
 Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a "Requires-Python" attribute.
 
-Metadata 1.2+ clients, such as Pip 9.0+, will adhere to this specification by matching the current Python runtime and comparing it with the required version 
+Metadata 1.2+ clients, such as Pip 9.0+, will adhere to this specification by matching the current Python runtime and comparing it with the required version
 in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime.
 
 This mechanism can be used to drop support for older Python versions, by amending the "Requires-Python" attribute in the package metadata.
@@ -102,8 +102,8 @@ metadata values based on the argument you provide in ``python_requires``.
 
 Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO.
 
-This file is generated by Distutils or :ref:`setuptools` when it generates the source package. 
-The file contains a set of keys and values, the list of keys is part of the PyPa standard metadata format. 
+This file is generated by Distutils or :ref:`setuptools` when it generates the source package.
+The file contains a set of keys and values, the list of keys is part of the PyPa standard metadata format.
 
 You can see the contents of the generated file like this:
 
@@ -113,7 +113,7 @@ You can see the contents of the generated file like this:
 
 Validate that the following is in place, before publishing the package:
 
-- If you have upgraded correctly, the Metadata-Version value should be 1.2 or higher. 
+- If you have upgraded correctly, the Metadata-Version value should be 1.2 or higher.
 - The Requires-Python field is set and matches your specification in setup.py.
 
 4. Using Twine to publish
diff --git a/source/guides/installing-stand-alone-command-line-tools.rst b/source/guides/installing-stand-alone-command-line-tools.rst
@@ -66,7 +66,7 @@ For example:
            \
              ^__^
              (oo)\_______
-             (__)\       )\/       
+             (__)\       )\/
                  ||     ||
                  ||----w |
 
diff --git a/source/guides/installing-using-linux-tools.rst b/source/guides/installing-using-linux-tools.rst
@@ -38,7 +38,7 @@ Fedora
   sudo dnf install python3-pip python3-wheel
 
 To learn more about Python in Fedora, please visit the `official Fedora docs`_,
-`Python Classroom`_ or `Fedora Loves Python`_. 
+`Python Classroom`_ or `Fedora Loves Python`_.
 
 .. _official Fedora docs: https://developer.fedoraproject.org/tech/languages/python/python-installation.html
 .. _Python Classroom: https://labs.fedoraproject.org/en/python-classroom/
@@ -54,7 +54,7 @@ To install pip and wheel for the system Python, there are two options:
 
 1. Enable the `EPEL repository <https://fedoraproject.org/wiki/EPEL>`_ using
    `these instructions
-   <https://docs.fedoraproject.org/en-US/epel/#how_can_i_use_these_extra_packages>`__. 
+   <https://docs.fedoraproject.org/en-US/epel/#how_can_i_use_these_extra_packages>`__.
    On EPEL 7, you can install pip and wheel like so:
 
    .. code-block:: bash
@@ -111,7 +111,7 @@ openSUSE
 ~~~~~~~~
 
   .. code-block:: bash
- 
+
     sudo zypper install python3-pip python3-setuptools python3-wheel
 
 
diff --git a/source/guides/making-a-pypi-friendly-readme.rst b/source/guides/making-a-pypi-friendly-readme.rst
@@ -58,7 +58,7 @@ such as ``text/plain``, ``text/x-rst`` (for reStructuredText), or ``text/markdow
          py -m pip install --user --upgrade setuptools wheel twine
 
    The minimum required versions of the respective tools are:
-   
+
     - ``setuptools >= 38.6.0``
     - ``wheel >= 0.31.0``
     - ``twine >= 1.11.0``
diff --git a/source/guides/packaging-binary-extensions.rst b/source/guides/packaging-binary-extensions.rst
@@ -169,7 +169,7 @@ wrapper modules up to date.
   for automatic wrapping with Cython. It also supports performance-oriented
   Python implementations that provide a CPython-like C-API, such as PyPy
   and Pyston.
-  
+
 * :doc:`pybind11 <pybind11:index>` is a pure C++11 library
   that provides a clean C++ interface to the CPython (and PyPy) C API. It
   does not require a pre-processing step; it is written entirely in
diff --git a/source/guides/packaging-namespace-packages.rst b/source/guides/packaging-namespace-packages.rst
@@ -9,7 +9,7 @@ single :term:`package <Import Package>` across multiple, separate
 have the following package structure:
 
 .. code-block:: text
-    
+
     mynamespace/
         __init__.py
         subpackage_a/
@@ -29,7 +29,7 @@ And you use this package in your code like so::
 Then you can break these sub-packages into two separate distributions:
 
 .. code-block:: text
-    
+
     mynamespace-subpackage-a/
         setup.py
         mynamespace/
diff --git a/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst b/source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst
@@ -138,7 +138,7 @@ Now, whenever you push a tagged commit to your Git repository remote
 on GitHub, this workflow will publish it to PyPI.
 And it'll publish any push to TestPyPI which is useful for
 providing test builds to your alpha users as well as making
-sure that your release pipeline remains healthy! 
+sure that your release pipeline remains healthy!
 
 
 .. _API token: https://pypi.org/help/#apitoken
diff --git a/source/guides/single-sourcing-package-version.rst b/source/guides/single-sourcing-package-version.rst
@@ -9,7 +9,7 @@ There are many techniques to maintain a single source of truth for the version
 number of your project:
 
 #.  Read the file in :file:`setup.py` and get the version. Example (from `pip setup.py
-    <https://github.com/pypa/pip/blob/main/setup.py#L11>`_)::
+    <https://github.com/pypa/pip/blob/main/setup.py>`_)::
 
         import codecs
         import os.path
diff --git a/source/key_projects.rst b/source/key_projects.rst
@@ -486,9 +486,7 @@ pdm
 `GitHub <https://github.com/pdm-project/pdm/>`__ |
 `PyPI <https://pypi.org/project/pdm>`__
 
-PDM is a modern Python package manager with :pep:`582` support. It installs and
-manages packages in a similar way to ``npm`` that doesn't need to create a
-:term:`virtual environment` at all. It also uses :term:`pyproject.toml` to store
+PDM is a modern Python package manager. It uses :term:`pyproject.toml` to store
 project metadata as defined in :pep:`621`.
 
 .. _pex:
diff --git a/source/specifications/binary-distribution-format.rst b/source/specifications/binary-distribution-format.rst
@@ -134,6 +134,23 @@ build tag
     the first item being the initial digits as an ``int``, and the
     second item being the remainder of the tag as a ``str``.
 
+    A common use-case for build numbers is rebuilding a binary
+    distribution due to a change in the build environment,
+    like when using the manylinux image to build
+    distributions using pre-release CPython versions.
+
+    .. warning::
+
+        Build numbers are not a part of the distribution version and thus are difficult
+        to reference externally, especially so outside the Python ecosystem of tools and standards.
+        A common case where a distribution would need to referenced externally is when
+        resolving a security vulnerability.
+
+        Due to this limitation, new distributions which need to be referenced externally
+        **should not** use build numbers when building the new distribution.
+        Instead a **new distribution version** should be created for such cases.
+
+
 language implementation and version tag
     E.g. 'py27', 'py2', 'py3'.
 
diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst
@@ -40,6 +40,8 @@ to a new format.
 .. contents:: Contents
    :local:
 
+.. _core-metadata-metadata-version:
+
 Metadata-Version
 ================
 
@@ -133,6 +135,7 @@ project.
 
 Full details of the semantics of ``Dynamic`` are described in :pep:`643`.
 
+.. _core-metadata-platform:
 
 Platform (multiple use)
 =======================
@@ -148,6 +151,7 @@ Examples::
     Platform: ObscureUnix
     Platform: RareDOS
 
+.. _core-metadata-supported-platform:
 
 Supported-Platform (multiple use)
 =================================
@@ -340,6 +344,7 @@ Example::
    easier to update the specification to match the de facto standard.
 
 .. _home-page-optional:
+.. _core-metadata-home-page:
 
 Home-page
 =========
@@ -352,6 +357,7 @@ Example::
 
     Home-page: http://www.example.com/~cschultz/bvote/
 
+.. _core-metadata-download-url:
 
 Download-URL
 ============
@@ -558,6 +564,7 @@ Examples::
     Requires-Python: >2.6,!=3.0.*,!=3.1.*
     Requires-Python: ~=2.6
 
+.. _core-metadata-requires-external:
 
 Requires-External (multiple use)
 ================================
@@ -682,6 +689,7 @@ as they're still potentially useful for informational purposes, and can
 also be used for their originally intended purpose in combination with
 a curated package repository.
 
+.. _core-metadata-provides-dist:
 
 Provides-Dist (multiple use)
 ----------------------------
@@ -723,6 +731,7 @@ Examples::
     Provides-Dist: AnotherProject (3.4)
     Provides-Dist: virtual_package; python_version >= "3.4"
 
+.. _core-metadata-obsoletes-dist:
 
 Obsoletes-Dist (multiple use)
 -----------------------------
diff --git a/source/specifications/direct-url-data-structure.rst b/source/specifications/direct-url-data-structure.rst
@@ -70,20 +70,20 @@ When ``url`` refers to a source archive or a wheel, the ``archive_info`` key
 MUST be present as a dictionary with the following keys:
 
 - A ``hashes`` key SHOULD be present as a dictionary mapping a hash name to a hex
-  encoded digest of the file. 
-  
+  encoded digest of the file.
+
   Multiple hashes can be included, and it is up to the consumer to decide what to do
   with multiple hashes (it may validate all of them or a subset of them, or nothing at
-  all). 
-  
-  These hash names SHOULD always be normalized to be lowercase. 
-  
+  all).
+
+  These hash names SHOULD always be normalized to be lowercase.
+
   Any hash algorithm available via ``hashlib`` (specifically any that can be passed to
   ``hashlib.new()`` and do not require additional parameters) can be used as a key for
   the hashes dictionary. At least one secure algorithm from
   ``hashlib.algorithms_guaranteed`` SHOULD always be included. At time of writing,
   ``sha256`` specifically is recommended.
-  
+
 - A deprecated ``hash`` key (type ``string``) MAY be present for backwards compatibility
   purposes, with value ``<hash-algorithm>=<expected-hash>``.
 
@@ -188,7 +188,7 @@ Bazaar
 
 Home page
 
-   _`https://bazaar.canonical.com` *(Not responding as of 5/2023)*
+   https://www.breezy-vcs.org/
 
 vcs command
 
diff --git a/source/specifications/index.rst b/source/specifications/index.rst
@@ -6,7 +6,7 @@ PyPA specifications
 This is a list of currently active interoperability specifications maintained
 by the Python Packaging Authority. The process for updating these standards,
 and for proposing new ones, is documented on
-`pypa.io <https://www.pypa.io/en/latest/specifications.html>`__.
+`pypa.io <https://www.pypa.io/en/latest/specifications/>`__.
 
 
 Package Distribution Metadata
diff --git a/source/specifications/simple-repository-api.rst b/source/specifications/simple-repository-api.rst
@@ -9,5 +9,5 @@ The current interface for querying available package versions and
 retrieving packages from an index server is defined in :pep:`503`,
 with the addition of "yank" support (allowing a kind of file deletion)
 in :pep:`592`, specifying the interface version provided
-by an index server in :pep:`629`, and providing package metadata 
+by an index server in :pep:`629`, and providing package metadata
 independently from a package in :pep:`658`.
diff --git a/source/specifications/source-distribution-format.rst b/source/specifications/source-distribution-format.rst
diff --git a/source/tutorials/creating-documentation.rst b/source/tutorials/creating-documentation.rst
diff --git a/source/tutorials/managing-dependencies.rst b/source/tutorials/managing-dependencies.rst

Original file line number	Diff line number	Diff line change
`@@ -66,7 +66,7 @@ For example:`
`66`	`66`	`\`
`67`	`67`	`^__^`
`68`	`68`	`(oo)\_______`
`69`		`- (__)\ )\/`
	`69`	`+ (__)\ )\/`
`70`	`70`	`\|\| \|\|`
`71`	`71`	`\|\|----w \|`
`72`	`72`