Repository navigation
Description
Context
CompStats is a pure-Python package (CompStats/, version read from CompStats.__version__,
currently 0.2.0; PyPI has 0.1.15). Its continuous integration is legacy and no longer matches
how the project is developed:
.github/workflows/test.yamlbuilds a conda environment and runsnosetests, only on pushes to
develop. Day-to-day development usespytest CompStats(seeCLAUDE.md)..github/workflows/pip.yamlpublishes to PyPI from a conda matrix (Linux uploads the sdist,
Windows uploads the wheel,--skip-existing). Nothing checks that the pushed tag matches
__version__, so a stale tag silently re-publishes nothing, or publishes the wrong version.pyproject.tomlhas no[build-system]table and no optionaltestdependencies.
Two sibling projects of the same maintainer (scjn and dofjson) use a simpler, stricter layout:
a test.yml workflow running pytest on a Python matrix plus a version gate, and a
publish-pypi.yml workflow triggered by a v* tag that first verifies the tag against the package
version. This issue brings that layout to CompStats. The complete file contents are given below, so
nothing has to be looked up in those repositories.
Facts already verified while planning (do not re-derive them):
- The repository secret used for the upload is named
TWINEand already exists. pytest CompStatspasses today: 74 tests, about 2.5 minutes..venv/bin/pythonis Python 3.13 and haspytest,packaging,buildandcoverage
installed. It does not havepiportwine. Do not install anything into it.
Scope
In scope:
- Replace
.github/workflows/test.yamlwith.github/workflows/test.yml(pytest). - Replace
.github/workflows/pip.yamlwith.github/workflows/publish-pypi.yml(tag-driven). - Add
scripts/check_package_versions.py(version gate against PyPI). - Add
[build-system]and atestextra topyproject.toml. - Add
CompStats/tests/test_packaging.py. - Update the test badge URL (
test.yaml->test.yml) wherever it appears, and the CI notes in
CLAUDE.md.
Out of scope:
- Publishing anything: do not create or push a git tag, do not run
twine upload, do not bump
__version__(0.2.0 is already exactly one minor release ahead of PyPI's 0.1.15, which is what
the gate requires). - Any documentation work (
docs/,quarto/, the body ofREADME.rst): that is done in follow-up
issues. Only the badge URL changes here. .github/workflows/publish.yml(the Quarto site workflow): leave it untouched.- Adding
requires-python, changing dependencies, changing classifiers, conda-forge, Windows or
macOS CI, PyPI trusted publishing. - Any change to the behaviour of the code under
CompStats/(only a new test file is added there).
Implementation plan
1. pyproject.toml
Add, at the very top of the file:
[build-system]
# 77 is the first setuptools that accepts the SPDX string form `license = "Apache-2.0"`
# used below.
requires = ["setuptools>=77.0.3"]
build-backend = "setuptools.build_meta"Add, after the dependencies = [...]/dynamic = ['version'] lines and before classifiers
(any position inside the document is fine as long as it is its own table):
[project.optional-dependencies]
# `packaging` is only needed by scripts/check_package_versions.py and its test.
test = ["pytest>=7.0", "packaging"]Careful with TOML table order: [project.optional-dependencies] starts a new table, so every key
that belongs to [project] (name, description, readme, license, dependencies, dynamic,
classifiers) must appear before it. The safest edit is to put the new table right before
[tool.setuptools.dynamic]. Leave every existing key and value unchanged.
Verify with:
.venv/bin/python -c "import tomllib; d = tomllib.load(open('pyproject.toml','rb')); print(d['build-system'], d['project']['optional-dependencies'], d['project']['classifiers'][0])"2. scripts/check_package_versions.py (new file, new scripts/ directory)
Create it with exactly this content:
#!/usr/bin/env python3
"""Check the package's local version against PyPI.
``publish-pypi.yml`` only checks, at the moment a tag is pushed, that the tag
matches ``CompStats.__version__``. Nothing checks *before* that whether the
local version is actually ahead of what PyPI has, or whether it jumped more
than one release past it. This script reports PyPI's latest version, the
local version (read from the attribute ``pyproject.toml`` declares as the
dynamic version, without importing the package, so none of its dependencies
need to be installed), and whether the local version is a valid single-step
jump ahead of PyPI: the next patch, or the next minor with patch reset to 0.
A package PyPI has never published always passes.
Usage::
python scripts/check_package_versions.py
"""
import ast
import json
import sys
import tomllib
import urllib.error
import urllib.request
from pathlib import Path
from packaging.version import Version
ROOT = Path(__file__).resolve().parents[1]
#: Name of the distribution on PyPI.
PACKAGE = "CompStats"
def pypi_latest_version(package: str = PACKAGE):
"""Return the latest version PyPI reports for `package`, or `None` if it
has never been published (a 404 from PyPI's JSON API)."""
url = f"https://pypi.org/pypi/{package}/json"
try:
with urllib.request.urlopen(url, timeout=10) as response:
return json.load(response)["info"]["version"]
except urllib.error.HTTPError as error:
if error.code == 404:
return None
raise
def local_version(package_dir: Path = ROOT) -> str:
"""Return the version ``pyproject.toml`` resolves dynamically, read
straight out of the source file its ``attr`` points at (no import)."""
with open(package_dir / "pyproject.toml", "rb") as fpt:
pyproject = tomllib.load(fpt)
attr = pyproject["tool"]["setuptools"]["dynamic"]["version"]["attr"]
module_name, attr_name = attr.rsplit(".", 1)
module_path = package_dir / module_name.replace(".", "/") / "__init__.py"
tree = ast.parse(module_path.read_text(encoding="utf-8"),
filename=str(module_path))
for node in ast.walk(tree):
if not isinstance(node, ast.Assign):
continue
if any(isinstance(t, ast.Name) and t.id == attr_name
for t in node.targets):
return ast.literal_eval(node.value)
raise ValueError(f"{attr} not found in {module_path}")
def next_versions(version: Version):
"""Return the two versions immediately ahead of `version`: the next
patch, and the next minor with patch reset to 0."""
major, minor, patch = (tuple(version.release) + (0, 0, 0))[:3]
return (Version(f"{major}.{minor}.{patch + 1}"),
Version(f"{major}.{minor + 1}.0"))
def check_package(package: str = PACKAGE, package_dir: Path = ROOT):
"""Return ``(package, pypi_version, local_version, ok, detail)``."""
pypi = pypi_latest_version(package)
local = local_version(package_dir)
if pypi is None:
return package, pypi, local, True, "never published"
local_v, pypi_v = Version(local), Version(pypi)
if local_v <= pypi_v:
return package, pypi, local, False, f"local is not ahead of PyPI ({pypi})"
next_patch, next_minor = next_versions(pypi_v)
if local_v not in (next_patch, next_minor):
return (package, pypi, local, False,
f"jumps more than one release past PyPI ({pypi}); "
f"expected {next_patch} or {next_minor}")
return package, pypi, local, True, "ok"
def main() -> int:
"""Print the verdict and return the process exit status."""
package, pypi, local, ok, detail = check_package()
print(f"{'package':<12} {'pypi':<10} {'local':<10} verdict")
verdict = "OK" if ok else "FAIL"
print(f"{package:<12} {pypi or '-':<10} {local:<10} {verdict}: {detail}")
return 0 if ok else 1
if __name__ == "__main__":
sys.exit(main())Run it once (it makes one HTTPS request to pypi.org):
.venv/bin/python scripts/check_package_versions.pyExpected output: a line ending in OK: ok with pypi = 0.1.15 and local = 0.2.0, exit
status 0. If the only failure is that the network is unreachable, say so in the commit message body
and continue; any other failure must be fixed.
3. .github/workflows/test.yml (new) and removal of test.yaml
git rm .github/workflows/test.yaml, then create .github/workflows/test.yml with exactly:
name: test
on:
push:
branches: [main, develop]
pull_request:
env:
# The suite draws seaborn figures; the runner has no display.
MPLBACKEND: Agg
jobs:
# The whole suite: no test touches the network.
test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
python-version: ["3.10", "3.11", "3.12"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- name: Install package and test dependencies
run: pip install -e ".[test]"
- name: Run tests
run: pytest CompStats
# Coverage is collected once (not per matrix cell) and sent to Coveralls,
# which the README badge reads. `.coveragerc` omits the tests package.
coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install package, test and coverage dependencies
run: |
pip install -e ".[test]"
pip install coverage coveralls
- name: Run tests with coverage
run: coverage run -m pytest CompStats
- name: Report
run: coverage report
- name: Coveralls
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: coveralls --service=github
# Hard gate on the single-step-ahead rule: __version__ may not be behind,
# equal to, or more than one release past what is published on PyPI.
check-package-versions:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install checker dependencies
run: pip install packaging
- name: Check package versions against PyPI
run: python scripts/check_package_versions.py4. .github/workflows/publish-pypi.yml (new) and removal of pip.yaml
git rm .github/workflows/pip.yaml, then create .github/workflows/publish-pypi.yml with exactly:
name: Publish to PyPI
on:
push:
tags:
- "v*"
workflow_dispatch:
concurrency:
group: publish-${{ github.ref_name }}
cancel-in-progress: false
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: Install version-check dependencies
if: github.event_name != 'workflow_dispatch'
run: pip install packaging
# Tags are the release trigger, so a stale tag (forgot to bump
# __version__) must fail loudly instead of publishing the wrong
# version. `version` is declared `dynamic` in pyproject.toml, so it is
# read the same way scripts/check_package_versions.py reads it.
- name: Verify tag matches the package version
if: github.event_name != 'workflow_dispatch'
run: |
tag_version="${GITHUB_REF_NAME#v}"
pkg_version=$(python -c "import sys; sys.path.insert(0, 'scripts'); from check_package_versions import local_version; print(local_version())")
if [ "$tag_version" != "$pkg_version" ]; then
echo "Tag version $tag_version does not match CompStats.__version__ $pkg_version" >&2
exit 1
fi
- name: Install build tooling
run: pip install build twine
# CompStats is pure Python: one sdist and one universal wheel, built once.
- name: Build sdist and wheel
run: python -m build
- name: Check package metadata
run: twine check dist/*
# `TWINE` is a repository secret holding a PyPI API token.
- name: Upload to PyPI
env:
TWINE_USERNAME: __token__
TWINE_PASSWORD: ${{ secrets.TWINE }}
run: twine upload dist/*5. Check that the package still builds
.venv/bin/python -m build --outdir "$(mktemp -d)"This downloads setuptools into an isolated environment (needs network, about 30 seconds) and must
end with Successfully built compstats-0.2.0.tar.gz and compstats-0.2.0-py3-none-any.whl (the
exact file-name casing may differ). It creates build/ and CompStats.egg-info/ in the
repository; both are already git-ignored, do not commit them. If it fails only because the network
is unreachable, say so in the commit message body and continue.
6. Badge URL
Replace actions/workflows/test.yaml with actions/workflows/test.yml in every tracked file that
has it. Today that is two occurrences (badge image and its target) in each of README.rst,
docs/source/index.rst and docs/source/metrics_api.rst. Find them with:
git grep -n "test.yaml"After the edit that command must print nothing except, possibly, lines inside this issue's own
text that you may have pasted somewhere (there should be none).
7. CLAUDE.md
In the ## Commands section, replace the sentence in parentheses that says CI still invokes
nosetests and the final Note: paragraph (the one starting ".github/workflows/test.yaml (CI)
builds the environment with conda and runs nosetests") so that they state the truth after this
change: CI (.github/workflows/test.yml) runs pytest CompStats on Python 3.10-3.12, collects
coverage for Coveralls, and runs scripts/check_package_versions.py.
Add a new ## Releasing section right after ## Commands with this content (reword freely, keep
the facts):
- The version lives in one place:
__version__inCompStats/__init__.py. scripts/check_package_versions.py(run by CI on every push and pull request) fails unless
__version__is exactly one patch or one minor release ahead of the latest version on PyPI.- To release: make sure
__version__is the version to publish, merge tomain, then create and
push the tagv<__version__>(for examplegit tag v0.2.0 && git push origin v0.2.0).
.github/workflows/publish-pypi.ymlverifies that the tag equals__version__, builds the
sdist and the wheel, runstwine checkand uploads with theTWINErepository secret. - After a release, bump
__version__before the next change is merged, otherwise the version gate
fails ("local is not ahead of PyPI").
Acceptance criteria
-
.github/workflows/test.yamland.github/workflows/pip.yamlno longer exist;
.github/workflows/test.ymland.github/workflows/publish-pypi.ymlexist with the content
above. - No tracked file mentions
nosetestsortest.yaml(git grep -n -e nosetests -e test.yaml
prints nothing). -
scripts/check_package_versions.pyexists and.venv/bin/python scripts/check_package_versions.pyexits 0 printingOK: ok(network permitting). -
pyproject.tomlparses, has[build-system]withsetuptools>=77.0.3and atestextra
containingpytest>=7.0andpackaging; every pre-existing key is unchanged. -
.venv/bin/python -m build --outdir "$(mktemp -d)"succeeds (network permitting). -
CompStats.__version__is still'0.2.0'; no tag was created. -
CLAUDE.mdno longer describes CI as legacy/nosetestsand has a## Releasingsection. -
.github/workflows/publish.ymlis byte-for-byte unchanged. -
.venv/bin/python -m pytest CompStatsis green.
Tests
Add CompStats/tests/test_packaging.py (pytest style, like the other files in that directory;
English names and docstrings). The tests package is shipped inside the wheel, so the file must skip
cleanly when it runs outside a repository checkout. Start it with:
import importlib.util
from pathlib import Path
import pytest
ROOT = Path(__file__).resolve().parents[2]
SCRIPT = ROOT / "scripts" / "check_package_versions.py"
WORKFLOWS = ROOT / ".github" / "workflows"
pytest.importorskip("tomllib") # Python 3.11+
pytest.importorskip("packaging")
pytestmark = pytest.mark.skipif(
not SCRIPT.is_file(), reason="needs the repository checkout (scripts/)")
def _load_script():
"""Import scripts/check_package_versions.py as a module"""
spec = importlib.util.spec_from_file_location("check_package_versions", SCRIPT)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return moduleRequired test functions (no test may touch the network: replace pypi_latest_version with
monkeypatch.setattr(module, "pypi_latest_version", lambda package=None: "<value>")):
test_local_version_matches_package:module.local_version()equalsCompStats.__version__.test_next_versions:next_versions(Version("0.1.15"))is(Version("0.1.16"), Version("0.2.0")).test_check_package_never_published: with PyPI returningNone,okisTrue.test_check_package_single_step: with PyPI returning a version whose next patch or next minor
equals the local version,okisTrue. Derive the fake PyPI version from the local one so the
test does not break at the next version bump, e.g. monkeypatchlocal_versionto return
"1.4.0"andpypi_latest_versionto return"1.3.7"(next minor) and then"1.3.9"with
local"1.3.10"(next patch).test_check_package_not_ahead: PyPI equal to local, and PyPI greater than local, both give
ok is False.test_check_package_jump: local"1.5.0"with PyPI"1.3.7"givesok is Falseand the
detail mentions1.3.8and1.4.0.test_workflows:test.ymlandpublish-pypi.ymlexist inWORKFLOWS;test.yamland
pip.yamldo not; the text oftest.ymlcontainspytest CompStatsand
scripts/check_package_versions.pyand does not containnosetests; the text of
publish-pypi.ymlcontainssecrets.TWINEandtwine check.test_pyproject_build_system_and_test_extra: loadpyproject.tomlwithtomlliband assert
build-system.build-backend == "setuptools.build_meta"and that thetestextra contains an
entry starting withpytest.
The command that must be green before committing (about 2.5 minutes; it prints a progress line per
test file and ends with a line like 82 passed):
.venv/bin/python -m pytest CompStatsDecisions
- Ubuntu only, Python 3.10-3.12: same matrix as the sibling projects; the package is pure
Python, so the old Windows cell only existed to upload a wheel. - One build job for both sdist and wheel: a pure-Python wheel is platform independent; the old
split across operating systems was unnecessary. - No
--skip-existingon upload: with the tag/version check a duplicate upload is a mistake
and must fail loudly. - Coveralls kept, as a single separate job, because the README badge depends on it.
requires-pythonnot added: declaring a minimum Python changes what users can install and
was not requested.- No version bump: 0.2.0 is already the next minor after PyPI's 0.1.15.
- Tests run on pushes to
mainanddevelopand on every pull request:developis the
integration branch here, unlike the sibling projects. - The version-gate script lives in
scripts/and its test inCompStats/tests/: the project's
test command ispytest CompStats, so a test outside the package would never run. - Tagging and publishing 0.2.0 is a manual step for the maintainer, after the work reaches
main.
Planned against develop at d2c6feade9eac5eb039b405ac272f70fc66458ce.
Activity
mgraffg commentedon Nov 19, 2026
Implemented on branch
issues-48-49-50, commit 7830a8a.test.yaml/pip.yamlwithtest.yml(pytest on 3.10-3.12, Coveralls, version gate) andpublish-pypi.yml(tag-driven) exactly as specified.scripts/check_package_versions.py,[build-system]+testextra inpyproject.toml,CompStats/tests/test_packaging.py(8 tests), badge URLs, and CLAUDE.md updates (new## Releasing)..venv/bin/python -m pytest CompStatsgreen (exit 0); version script printsOK: ok(pypi 0.1.15, local 0.2.0).python -m buildis not installed in.venv(and nothing may be installed), so I verified the build by callingsetuptools.build_meta.build_sdist/build_wheelon a scratch copy:compstats-0.2.0.tar.gzandcompstats-0.2.0-py3-none-any.whlbuilt. I also removed thenosetests.xmlline from.gitignoresogit grep nosetestsis empty, as the acceptance criteria require.mgraffg commentedon Nov 20, 2026
Review fix-1 (commit f4b315a, branch
issues-48-49-50):CompStats/tests/test_packaging.pyno longer contains the stringsnosetests/test.yamlliterally (built from fragments), sogit grep -e nosetests -e test.yamlis empty as the acceptance criteria require. Full suite: 100 passed.Formalize documentation, CI and PyPI publishing (#48, #49, #50) (#51)
mgraffg commentedon Nov 20, 2026
Implemented in #51, merged into develop. Commit 7830a8a.
Develop (#52)
Develop (#53)