Merge branch 'main' into added_obsolete

Author: venthur

.github/workflows/test.yml

@@ -17,21 +17,14 @@ jobs:
         - linkcheck
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         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 }}-
+          cache: 'pip'
+          cache-dependency-path: 'requirements.txt'
 
       - name: Install dependencies
         run: |

.github/workflows/translation.yml

@@ -18,14 +18,14 @@ jobs:
 
     steps:
     - name: Grab the repo src
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       with:
         fetch-depth: 0  # To reach the common commit
     - name: Set up git user as [bot]
       # Refs:
       # * https://github.community/t/github-actions-bot-email-address/17204/6
       # * https://github.com/actions/checkout/issues/13#issuecomment-724415212
-      uses: fregante/setup-git-user@v1.0.1
+      uses: fregante/setup-git-user@v1.1.0
 
     - name: Switch to the translation source branch
       run: |
@@ -50,7 +50,7 @@ jobs:
         git merge '${{ github.event.repository.default_branch }}'
 
     - name: Set up Python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         python-version: >-
           3.10

source/conf.py

@@ -416,7 +416,6 @@
     'pypa': ('https://www.pypa.io/en/latest/', None),
     'python': ('https://docs.python.org/3', None),
     'python-guide': ('https://docs.python-guide.org', None),
