Merge branch 'main' into main

Author: chrysle

.github/workflows/zizmor.yml

@@ -0,0 +1,38 @@
+# From https://woodruffw.github.io/zizmor/usage/#use-in-github-actions
+
+name: GitHub Actions Security Analysis with zizmor 🌈
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  zizmor:
+    name: zizmor latest via PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      # required for workflows in private repositories
+      contents: read
+      actions: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Run zizmor 🌈
+        run: uvx zizmor --format sarif source/guides/github-actions-ci-cd-sample/* > results.sarif
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload SARIF file
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
+          category: zizmor

requirements.txt

@@ -1,4 +1,4 @@
-furo==2023.9.10
+furo==2024.8.6
 sphinx==7.2.6
 sphinx-autobuild==2021.3.14
 sphinx-inline-tabs==2023.4.21

source/conf.py

@@ -62,6 +62,11 @@
 html_title = "Python Packaging User Guide"
 html_theme = "furo"
 
+html_theme_options = {
+    "source_edit_link": "https://github.com/pypa/packaging.python.org/edit/main/source/{filename}",
+    "source_view_link": "https://github.com/pypa/packaging.python.org/blob/main/source/{filename}?plain=true",
+}
+
 html_favicon = "assets/py.png"
 html_last_updated_fmt = ""
 
@@ -136,11 +141,13 @@
     "https://anaconda.org",
 ]
 linkcheck_retries = 5
-# Ignore anchors for links to GitHub project pages -- GitHub adds anchors from
-# README.md headings through JavaScript, so Sphinx's linkcheck can't find them
-# in the HTML.
+# Ignore anchors for common targets when we know they likely won't be found
 linkcheck_anchors_ignore_for_url = [
+    # GitHub synthesises anchors in JavaScript, so Sphinx can't find them in the HTML
     r"https://github\.com/",
+    # While PyPI has its botscraping defenses active, Sphinx can't resolve the anchors
+    # https://github.com/pypa/packaging.python.org/issues/1744
+    r"https://pypi\.org/",
 ]
 
 # -- Options for extlinks ----------------------------------------------------------

source/discussions/downstream-packaging.rst

@@ -17,3 +17,4 @@ specific topic. If you're just trying to get stuff done, see
    src-layout-vs-flat-layout
    setup-py-deprecated
    single-source-version
+   downstream-packaging

source/discussions/index.rst

@@ -210,6 +210,6 @@ has now been reduced to the role of a build backend.
 Where to read more about this?
 ==============================
 
-* https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html
+* `Why you shouldn't invoke setup.py directly <https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html>`__ by Paul Ganssle
 
 * :doc:`setuptools:deprecated/commands`

source/discussions/setup-py-deprecated.rst

@@ -147,6 +147,40 @@ Glossary
         multiple individual distributions.
 
 
+    License Classifier
+
+        A PyPI Trove classifier
+        (as :ref:`described <core-metadata-classifier>`
+        in the :term:`Core Metadata` specification)
+        which begins with ``License ::``.
+
+
+    License Expression
+    SPDX Expression
+
+        A string with valid SPDX license expression syntax,
+        including one or more SPDX :term:`License Identifier`\(s),
+        which describes a :term:`Project`'s license(s)
+        and how they inter-relate.
+        Examples:
+        ``GPL-3.0-or-later``,
+        ``MIT AND (Apache-2.0 OR BSD-2-Clause)``
+
+
+    License Identifier
+    SPDX Identifier
+
+        A valid SPDX short-form license identifier,
+        originally specified in :pep:`639`.
+        This includes all valid SPDX identifiers and
+        the custom ``LicenseRef-[idstring]`` strings conforming to the
+        SPDX specification.
+        Examples:
+        ``MIT``,
+        ``GPL-3.0-only``,
+        ``LicenseRef-My-Custom-License``
+
+
     Module
 
         The basic unit of code reusability in Python, existing in one of two
@@ -313,6 +347,23 @@ Glossary
        docs on :ref:`pip:Requirements Files`.
 
 
+    Root License Directory
+    License Directory
+
+        The directory under which license files are stored in a
+        :term:`Project Source Tree`, :term:`Distribution Archive`
+        or :term:`Installed Project`.
+        For a :term:`Project Source Tree` or
+        :term:`Source Distribution (or "sdist")`, this is the
+        :term:`Project Root Directory`.
+        For a :term:`Built Distribution` or :term:`Installed Project`,
+        this is the :file:`.dist-info/licenses/` directory of
+        the wheel archive or project folder respectively.
+        Also, the root directory that paths
+        recorded in the ``License-File``
+        :term:`Core Metadata Field` are relative to.
+
+
     setup.py
     setup.cfg
 

source/glossary.rst

@@ -9,6 +9,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
@@ -78,8 +80,8 @@ jobs:
         GITHUB_TOKEN: ${{ github.token }}
       run: >-
         gh release create
-        '${{ github.ref_name }}'
-        --repo '${{ github.repository }}'
+        "$GITHUB_REF_NAME"
+        --repo "$GITHUB_REPOSITORY"
         --notes ""
     - name: Upload artifact signatures to GitHub Release
       env:
@@ -89,8 +91,8 @@ jobs:
       # sigstore-produced signatures and certificates.
       run: >-
         gh release upload
-        '${{ github.ref_name }}' dist/**
-        --repo '${{ github.repository }}'
+        "$GITHUB_REF_NAME" dist/**
+        --repo "$GITHUB_REPOSITORY"
 
   publish-to-testpypi:
     name: Publish Python 🐍 distribution 📦 to TestPyPI

source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml

@@ -89,7 +89,7 @@ SciPy distributions
 -------------------
 
 The SciPy site lists `several distributions
-<https://scipy.org/install/#distributions>`_
+<https://scipy.org/install/>`_
 that provide the full SciPy stack to
 end users in an easy to use and update format.