Merge branch 'main' into extension

Author: pradyunsg

.github/workflows/test.yml

@@ -1,7 +1,10 @@
 name: Test
 
-on: 
+on:
+  merge_group:
   push:
+    branches-ignore:
+    - gh-readonly-queue/**  # Temporary merge queue-related GH-made branches
   pull_request:
   schedule:
     - cron: "0 6 * * *" # daily at 6am
@@ -13,6 +16,7 @@ concurrency:
 jobs:
   build:
     name: ${{ matrix.noxenv }}
+    if: ${{ github.repository_owner == 'pypa' || github.event_name != 'schedule' }}
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -26,7 +30,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: "3.11"
           cache: 'pip'
           cache-dependency-path: 'requirements.txt'
 
@@ -37,3 +41,21 @@ jobs:
       - name: Nox ${{ matrix.noxenv }}
         run: |
           python -m nox -s ${{ matrix.noxenv }}
+
+
+  check:
+    # 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()
+
+    needs:
+    - build
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Decide whether the needed jobs succeeded or failed
+      uses: re-actors/alls-green@release/v1
+      with:
+        jobs: ${{ toJSON(needs) }}

.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.4.0
+  hooks:
+  - id: check-added-large-files
+  - id: check-case-conflict
+  - id: check-merge-conflict
+  - id: check-symlinks
+  - id: check-yaml
+  - id: end-of-file-fixer
+  - id: mixed-line-ending
+  - id: trailing-whitespace
+
+- repo: https://github.com/codespell-project/codespell
+  rev: v2.2.6
+  hooks:
+  - id: codespell
+    args: ["-L", "ned"]
+
+- repo: local
+  hooks:
+  - id: disallow-caps
+    name: Disallow improper capitalization
+    language: pygrep
+    entry: PyBind|Numpy|Cmake|CCache|Github|PyTest
+    exclude: .pre-commit-config.yaml
+
+- repo: https://github.com/pre-commit/pygrep-hooks
+  rev: v1.10.0
+  hooks:
+  - id: rst-backticks
+  - id: rst-directive-colons
+  - id: rst-inline-touching-normal

.readthedocs.yaml

@@ -9,7 +9,11 @@ sphinx:
    # https://github.com/pyca/cryptography/issues/5863#issuecomment-792343136
    builder: dirhtml
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
 python:
-   version: 3.8
    install:
    - requirements: requirements.txt

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):
     """
@@ -38,7 +39,7 @@ def build(session, autobuild=False):
 
     if autobuild:
         command = "sphinx-autobuild"
-        extra_args = "-H", "0.0.0.0"
+        extra_args = "--host", "0.0.0.0"
     else:
         # NOTE: This branch adds options that are unsupported by autobuild
         command = "sphinx-build"
@@ -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",
+    )

requirements.txt

@@ -1,6 +1,7 @@
 sphinx==4.5.0
-sphinx-autobuild==0.7.1
+sphinx-autobuild==2021.3.14
 sphinx-inline-tabs==2021.4.11b9
-python-docs-theme==2022.1
+python-docs-theme==2023.9
 sphinx-copybutton==0.5.0
-git+https://github.com/pypa/pypa-docs-theme.git#egg=pypa-docs-theme
+pypa-docs-theme @ git+https://github.com/pypa/pypa-docs-theme.git
+sphinx-toolbox==3.5.0

source/conf.py

@@ -36,6 +36,7 @@
     'sphinx.ext.todo',
     'sphinx_inline_tabs',
     'sphinx_copybutton',
+    'sphinx_toolbox.collapse',
 ]
 
 # config for copy button
@@ -397,6 +398,7 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'boltons': ('https://boltons.readthedocs.io/en/latest/', None),
+    'bottle': ('https://bottlepy.org/docs/dev/', None),
     'build': ('https://pypa-build.readthedocs.io/en/stable/', None),
     'cffi': ('https://cffi.readthedocs.io/en/latest/', None),
     'conda': ('https://conda.io/en/latest/', None),
@@ -407,7 +409,7 @@
     'nox': ('https://nox.thea.codes/en/latest/', None),
     'openstack': ('https://docs.openstack.org/glance/latest/', None),
     'packaging': ('https://packaging.pypa.io/en/latest/', None),
-    'packaging.python.org': ('https://packaging.python.org/', None),
+    'packaging.python.org': ('https://packaging.python.org/en/latest/', None),
     'pip': ('https://pip.pypa.io/en/latest/', None),
     'pipenv': ('https://pipenv.pypa.io/en/latest/', None),
     'piwheels': ('https://piwheels.readthedocs.io/en/latest/', None),
@@ -416,10 +418,10 @@
     'pypa': ('https://www.pypa.io/en/latest/', None),
     'python': ('https://docs.python.org/3', None),
     'python-guide': ('https://docs.python-guide.org', None),
-    'setuptools': ('https://setuptools.readthedocs.io/en/latest/', None),
+    'setuptools': ('https://setuptools.pypa.io/en/latest/', None),
     'spack': ('https://spack.readthedocs.io/en/latest/', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master', None),
-    'tox': ('https://tox.readthedocs.io/en/latest/', None),
+    'tox': ('https://tox.wiki/en/latest/', None),
     'twine': ('https://twine.readthedocs.io/en/stable/', None),
     'virtualenv': ('https://virtualenv.pypa.io/en/stable/', None),
 }

source/contribute.rst

@@ -32,9 +32,12 @@ Documentation types
 ===================
 
 This project consists of four distinct documentation types with specific
-purposes. When proposing new additions to the project please pick the
+purposes. The project aspires to follow the `Diátaxis process`_
+for creating quality documentation. When proposing new additions to the project please pick the
 appropriate documentation type.
 
+.. _Diátaxis process: https://diataxis.fr/
+
 Tutorials
 ---------
 
@@ -63,7 +66,7 @@ document <discussions/install-requires-vs-requirements>`.
 Specifications
 --------------
 
-Specifications are reference documention focused on comprehensively documenting
+Specifications are reference documentation focused on comprehensively documenting
 an agreed-upon interface for interoperability between packaging tools.
 :doc:`example specification-style document <specifications/core-metadata>`.
 
@@ -75,15 +78,15 @@ We use `Weblate`_ to manage translations of this project.
 Please visit the `packaging.python.org`_ project on Weblate to contribute.
 
 If you are experiencing issues while you are working on translations,
-please open an issue on `Github`_.
+please open an issue on `GitHub`_.
 
 .. tip::
 
    Any translations of this project should follow `reStructuredText syntax`_.
 
 .. _Weblate: https://weblate.org/
 .. _packaging.python.org: https://hosted.weblate.org/projects/pypa/packaging-python-org/
-.. _Github: https://github.com/pypa/packaging.python.org/issues
+.. _GitHub: https://github.com/pypa/packaging.python.org/issues
 .. _reStructuredText syntax: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 
 Adding a language
@@ -131,9 +134,9 @@ need:
 
       python -m pip install --user nox
 
-2. Python 3.8. Our build scripts are usually tested with Python 3.8 only.
+2. Python 3.11. Our build scripts are usually tested with Python 3.11 only.
    See the :doc:`Hitchhiker's Guide to Python installation instructions <python-guide:starting/installation>`
-   to install Python 3.8 on your operating system.
+   to install Python 3.11 on your operating system.
 
 To build the guide, run the following shell command in the project's root folder:
 

source/discussions/deploying-python-applications.rst

@@ -73,7 +73,7 @@ directory, independent of any other Python installation on the computer.
 
 A big advantage of Pynsist is that the Windows packages can be built on Linux.
 There are several examples for different kinds of programs (console, GUI) in
-the `documentation <pynsist:index>`. The tool is released
+the :any:`documentation <pynsist:index>`. The tool is released
 under the MIT-licence.
 
 Application bundles
@@ -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.
 

source/discussions/install-requires-vs-requirements.rst

@@ -38,8 +38,9 @@ v2 of 'B', so it would be like so:
     'B>=2'
  ]
 
-It may also be known that project A follows semantic versioning, and that v2 of
-'A' will indicate a break in compatibility, so it makes sense to not allow v2:
+It may also be known that project 'A' introduced a change in its v2
+that breaks the compatibility of your project with v2 of 'A' and later,
+so it makes sense to not allow v2:
 
 ::
 

source/discussions/wheel-vs-egg.rst

@@ -17,7 +17,9 @@ Distribution>` and :term:`binary <Binary Distribution>` packaging for Python.
 Here's a breakdown of the important differences between :term:`Wheel` and :term:`Egg`.
 
 
-* :term:`Wheel` has an :pep:`official PEP <427>`. :term:`Egg` did not.
+* :term:`Wheel` has an :doc:`official standard specification
+  </specifications/binary-distribution-format>`.
+  :term:`Egg` did not.
 
 * :term:`Wheel` is a :term:`distribution <Distribution Package>` format, i.e a packaging
   format. [1]_ :term:`Egg` was both a distribution format and a runtime
@@ -42,8 +44,12 @@ 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
-       runtime format, although :pep:`this is not officially supported at this time
-       <427#is-it-possible-to-import-python-code-directly-from-a-wheel-file>`.
+       runtime format, although :ref:`this is not officially supported at this time
+       <binary-distribution-format-import-wheel>`.