-    'python2': ('https://docs.python.org/2', None),
     'setuptools': ('https://setuptools.readthedocs.io/en/latest/', None),
     'spack': ('https://spack.readthedocs.io/en/latest/', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master', None),

source/contribute.rst

@@ -135,7 +135,7 @@ need:
    See the :doc:`Hitchhiker's Guide to Python installation instructions <python-guide:starting/installation>`
    to install Python 3.8 on your operating system.
 
-To build the guide, run the following bash command in the source folder:
+To build the guide, run the following shell command in the project's root folder:
 
 .. code-block:: bash
 

source/discussions/index.rst

@@ -12,3 +12,4 @@ specific topic. If you're just trying to get stuff done, see
    pip-vs-easy-install
    install-requires-vs-requirements
    wheel-vs-egg
+   src-layout-vs-flat-layout

source/discussions/src-layout-vs-flat-layout.rst

@@ -0,0 +1,79 @@
+=========================
+src layout vs flat layout
+=========================
+
+The "flat layout" refers to organising a project's files in a folder or
+repository, such that the various configuration files and
+:term:`import packages <Import Package>` are all in the top-level directory.
+
+::
+
+    .
+    ├── README.md
+    ├── noxfile.py
+    ├── pyproject.toml
+    ├── setup.py
+    ├── awesome_package/
+    │   ├── __init__.py
+    │   └── module.py
+    └── tools/
+        ├── generate_awesomeness.py
+        └── decrease_world_suck.py
+
+The "src layout" deviates from the flat layout by moving the code that is
+intended to be importable (i.e. ``import awesome_package``, also known as
+:term:`import packages <Import Package>`) into a subdirectory. This
+subdirectory is typically named ``src/``, hence "src layout".
+
+::
+
+    .
+    ├── README.md
+    ├── noxfile.py
+    ├── pyproject.toml
+    ├── setup.py
+    ├── src/
+    │    └── awesome_package/
+    │       ├── __init__.py
+    │       └── module.py
+    └── tools/
+        ├── generate_awesomeness.py
+        └── decrease_world_suck.py
+
+Here's a breakdown of the important behaviour differences between the src
+layout and the flat layout:
+
+* The src layout requires installation of the project to be able to run its
+  code, and the flat layout does not.
+
+  This means that the src layout involves an additional step in the
+  development workflow of a project (typically, an
+  :doc:`editable installation <setuptools:userguide/development_mode>`
+  is used for development and a regular installation is used for testing).
+
+* The src layout helps prevent accidental usage of the in-development copy of
+  the code.
+
+  This is relevant since the Python interpreter includes the current working
+  directory as the first item on the import path. This means that if an import
+  package exists in the current working directory with the same name as an
+  installed import package, the variant from the current working directory will
+  be used. This can lead to subtle  misconfiguration of the project's packaging
+  tooling, which could result in files not being included in a distribution.
+
+  The src layout helps avoid this by keeping import packages in a directory
+  separate from the root directory of the project, ensuring that the installed
+  copy is used.
+
+* The src layout helps enforce that an
+  :doc:`editable installation <setuptools:userguide/development_mode>` is only
+  able to import files that were meant to be importable.
+
+  This is especially relevant when the editable installation is implemented
+  using a `path configuration file <https://docs.python.org/3/library/site.html#index-2>`_
+  that adds the directory to the import path.
+
+  The flat layout would add the other project files (eg: ``README.md``,
+  ``tox.ini``) and packaging/tooling configuration files (eg: ``setup.py``,
+  ``noxfile.py``) on the import path. This would make certain imports work
+  in editable installations but not regular installations.

source/guides/analyzing-pypi-package-downloads.rst

@@ -51,7 +51,7 @@ Getting set up
 
 In order to use `Google BigQuery`_ to query the `public PyPI download
 statistics dataset`_, you'll need a Google account and to enable the BigQuery
-API on a Google Cloud Platform project. You can run the up to 1TB of queries
+API on a Google Cloud Platform project. You can run up to 1TB of queries
 per month `using the BigQuery free tier without a credit card
 <https://cloud.google.com/blog/products/data-analytics/query-without-a-credit-card-introducing-bigquery-sandbox>`__
 

source/key_projects.rst

@@ -64,8 +64,8 @@ distlib
 =======
 
 :doc:`Docs <distlib:index>` |
-`Issues <https://bitbucket.org/pypa/distlib/issues?status=new&status=open>`__ |
-`Bitbucket <https://bitbucket.org/pypa/distlib>`__ |
+`Issues <https://github.com/pypa/distlib/issues>`__ |
+`GitHub <https://github.com/pypa/distlib>`__ |
 `PyPI <https://pypi.org/project/distlib>`__
 
 ``distlib`` is a library which implements low-level functions that
@@ -496,7 +496,8 @@ make deployment of Python applications as simple as ``cp``.
 pip-tools
 =========
 
-`GitHub and Docs <https://github.com/jazzband/pip-tools/>`__ |
+`Docs <https://pip-tools.readthedocs.io/en/latest/>`__ |
+`GitHub <https://github.com/jazzband/pip-tools/>`__ |
 `PyPI <https://pypi.org/project/pip-tools/>`__
 
 pip-tools is a suite of tools meant for Python system administrators

source/specifications/declaring-project-metadata.rst

@@ -33,7 +33,7 @@ or listed as dynamic are:
 
 - ``version``
 
-All other fields are considered optional and my be specified
+All other fields are considered optional and may be specified
 statically, listed as dynamic, or left unspecified.
 
 

source/specifications/source-distribution-format.rst

@@ -33,15 +33,23 @@ deemed a source tree.
 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 canonicalized form of
-the project version (see :ref:`version-specifiers`).
+The file name of a sdist was standardised in :pep:`625`. The file name must be in
+the form ``{name}-{version}.tar.gz``, where ``{name}`` is normalised according to
+the same rules as for binary distributions (see :ref:`binary-distribution-format`),
+and ``{version}`` is the canonicalized form of the project version (see
+:ref:`version-specifiers`).
 
 The name and version components of the filename MUST match the values stored
 in the metadata contained in the file.
 
+Code that produces a source distribution file MUST give the file a name that matches
+this specification. This includes the ``build_sdist`` hook of a build backend.
+
+Code that processes source distribution files MAY recognise source distribution files
+by the ``.tar.gz`` suffix and the presence of precisely *one* hyphen in the filename.
+Code that does this may then use the distribution name and version from the filename
+without further verification.
+
 Source distribution file format
 ===============================
 
@@ -57,4 +65,5 @@ 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.
+UTF-8 based file names. In particular, source distribution files must be readable
+using the standard library tarfile module with the open flag 'r:gz'.