Merge branch 'main' into musllinux

Author: jeanas

.github/workflows/test-translations.yml

@@ -0,0 +1,73 @@
+name: Test translations
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+    - '**.po'
+    branches:
+    - translation/source
+  push:
+    paths:
+    - '**.po'
+    branches:
+    - translation/source
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+env:
+  I18N_BRANCH: translation/source
+
+jobs:
+  matrix:
+    runs-on: ubuntu-latest
+    outputs:
+      languages: ${{ steps.languages.outputs.languages }}
+
+    steps:
+    - name: Grab the repo src
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ env.I18N_BRANCH }}
+
+    - name: List languages
+      id: languages
+      working-directory: locales
+      run: |
+        list=$(find * -maxdepth 0 -type d | jq -nRc '[inputs]')
+        echo "languages=$list" >> $GITHUB_OUTPUT
+
+
+  test-translation:
+    runs-on: ubuntu-latest
+    needs: matrix
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ${{fromJson(needs.matrix.outputs.languages)}}
+
+    steps:
+    - name: Grab the repo src
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ env.I18N_BRANCH }}
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: >-
+          3.10
+
+    - name: Install Python tooling
+      run: python -m pip install --upgrade nox virtualenv sphinx-lint
+
+    - name: Build translated docs in ${{ matrix.language }}
+      run: nox -s build -- -q -D language=${{ matrix.language }}
+
+    - name: Lint translation file
+      run: sphinx-lint locales/${{ matrix.language }}/LC_MESSAGES/messages.po

.github/workflows/test.yml

@@ -47,7 +47,9 @@ jobs:
     # This job does nothing and is only used for the branch protection
     # or multi-stage CI jobs, like making sure that all tests pass before
     # a publishing job is started.
-    if: always()
+    if: >-
+      github.repository_owner == 'pypa'
+      || github.event_name != 'schedule'
 
     needs:
     - build

.github/workflows/translation.yml

@@ -15,6 +15,7 @@ env:
 jobs:
   build:
     runs-on: ubuntu-latest
+    if: github.repository_owner == 'pypa'
 
     steps:
     - name: Grab the repo src
@@ -65,6 +66,7 @@ jobs:
       run: |
         git_hash=$(git rev-parse --short "${GITHUB_SHA}")
         git add --force locales/messages.pot
+        git diff-index --quiet HEAD || \
         git commit \
           -m "Update messages.pot as of version ${git_hash}" \
           locales/messages.pot

.pre-commit-config.yaml

@@ -34,7 +34,7 @@ repos:
   - id: rst-inline-touching-normal
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.1.6
+  rev: v0.1.9
   hooks:
     - id: ruff
     - id: ruff-format

source/conf.py

@@ -108,6 +108,7 @@
     # https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690
     "https://www.breezy-vcs.org/*",
 ]
+linkcheck_retries = 5
 
 # -- Options for extlinks ----------------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html#configuration

source/discussions/distribution-package-vs-import-package.rst

