From e2b9a6ec8e1012242f6275d79e6db075e4cdefad Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:12:50 -0400 Subject: [PATCH 01/13] MNT: Remove deprecated test and upload commands from setup.py The setuptools test command has been removed, and invoking setup.py directly is deprecated. Building currently warns that references to the test command will cause build errors in the future. Co-Authored-By: Claude Opus 5.5 (1M context) --- setup.py | 62 +------------------------------------------------------- 1 file changed, 1 insertion(+), 61 deletions(-) diff --git a/setup.py b/setup.py index d4b4ea9..fbaa64b 100755 --- a/setup.py +++ b/setup.py @@ -2,11 +2,8 @@ import glob import os -import sys -from shutil import rmtree -from setuptools import Command, find_packages, setup -from setuptools.command.test import test as TestCommand +from setuptools import find_packages, setup def read(fname): @@ -84,58 +81,6 @@ def read(fname): long_description_content_type = "text/plain" -class PyTest(TestCommand): - """Support setup.py test.""" - - def finalize_options(self): - TestCommand.finalize_options(self) - self.test_args = [] - self.test_suite = True - - def run_tests(self): - import pytest - - pytest.main(self.test_args) - - -class UploadCommand(Command): - """Support setup.py upload.""" - - description = "Build and publish the package." - user_options = [] - - @staticmethod - def status(s): - """Print things in bold.""" - print("\033[1m{0}\033[0m".format(s)) - - def initialize_options(self): - pass - - def finalize_options(self): - pass - - def run(self): - try: - self.status("Removing previous builds...") - here = os.path.abspath(os.path.dirname(__file__)) - rmtree(os.path.join(here, "dist")) - except OSError: - pass - - self.status("Building Source and Wheel (universal) distribution...") - os.system("{0} setup.py sdist bdist_wheel --universal".format(sys.executable)) - - self.status("Uploading the package to PyPI via Twine...") - os.system("twine upload dist/*") - - self.status("Pushing git tags...") - os.system("git tag v{0}".format(meta["version"])) - os.system("git push --tags") - - sys.exit() - - setup( # Essential details on the package and its dependencies name=meta["name"], @@ -168,9 +113,4 @@ def run(self): "Programming Language :: Python :: 3.12", ], # Could also include keywords, download_url, project_urls, etc. - # Custom commands - cmdclass={ - "test": PyTest, - "upload": UploadCommand, - }, ) From 64eac360219403248f0c5f6b4e9b0be55e5008be Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:12:51 -0400 Subject: [PATCH 02/13] DOC: Recommend python -m build instead of invoking setup.py Co-Authored-By: Claude Opus 5.5 (1M context) --- README.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/README.rst b/README.rst index 566b179..86ee200 100644 --- a/README.rst +++ b/README.rst @@ -412,18 +412,10 @@ Your package can be installed from source with:: pip install . -or alternatively with:: - - python setup.py install - -But do remember that as a developer, you should install your package in editable mode, using either:: +But do remember that as a developer, you should install your package in editable mode, using:: pip install --editable . -or:: - - python setup.py develop - which will mean changes to the source will affect your installed package immediately without you having to reinstall it. By default, when the package is installed only the main requirements, listed in ``requirements.txt`` will be installed with it. @@ -437,12 +429,21 @@ etc. Any additional files named ``requirements-EXTRANAME.txt`` will also be collected automatically and made available with the corresponding name ``EXTRANAME``. Another extra named ``all`` captures all of these optional dependencies. -Your README file is automatically included in the metadata when you use setup.py build wheels for PyPI. +To build an sdist and wheel for distribution on PyPI, use build_:: + + pip install build + python -m build + +Note that invoking ``setup.py`` directly (e.g. ``python setup.py install``, ``python setup.py sdist``) is `deprecated `_ and should not be used. + +Your README file is automatically included in the metadata of the built distributions. The rest of the metadata comes from ``package_name/__meta__.py``. Our template setup.py file is based on the `example from setuptools documentation `_, and the comprehensive example from `Kenneth Reitz `_ (released under `MIT License `__), with further features added. +.. _build: https://build.pypa.io/ .. _kennethreitz/setup.py: https://github.com/kennethreitz/setup.py +.. _setuptools-deprecated: https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html .. _setuptools-setup.py: https://setuptools.readthedocs.io/en/latest/setuptools.html#basic-use From 94fc279adec3a78b4078d8bc7e21fe61a65d12a0 Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:12:52 -0400 Subject: [PATCH 03/13] BUG:CI: Remove invalid branches filter from scheduled trigger The schedule event does not accept a branches key; scheduled runs always use the default branch. Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/workflows/test.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 4b4f03d..6d69deb 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -14,8 +14,8 @@ on: push: pull_request: schedule: + # Scheduled runs always use the default branch - cron: "0 0 * * 1" - branches: [ $default-branch ] jobs: test: From 5c149f9e65a79733adaf049f423039a2239dd312 Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:12:52 -0400 Subject: [PATCH 04/13] CI: Remove duplicated macOS job from release candidate matrix Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/workflows/test-release-candidate.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/test-release-candidate.yaml b/.github/workflows/test-release-candidate.yaml index a7a1217..30ec2c8 100644 --- a/.github/workflows/test-release-candidate.yaml +++ b/.github/workflows/test-release-candidate.yaml @@ -52,8 +52,6 @@ jobs: include: - os: macos-latest python-version: "3.12" - - os: macos-latest - python-version: "3.12" env: OS: ${{ matrix.os }} PYTHON: ${{ matrix.python-version }} From e3d5e57ba82a3dd47b11f546d3d0ef77a0af792a Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:12:53 -0400 Subject: [PATCH 05/13] CI: Build distributions with python -m build Wheels continue to be built on every OS and Python version, in case the package contains compiled extensions. The sdist is built once, in the publish job. Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/workflows/test-release-candidate.yaml | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/.github/workflows/test-release-candidate.yaml b/.github/workflows/test-release-candidate.yaml index 30ec2c8..88e7ac3 100644 --- a/.github/workflows/test-release-candidate.yaml +++ b/.github/workflows/test-release-candidate.yaml @@ -94,10 +94,10 @@ jobs: env_vars: OS,PYTHON name: Python ${{ matrix.python-version }} on ${{ runner.os }} - - name: Build wheels + - name: Build wheel run: | - python -m pip install --upgrade setuptools wheel twine - python setup.py sdist bdist_wheel + python -m pip install --upgrade build + python -m build --wheel - name: Store wheel artifacts uses: actions/upload-artifact@v4 @@ -123,6 +123,16 @@ jobs: steps: - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Build sdist + run: | + python -m pip install --upgrade build + python -m build --sdist + - name: Download wheel artifacts uses: actions/download-artifact@v4 with: From 1a7fc1e9480ec6c6df7e10afc5140ee4eece290b Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:12:53 -0400 Subject: [PATCH 06/13] BUG:CI: Fix download of wheel artifacts in publish job download-artifact@v4 matches multiple artifacts with pattern, not name, and needs merge-multiple to put them all into one directory. Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/workflows/test-release-candidate.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/test-release-candidate.yaml b/.github/workflows/test-release-candidate.yaml index 88e7ac3..61eb32a 100644 --- a/.github/workflows/test-release-candidate.yaml +++ b/.github/workflows/test-release-candidate.yaml @@ -136,13 +136,14 @@ jobs: - name: Download wheel artifacts uses: actions/download-artifact@v4 with: - name: wheel-* + pattern: wheel-* path: dist/ + merge-multiple: true - - name: Store aggregated wheel artifacts + - name: Store aggregated distribution artifacts uses: actions/upload-artifact@v4 with: - name: wheels + name: dist path: dist/* - name: Publish package to Test PyPI From 836ed4276ffa9a591291feec77384e7d5ee1696f Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:12:54 -0400 Subject: [PATCH 07/13] DOC: Remove stale line-number links from README Co-Authored-By: Claude Opus 5.5 (1M context) --- README.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/README.rst b/README.rst index 86ee200..4db5334 100644 --- a/README.rst +++ b/README.rst @@ -139,15 +139,15 @@ When creating a new repository from this template, these are the steps to follow .. highlight:: python - - In ``setup.py``, `L54 `__:: + - In ``setup.py``:: exec(read("package_name/__meta__.py"), meta) - - In ``docs/source/conf.py``, `L27 `__:: + - In ``docs/source/conf.py``:: from package_name import __meta__ as meta # noqa: E402 isort:skip - - In ``.github/workflows/test.yaml``, `L64 `__, and ``.github/workflows/test-release-candidate.yaml``, `L90 `__:: + - In ``.github/workflows/test.yaml`` and ``.github/workflows/test-release-candidate.yaml``:: python -m pytest --cov=package_name --cov-report term --cov-report xml --cov-config .coveragerc --junitxml=testresults.xml @@ -240,10 +240,8 @@ For a given block of code, a fixed version of black will always produce the same However, you should note that different versions of black will produce different outputs. If you want to upgrade to a newer version of black, you must change the version everywhere it is specified: -- requirements-dev.txt, `L1 `__ -- .pre-commit-config.yaml, `L14 `__, - `L29 `__, and - `L48 `__ +- requirements-dev.txt (``black==...``) +- .pre-commit-config.yaml (the ``rev`` of the black-pre-commit-mirror repo, and the ``black==...`` entries in ``additional_dependencies`` for the blacken-docs and nbqa-black hooks) .. _black: https://github.com/psf/black From aa4046d24a81b47df047e0f5f5075dc3dd9d431a Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:12:55 -0400 Subject: [PATCH 08/13] DOC: Replace black_nbconvert reference with nbQA Co-Authored-By: Claude Opus 5.5 (1M context) --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 4db5334..b43abf1 100644 --- a/README.rst +++ b/README.rst @@ -275,7 +275,7 @@ The pre-commit stack which comes with the template is highly opinionated, and in - Code is reformatted to use the black_ style. Any code inside docstrings will be formatted to black using blackendocs_. - All code cells in Jupyter notebooks are also formatted to black using black_nbconvert_. + All code cells in Jupyter notebooks are also formatted to black (and have their imports sorted and checked with flake8) using nbQA_. - All Jupyter notebooks are cleared using nbstripout_. @@ -294,10 +294,10 @@ The pre-commit stack which comes with the template is highly opinionated, and in Once it is set up, the pre-commit stack will run locally on every commit. The pre-commit stack will also run on github with one of the action workflows, which ensures PRs are checked without having to rely on contributors to enable the pre-commit locally. -.. _black_nbconvert: https://github.com/dfm/black_nbconvert .. _blackendocs: https://github.com/asottile/blacken-docs .. _flake8: https://gitlab.com/pycqa/flake8 .. _isort: https://github.com/timothycrosley/isort +.. _nbQA: https://github.com/nbQA-dev/nbQA .. _nbstripout: https://github.com/kynan/nbstripout .. _PEP-8: https://www.python.org/dev/peps/pep-0008/ .. _pre-commit: https://pre-commit.com/ From ce3f012344fea453c98aec2bf4cf3c544002c3b9 Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:12:55 -0400 Subject: [PATCH 09/13] DOC: Remove reference to nonexistent lint workflow Co-Authored-By: Claude Opus 5.5 (1M context) --- README.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/README.rst b/README.rst index b43abf1..69e508e 100644 --- a/README.rst +++ b/README.rst @@ -460,7 +460,7 @@ GitHub features the ability to run various workflows whenever code is pushed to This is one service of several services that can be used to continually run the unit tests and ensure changes can be integrated together without issue. It is also useful to ensure that style guides are adhered to -Five workflows are included: +Four workflows are included: docs The docs workflow ensures the documentation builds correctly, and presents any errors and warnings nicely as annotations. @@ -470,10 +470,6 @@ pre-commit Runs the pre-commit stack. Ensures all contributions are compliant, even if a contributor has not set up pre-commit on their local machine. -lint - Checks the code uses the black_ style and tests for flake8_ errors. - If you are using the pre-commit hooks, the lint workflow is superfluous and can be deleted. - test Runs the unit tests, and pushes coverage reports to Codecov_. You'll need to sign up at Codecov_ with your GitHub account in order for this integration to work. From 0685c759d026bb6329b3d71227cc5b6d64cd81e3 Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:12:56 -0400 Subject: [PATCH 10/13] DOC: Update list of alternative CI/CD services Co-Authored-By: Claude Opus 5.5 (1M context) --- README.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index 69e508e..2a9a862 100644 --- a/README.rst +++ b/README.rst @@ -497,12 +497,9 @@ Other CI/CD options Alternative CI/CD services are also available for running tests. -- `Travis CI `_ offers a free trial service. +- `GitLab CI/CD `_ is the natural choice if your repository is hosted on GitLab. -- `Circle CI `_ is another option with a limited `free option `_. - -- `Appveyor `_ useful for testing on Windows. - This offers an alternative to GitHub Actions if you need to `build Windows wheel files to submit to PyPI `_. +- `CircleCI `_ is another option with a limited `free plan `_. - `Jenkins `_ is useful if you want to run your CI test suite locally or on your own private server instead of in the cloud. From 95c69ea5c97c05e512d6fc66f6449be243b45a0d Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:13:15 -0400 Subject: [PATCH 11/13] CI: Publish to Test PyPI with Trusted Publishing Replace the API token with OIDC-based Trusted Publishing, and update the deprecated repository_url input to repository-url. Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/workflows/test-release-candidate.yaml | 12 +++++++++--- README.rst | 6 +++--- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/.github/workflows/test-release-candidate.yaml b/.github/workflows/test-release-candidate.yaml index 61eb32a..8e6ea25 100644 --- a/.github/workflows/test-release-candidate.yaml +++ b/.github/workflows/test-release-candidate.yaml @@ -120,6 +120,14 @@ jobs: needs: test-build runs-on: ubuntu-latest + # Uses PyPI Trusted Publishing, which needs no API token. Before enabling + # this job, add this repository and workflow as a trusted publisher in + # your Test PyPI project settings. See + # https://docs.pypi.org/trusted-publishers/ + environment: testpypi + permissions: + id-token: write + steps: - uses: actions/checkout@v4 @@ -149,6 +157,4 @@ jobs: - name: Publish package to Test PyPI uses: pypa/gh-action-pypi-publish@release/v1 with: - user: __token__ - password: ${{ secrets.TEST_PYPI_API_TOKEN }} - repository_url: https://test.pypi.org/legacy/ + repository-url: https://test.pypi.org/legacy/ diff --git a/README.rst b/README.rst index 2a9a862..6f495bc 100644 --- a/README.rst +++ b/README.rst @@ -480,16 +480,16 @@ release candidate tests Wheels are built for all the tested systems, and stored as artifacts for your convenience when shipping a new distribution. If you enable the ``publish`` job on the release candidate tests workflow, you can also push built release candidates to the `Test PyPI `_ server. -For this to work, you'll also need to add your Test `PyPI API token `_ to your `GitHub secrets `_. +The job uses `Trusted Publishing `_, so no API token is needed. +Instead, you'll need to add your repository as a trusted publisher in your project's settings on Test PyPI, specifying the workflow file ``test-release-candidate.yaml`` and the environment name ``testpypi``. Checkout the `pypa/gh-action-pypi-publish `_ GitHub action, and `PyPI's guide on distributing from CI `_ for more information on this. With minimal tweaks, this job can be changed to push to PyPI for real, but be careful with this since releases on PyPI can not easily be yanked. .. _Codecov: https://codecov.io/ .. _ci-packaging: https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/ -.. _github-secrets: https://docs.github.com/en/actions/reference/encrypted-secrets -.. _pypi-api-token: https://pypi.org/help/#apitoken .. _pypi-publish: https://github.com/pypa/gh-action-pypi-publish .. _testpypi: https://test.pypi.org/ +.. _trusted-publishing: https://docs.pypi.org/trusted-publishers/ Other CI/CD options From 4dd92c8fed6889a232ad1ce90669262139c58a63 Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:13:16 -0400 Subject: [PATCH 12/13] DOC: Correct claim that PyPI releases cannot easily be yanked Yanking a release is straightforward. The real hazard is that a version number can never be reused once it has been uploaded. Co-Authored-By: Claude Opus 5.5 (1M context) --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 6f495bc..2528b15 100644 --- a/README.rst +++ b/README.rst @@ -483,7 +483,7 @@ If you enable the ``publish`` job on the release candidate tests workflow, you c The job uses `Trusted Publishing `_, so no API token is needed. Instead, you'll need to add your repository as a trusted publisher in your project's settings on Test PyPI, specifying the workflow file ``test-release-candidate.yaml`` and the environment name ``testpypi``. Checkout the `pypa/gh-action-pypi-publish `_ GitHub action, and `PyPI's guide on distributing from CI `_ for more information on this. -With minimal tweaks, this job can be changed to push to PyPI for real, but be careful with this since releases on PyPI can not easily be yanked. +With minimal tweaks, this job can be changed to push to PyPI for real, but be careful with this since once a version number has been uploaded to PyPI it can never be reused, even if that release is deleted. .. _Codecov: https://codecov.io/ .. _ci-packaging: https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/ From d77ce30ee404d31c72ad8eb9dc17fe3ca05c8f20 Mon Sep 17 00:00:00 2001 From: Scott Lowe Date: Sat, 3 Oct 2026 09:13:16 -0400 Subject: [PATCH 13/13] DOC: Explain wheel build behaviour for pure and compiled packages Note that wheels are identical for pure-Python packages, and that packages with compiled extensions need manylinux wheels for PyPI. Co-Authored-By: Claude Opus 5.5 (1M context) --- .github/workflows/test-release-candidate.yaml | 4 ++++ README.rst | 3 +++ 2 files changed, 7 insertions(+) diff --git a/.github/workflows/test-release-candidate.yaml b/.github/workflows/test-release-candidate.yaml index 8e6ea25..9e0e470 100644 --- a/.github/workflows/test-release-candidate.yaml +++ b/.github/workflows/test-release-candidate.yaml @@ -12,6 +12,10 @@ # In addition, the package is built as a wheel on each OS/Python job, and these # are stored as artifacts to use for your distribution process. There is an # extra job (disabled by default) which can be enabled to push to Test PyPI. +# If your package is pure-Python, all these wheels are identical and a single +# one will be published. If your package includes compiled extensions, note +# that PyPI does not accept plain linux_* wheels; you will need to build +# manylinux wheels instead (e.g. with cibuildwheel). name: release candidate tests diff --git a/README.rst b/README.rst index 2528b15..1244d2d 100644 --- a/README.rst +++ b/README.rst @@ -478,15 +478,18 @@ release candidate tests The release candidate tests workflow runs the unit tests on more Python versions and operating systems than the regular test workflow. This runs on all tags, plus pushes and PRs to branches named like "v1.2.x", etc. Wheels are built for all the tested systems, and stored as artifacts for your convenience when shipping a new distribution. + If your package is pure-Python, these wheels will all be the same; if it includes compiled extensions, you will get a wheel for each platform and Python version. If you enable the ``publish`` job on the release candidate tests workflow, you can also push built release candidates to the `Test PyPI `_ server. The job uses `Trusted Publishing `_, so no API token is needed. Instead, you'll need to add your repository as a trusted publisher in your project's settings on Test PyPI, specifying the workflow file ``test-release-candidate.yaml`` and the environment name ``testpypi``. Checkout the `pypa/gh-action-pypi-publish `_ GitHub action, and `PyPI's guide on distributing from CI `_ for more information on this. +If your package includes compiled extensions, note that PyPI will not accept the plain ``linux_*`` wheels built by this workflow, and you should build manylinux wheels instead (for instance with cibuildwheel_). With minimal tweaks, this job can be changed to push to PyPI for real, but be careful with this since once a version number has been uploaded to PyPI it can never be reused, even if that release is deleted. .. _Codecov: https://codecov.io/ .. _ci-packaging: https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/ +.. _cibuildwheel: https://cibuildwheel.pypa.io/ .. _pypi-publish: https://github.com/pypa/gh-action-pypi-publish .. _testpypi: https://test.pypi.org/ .. _trusted-publishing: https://docs.pypi.org/trusted-publishers/