Development¶
Set up¶
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r config/requirements-dev.txt
pip install -e .
Lint and test¶
CI runs these on every pull request, and each one must pass:
ruff check wayback_archive tests
ruff format --check wayback_archive tests
mypy wayback_archive
pytest tests/ -q --cov=wayback_archive --cov-fail-under=85
ruff format wayback_archive tests rewrites files in place. The ruff and mypy settings live in pyproject.toml.
The tests never reach the network. An autouse guard in tests/conftest.py refuses every connection that is not to localhost, so a test that needs a response mocks it or serves it from a local server.
CI runs the suite on Python 3.10 to 3.14 on Linux, and on Python 3.13 on Windows and macOS. The Python versions in the CI matrix and the classifiers in pyproject.toml must match; tests/test_packaging.py fails when they do not.
Docs¶
The site is built with Zensical from docs/ and zensical.toml. Zensical needs Python 3.11 or newer, one version above the 3.10 the tool itself supports; CI builds the site on 3.13.
pip install -r docs/requirements-docs.txt
python -m zensical build --clean --strict
python -I .github/scripts/site-check.py site
The Docs workflow runs the same two steps on every pull request and deploys main to GitHub Pages. The strict build fails on a broken link or anchor inside the site (links to other sites are not fetched); site-check.py fails on what the build lets through: a page left out of the nav, a nav entry for a missing file, a missing image, a link rooted at /. python -m zensical serve previews the site while you edit.
Docker image¶
docker build -t wayback-archive .
docker run --rm -e WAYBACK_URL=... -v "$PWD/output:/output" wayback-archive
CI builds the image on every pull request and checks that it runs the CLI.
Releases¶
Set __version__ in wayback_archive/__init__.py, move the [Unreleased] entries of CHANGELOG.md under the new version, merge, tag vX.Y.Z and publish a GitHub release for the tag. The release workflow then:
- checks that the tag matches
__version__, builds the wheel and sdist, and installs the sdist in a clean environment; - publishes them to PyPI and attaches them to the GitHub release;
- pushes
drumsergio/wayback-archive:X.Y.Zand:X.Yto Docker Hub, for amd64 and arm64.
Running the workflow by hand on a tag (gh workflow run release.yml --ref vX.Y.Z) does step 1 only.
Contributing¶
Pull requests are welcome; see CONTRIBUTING.md in the repository.