@@ -0,0 +1,110 @@
+.. _distribution-package-vs-import-package:
+
+=======================================
+Distribution package vs. import package
+=======================================
+
+A number of different concepts are commonly referred to by the word
+"package". This page clarifies the differences between two distinct but
+related meanings in Python packaging, "distribution package" and "import
+package".
+
+What's a distribution package?
+==============================
+
+A distribution package is a piece of software that you can install.
+Most of the time, this is synonymous with "project". When you type ``pip
+install pkg``, or when you write ``dependencies = ["pkg"]`` in your
+``pyproject.toml``, ``pkg`` is the name of a distribution package. When
+you search or browse the PyPI_, the most widely known centralized source for
+installing Python libraries and tools, what you see is a list of distribution
+packages. Alternatively, the term "distribution package" can be used to
+refer to a specific file that contains a certain version of a project.
+
+Note that in the Linux world, a "distribution package",
+most commonly abbreviated as "distro package" or just "package",
+is something provided by the system package manager of the `Linux distribution <distro_>`_,
+which is a different meaning.
+
+
+What's an import package?
+=========================
+
+An import package is a Python module. Thus, when you write ``import
+pkg`` or ``from pkg import func`` in your Python code, ``pkg`` is the
+name of an import package. More precisely, import packages are special
+Python modules that can contain submodules. For example, the ``numpy``
+package contains modules like ``numpy.linalg`` and
+``numpy.fft``. Usually, an import package is a directory on the file
+system, containing modules as ``.py`` files and subpackages as
+subdirectories.
+
+You can use an import package as soon as you have installed a distribution
+package that provides it.
+
+
+What are the links between distribution packages and import packages?
+=====================================================================
+
+Most of the time, a distribution package provides one single import
+package (or non-package module), with a matching name. For example,
+``pip install numpy`` lets you ``import numpy``.
+
+However, this is only a convention. PyPI and other package indices *do not
+enforce any relationship* between the name of a distribution package and the
+import packages it provides. (A consequence of this is that you cannot blindly
+install the PyPI package ``foo`` if you see ``import foo``; this may install an
+unintended, and potentially even malicious package.)
+
+A distribution package could provide an import package with a different
+name. An example of this is the popular Pillow_ library for image
+processing. Its distribution package name is ``Pillow``, but it provides
+the import package ``PIL``. This is for historical reasons: Pillow
+started as a fork of the PIL library, thus it kept the import name
+``PIL`` so that existing PIL users could switch to Pillow with little
+effort. More generally, a fork of an existing library is a common reason
+for differing names between the distribution package and the import
+package.
+
+On a given package index (like PyPI), distribution package names must be
+unique. On the other hand, import packages have no such requirement.
+Import packages with the same name can be provided by several
+distribution packages. Again, forks are a common reason for this.
+
+Conversely, a distribution package can provide several import packages,
+although this is less common. An example is the attrs_ distribution
+package, which provides both an ``attrs`` import package with a newer
+API, and an ``attr`` import package with an older but supported API.
+
+
+How do distribution package names and import package names compare?
+===================================================================
+
+Import packages should have valid Python identifiers as their name (the
+:ref:`exact rules <python:identifiers>` are found in the Python
+documentation) [#non-identifier-mod-name]_. In particular, they use underscores ``_`` as word
+separator and they are case-sensitive.
+
+On the other hand, distribution packages can use hyphens ``-`` or
+underscores ``_``. They can also contain dots ``.``, which is sometimes
+used for packaging a subpackage of a :ref:`namespace package
+<packaging-namespace-packages>`. For most purposes, they are insensitive
+to case and to ``-`` vs.  ``_`` differences, e.g., ``pip install
+Awesome_Package`` is the same as ``pip install awesome-package`` (the
+precise rules are given in the :ref:`name normalization specification
+<name-normalization>`).
+
+
+
+---------------------------
+
+.. [#non-identifier-mod-name] Although it is technically possible
+   to import packages/modules that do not have a valid Python identifier as
+   their name, using :doc:`importlib <python:library/importlib>`,
+   this is vanishingly rare and strongly discouraged.
+
+
+.. _distro: https://en.wikipedia.org/wiki/Linux_distribution
+.. _PyPI: https://pypi.org
+.. _Pillow: https://pypi.org/project/Pillow
+.. _attrs: https://pypi.org/project/attrs

source/discussions/index.rst

@@ -12,5 +12,6 @@ specific topic. If you're just trying to get stuff done, see
    pip-vs-easy-install
    install-requires-vs-requirements
    wheel-vs-egg
+   distribution-package-vs-import-package
    src-layout-vs-flat-layout
    setup-py-deprecated

source/discussions/setup-py-deprecated.rst

@@ -12,7 +12,7 @@ for packaging Python projects.
 And :file:`setup.py` is a valid configuration file for :ref:`setuptools`
 that happens to be written in Python, instead of in *TOML* for example
 (a similar practice is used by other tools
-like *nox* and its :file:`nox.py` configuration file,
+like *nox* and its :file:`noxfile.py` configuration file,
 or *pytest* and :file:`conftest.py`).
 
 However, ``python setup.py`` and the use of :file:`setup.py`

source/glossary.rst

@@ -67,7 +67,8 @@ Glossary
         :term:`Import Package` (which is also commonly called a "package") or
         another kind of distribution (e.g. a Linux distribution or the Python
         language distribution), which are often referred to with the single term
-        "distribution".
+        "distribution". See :ref:`distribution-package-vs-import-package`
+        for a breakdown of the differences.
 
     Egg
 
@@ -103,7 +104,8 @@ Glossary
         An import package is more commonly referred to with the single word
         "package", but this guide will use the expanded term when more clarity
         is needed to prevent confusion with a :term:`Distribution Package` which
-        is also commonly called a "package".
+        is also commonly called a "package". See :ref:`distribution-package-vs-import-package`
+        for a breakdown of the differences.
 
     Module
 
@@ -207,10 +209,8 @@ Glossary
     Requirement Specifier
 
        A format used by :ref:`pip` to install packages from a :term:`Package
-       Index`. For an EBNF diagram of the format, see the
-       `pkg_resources.Requirement
-       <https://setuptools.readthedocs.io/en/latest/pkg_resources.html#requirement-objects>`_
-       entry in the :ref:`setuptools` docs. For example, "foo>=1.3" is a
+       Index`. For an EBNF diagram of the format, see :ref:`dependency-specifiers`.
+       For example, "foo>=1.3" is a
        requirement specifier, where "foo" is the project name, and the ">=1.3"
        portion is the :term:`Version Specifier`
 

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

@@ -32,7 +32,7 @@ PyPI does not display download statistics for a number of reasons: [#]_
   doesn't mean it's good; Similarly just because a project hasn't been
   downloaded a lot doesn't mean it's bad!
 
-In short, because it's value is low for various reasons, and the tradeoffs
+In short, because its value is low for various reasons, and the tradeoffs
 required to make it work are high, it has been not an effective use of
 limited resources.