wads creates, configures and publishes Python packages: a new project gets a Hatchling pyproject.toml and a five-line GitHub Actions stub that calls one shared reusable workflow, and every CI setting lives in [tool.wads.ci]. It also migrates legacy setup.cfg projects, wires CI secrets, and diagnoses CI failures.
Still typing code with your own fingers? Skip to For carbon-based contributors.
Skills. Twelve agent skills ship inside the package, in wads/data/skills/: setup-py-project, wads-migrate, wads-repo-doctor, wads-ci-health, wads-changelog, wads-docs-coverage, wads-docstring-render, wads-import-time, wads-pypi-polish, wads-skillify, wads-test-coverage and wads-type-coverage. Enable them either way:
pip install "wads[create]" && wads-install-skills # symlinks them into ~/.claude/skills/
gh skill install i2mint/wads wads-repo-doctor # one skill, from GitHubwads-install-skills --list prints the available names. In a clone of this repo, .claude/skills/ links every skill for Claude Code, plus the maintainer skill wads-dev-workflow (in skills/), which covers changing wads itself.
Project instructions. .claude/CLAUDE.md explains the architecture (pyproject as the single source of truth, the reusable workflow, the two-layer secrets model), the config sections, and the conventions.
What an agent can do with wads:
- Scaffold a package with
populate, or a whole repo with thesetup-py-projectskill. - Move a legacy repo to
pyproject.tomland the CI stub withwads-migrate. - Declare CI secrets and env vars with
wads-secrets add NAME. - Read or render a repo's CI configuration from Python, as below.
- Run the CI plan locally with
wads ci-local, and audit dependency licences withwads-licence-check. - Diagnose a failed run with
wads-ci-debug owner/repo.
A minimal example, runnable with only the light core (pip install wads):
from wads.ci_config import CIConfig
from wads.migration import migrate_ci_to_stub
config = CIConfig(
{
"project": {"name": "mypkg", "optional-dependencies": {"dev": ["httpx"]}},
"tool": {"wads": {"ci": {"testing": {"python_versions": ["3.12"]}}}},
}
)
assert config.python_versions == ["3.12"]
assert config.project_name == "mypkg"
# A dev extra CI would never install (no [tool.wads.ci.install].extras):
assert config.uninstalled_test_extras == {"dev": ["httpx"]}
stub = migrate_ci_to_stub() # the ci.yml a new repo gets
assert "uses: i2mint/wads/.github/workflows/uv-ci.yml@master" in stub
assert "PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}" in stubWads helps you:
- Create new Python projects with modern tooling (pyproject.toml, GitHub Actions)
- Manage CI/CD workflows with configuration-driven GitHub Actions
- Handle system dependencies declaratively in pyproject.toml
- Migrate legacy projects from setup.cfg to modern formats
- Debug CI failures with automated diagnostics
pip install wads # light core: config reading + templating engine
pip install wads[create] # full project-creation / publishing toolchain
pip install wads[all] # create + docswads ships a light core (just enough to read [tool.wads.ci] /
package.json config and run the templating engine — handy in CI) plus a
heavier create extra (requests, build, wheel, ruamel.yaml) for
scaffolding and publishing. Use wads[create] (or wads[all]) when running
populate/pack to create or publish projects.
populate my-project --root-url https://github.com/user/my-project
cd my-projectThis creates a complete project structure with:
pyproject.toml(modern build configuration)README.md,LICENSE,.gitignore- Package directory with
__init__.py - GitHub Actions CI/CD workflow (optional)
Python projects often ship a frontend component (a widget, a browser UI, a
TypeScript library). populate --frontend <profile> adds a parametrized
NPM CI alongside the Python one, following the same
"config-file-driven, fixed-workflow" model. Pick one or more profiles:
| Profile | Adds | Subdir | CI |
|---|---|---|---|
js |
package.json (npm) |
js/ |
single-package npm-ci.yml |
ts |
package.json + tsconfig.json + src/index.ts (tsup build, vitest) |
ts/ |
single-package npm-ci.yml |
ts-package |
the ts files at the repo root, no Python project (populate . -p ts-package; Node >= 22) |
. |
single-package npm-ci.yml, no path filter |
ts-monorepo |
pnpm workspace root + turbo.json + an example packages/core |
ts/ |
matrixed npm-ci-monorepo.yml |
The package each profile scaffolds (js/, ts/, or the example ts/packages/core/) gets a copy of the repo's root LICENSE (npm packs the one beside package.json), refreshed whenever the root one changes; a package you add to a monorepo later needs its own. The ts packages resolve types per condition (.d.ts for import, .d.cts for require) and type-check their tests separately (tsconfig.test.json, with Node types), so src/ builds without Node globals.
The two CIs run on their own inputs. The Python ci.yml carries a paths: filter that leaves out each npm component and its workflow file, so a change only under ts/ runs the npm CI alone and never cuts a PyPI release. The npm stub also watches the inputs it shares with the Python side: fixtures/** (the golden cases both test suites run) and rust/** when there is a Rust core; pass watch_paths= to apply_frontend for others. The filter is derived from the repo's npm-ci*.yml stubs each time the Python stub is rendered (populate, wads-migrate ci-to-stub, the on-demand flip), so re-rendering keeps it; populate --frontend on a repo whose stub predates it says to re-render. A file under the npm component that the Python tests check (one the Python side generates, say) goes back in with [tool.wads.ci.trigger] include_paths = ["ts/src/grammar.generated.ts"]. A hand-written filter that differs from the derived one is reported as a customization a re-render would drop (so ci-on-demand refuses and ci-to-stub warns); move its extra entries into include_paths and run wads-migrate ci-to-stub once (the filter is compared entry by entry, in order). wads-migrate fleet-stub skips such a stub instead of stripping it. GitHub's path filters have edges worth knowing: a workflow skipped by its filter leaves a required status check pending forever, so do not make the Python CI a required check in a polyglot repo; a diff of more than 300 files is judged on the first 300 only; tag pushes ignore the filter. The npm stub's watch paths are written when the component is scaffolded (a rust/ added later needs rust/** added to that stub by hand).
# A single TypeScript component:
populate my-project --root-url https://github.com/user/my-project --frontend ts
# Several components at once — each in its own subdir, no workflow collision:
populate my-project --root-url https://github.com/user/my-project --frontend js,ts--with-npm is kept as a back-compat alias for --frontend js.
Each component gets:
- a
package.jsonwith a namespaced"wads"config block (wads.ci.*) controlling node versions, lint/test/build commands, and publishing — analogous to[tool.wads.ci]inpyproject.toml; - a path-filtered
.github/workflows/npm-ci[-<subdir>].ymlstub calling wads's reusable NPM workflow (thejscomponent keeps the barenpm-ci.yml; every other component getsnpm-ci-<subdir>.yml, so multiple components never collide).
Validation runs on every push/PR; publishing is opt-in. It publishes only
when wads.ci.publish.enabled is true and the commit message contains
the marker [publish-npm] (deliberately distinct from the Python side).
Publishing uses npm OIDC trusted publishing + provenance by default (no
long-lived token). For a single component, customize the subdirectory and
package name with --npm-subdir / --npm-package-name.
Package manager: npm or pnpm. The single-package reusable workflow drives
npm by default and pnpm when selected — either explicitly via
wads.ci.packageManager (or populate --npm-package-manager pnpm) or
auto-detected from a pnpm-lock.yaml in the package directory. pnpm consumers
should declare a "packageManager": "pnpm@x.y.z" field in their package.json
(pnpm's own convention); the CI reads the pnpm version from there. Existing npm
consumers are unaffected (no pnpm-lock.yaml → npm). The ts-monorepo profile
is pnpm-based by design.
The profile set is extensible: register your own with
wads.profiles.register_frontend_profile(...).
Edit your pyproject.toml to configure CI behavior:
[tool.wads.ci.testing]
python_versions = ["3.10", "3.12"]
pytest_args = ["-v", "--tb=short"]
coverage_enabled = true
test_on_windows = true
[tool.wads.ci.quality.ruff]
enabled = true
[tool.wads.ci.build]
sdist = true
wheel = true
# Opt-in licence gate over the installed dependency closure (default: off).
# See "Licence Perimeter" under CI Configuration Reference.
[tool.wads.licence]
enabled = falseThe default ci.yml is a small stub that calls wads's reusable workflow
(i2mint/wads/.github/workflows/uv-ci.yml@master); all behavior is driven by
[tool.wads.ci.*] above. Publishing to PyPI happens automatically on your
repo's default branch — but only when the Linux test matrix passes.
If your tests need API keys or other secrets, declare them once and let wads wire up both the GitHub Actions transport and the job environment:
wads-secrets add OPENAI_API_KEY # env var == GitHub secret name
wads-secrets add HF_TOKEN HF_WRITE_TOKEN # env var <- differently-named secret
wads-secrets add DATABASE_URL --kind required # fail CI if the secret is unset
wads-secrets add TEST_LEVEL --variable # non-sensitive value -> repo variable
pass show openai | wads-secrets add OPENAI_API_KEY --value - # value from stdin
wads-secrets list # show what's configuredwads-secrets add (a) records the variable in [tool.wads.ci.env], (b) adds its secret to the stub's secrets: list, and (c) runs gh secret set (or gh variable set with --variable) if gh is installed (value taken from $VAR_NAME, or from stdin with --value -; it reaches gh on stdin, never on the command line). Under the hood there are two layers: a transport, where the stub passes secrets to the reusable workflow by name (PYPI_PASSWORD plus each declared one), and an env policy ([tool.wads.ci.env]: required_envvars / test_envvars / extra_envvars / defaults / secret_aliases) that decides which values become job env vars. Each declared name resolves against secrets first, then repository variables (the right home for non-sensitive values); committed constants can go straight into [tool.wads.ci.env].defaults. With --variable, the name is also recorded in [tool.wads.ci.env].variables, so stub rendering never counts it as a secret to transport. A named stub leaves out any name outside the wads secrets superset, with a note, instead of writing a line that would make the workflow unstartable. A required name that resolves to nothing fails the build; an undeclared secret is never written to the environment.
Named secrets must be in the superset in wads.ci_secrets.DEFAULT_CI_SECRETS, or GitHub rejects the workflow at parse time; wads-secrets and wads-migrate warn about such names, and the superset grows additively (adding a name never breaks a stub). The opt-in alternative, wads-migrate ci-to-stub --transport json, passes the repo's whole secrets context as one WADS_CI_SECRETS_JSON secret, so any name works. It is not the default because it hands every secret the repo can read to the called workflow, and GitHub's malicious-workflow scanner holds its runs: the run ends action_required with zero jobs and no log (#74, #101). Re-rendering a stub (wads-migrate ci-to-stub, ci-on-demand, fleet-stub) writes the named transport, converting a JSON stub, unless --transport json is given or a declared name is outside the superset.
Need ffmpeg, ODBC drivers, or other system packages in CI? Declare them in pyproject.toml:
[tool.wads.ops.ffmpeg]
description = "Multimedia framework for video/audio processing"
url = "https://ffmpeg.org/"
check.linux = "which ffmpeg"
check.macos = "which ffmpeg"
check.windows = "where ffmpeg"
install.linux = "sudo apt-get install -y ffmpeg"
install.macos = "brew install ffmpeg"
install.windows = "choco install ffmpeg -y"
note = "Required for audio processing features"The install-system-deps action in your CI workflow will automatically install these. Declare a check for every platform you install on: it skips an install that is not needed, and it is re-run after the install, so a package manager that exits 0 without installing anything (Chocolatey does this when its feed is down) fails the step instead of letting the tests run without the dependency. A failed check triggers one re-install before the step fails. A dependency whose check only passes in a fresh shell can opt out with verify_install = false.
For ffmpeg on Linux, prefer the built-in recipe over apt. apt-get install ffmpeg pulls about 99 packages from the runner's mirror, which sometimes crawls for 20+ minutes; the recipe installs a pinned, sha256-checked static ffmpeg + ffprobe build in seconds and falls back to apt (with a warning) only if the download, checksum or extraction fails. The static build is Linux x86_64 only: naming the recipe under another platform fails the dependency, and an arm64 Linux runner goes straight to apt. An unknown or mistyped recipe parameter fails the dependency, and overriding url requires its sha256:
[tool.wads.ops.ffmpeg]
check.linux = "ffmpeg -version && ffprobe -version" # running both also catches a wrong-arch or corrupt binary; tests that need ffprobe skip silently without it
install.linux = "wads:static-ffmpeg"
install.macos = "brew install ffmpeg"
# Optional overrides: url, sha256, binaries, bin_dir, download_timeout, apt_fallback
# [tool.wads.ops.ffmpeg.recipe]
# url = "https://github.com/BtbN/FFmpeg-Builds/releases/download/<month-end autobuild>/<asset>.tar.xz"
# sha256 = "<its sha256>"Create new Python projects with modern best practices:
# Basic usage
populate my-project
# With custom settings
populate my-project \
--root-url https://github.com/myorg/my-project \
--description "My awesome project" \
--author "Your Name" \
--license apacheOptions:
--root-url: GitHub repository URL--description: Project description--author: Author name--license: License type (mit, apache, bsd, etc.)--keywords: Comma-separated keywords--overwrite: Files to overwrite if they exist
Tip: Configure defaults in wads_configs.json or use WADS_CONFIGS_FILE environment variable to point to your custom config.
Build and publish packages to PyPI:
# See current configuration
pack current-configs
# Increment version and publish
pack go .
# Or step-by-step
pack increment-configs-version
pack run-setup
pack twine-upload-distMigrate legacy projects to modern format:
# Migrate setup.cfg to pyproject.toml
wads-migrate setup-to-pyproject setup.cfg -o pyproject.toml
# Migrate old CI workflow to new format
wads-migrate ci-old-to-new .github/workflows/old-ci.yml -o .github/workflows/ci.ymlPython API:
from wads.migration import migrate_setuptools_to_hatching, migrate_github_ci_old_to_new
# From setup.cfg file
pyproject_content = migrate_setuptools_to_hatching("setup.cfg")
# From setup.cfg dict
config = {"metadata": {"name": "myproject", "version": "1.0.0"}}
pyproject_content = migrate_setuptools_to_hatching(config)
# Migrate CI workflow
new_ci = migrate_github_ci_old_to_new(".github/workflows/ci.yml")Diagnose and fix GitHub Actions CI failures:
# Analyze latest failure
wads-ci-debug myorg/myrepo
# Analyze specific run
wads-ci-debug myorg/myrepo --run-id 1234567890
# Generate fix instructions
wads-ci-debug myorg/myrepo --fix --local-repo .The tool will:
- Fetch CI logs from GitHub
- Parse test failures and errors
- Identify root causes
- Generate fix instructions with file locations and suggested changes
For repos that should not run CI on every push (Actions minutes are free on public repos but metered on private ones), set:
[tool.wads.ci.trigger]
mode = "on-demand" # default "auto": every push and PR, as before
run_ci_marker = "[run ci]" # the default markerNothing runs unless asked. CI runs only when the commit subject (its first line) contains the marker, or when someone starts it by hand (gh workflow run ci.yml --ref <branch>, or the Actions tab), which is always allowed. Tests, publishing and GitHub Pages all obey the same gate.
git commit -m "Fix the parser [run ci]" # runs CI
git commit -m "Fix the parser" # runs nothingA marker quoted only in a squash-merged PR body does not count. The stub's zero-cost pre-filter lets that run start (one short setup job), and the reusable workflow checks the extracted subject before running anything else.
Worth knowing before you flip:
- The levels form a ladder:
[run ci]validates (lint, tests, build) and, whilerun_ci_publishes = true(the default), also releases from the default branch;[run deploy](deploy_marker) validates then publishes / builds Pages, whateverrun_ci_publishessays. Setrun_ci_publishes = falseto make[run ci]validate only: a cheap "did the tests pass?" that cannot ship. Publish and Pagesneed:validation, so a release never happens without it passing. - A manual run takes a
levelinput:config(default, asrun_ci_publishessays: with the default it releases on the default branch),validate, ordeploy.wads ci-local --level validate|deployis the local equivalent. - The
[publish]marker needs[run ci]or[run deploy]in the same subject (and, withrun_ci_publishes = false,[run deploy]: the publish job also needs the deploy verdict). This applies to repos with publishing disabled, where[publish]forces a release. - Re-render after upgrading. A stub rendered before
deploy_markerexisted has no[run deploy]in its pre-filter, so that marker silently runs nothing untilwads-migrate ci-to-stubre-renders it. - Only the pushed head commit's subject counts, not earlier commits in the same push.
- On-demand stubs drop the
pull_requesttrigger. A branch-protection rule that requires CI status checks will block PRs until those checks are removed from the rule.
Flip a repo in one idempotent command. It sets on-demand, python_versions = ["3.12"] and test_on_windows = false, and re-renders the stub, keeping its pin (its secrets move to the named transport):
wads-migrate ci-on-demand --dry-run # show the diff, write nothing
wads-migrate ci-on-demand --commit # apply and commit; then `git push`Do locally what CI would have done, from the same [tool.wads.ci] config:
wads ci-local # lint (ruff), tests (a fresh uv venv per python_versions entry), npm components, build
wads ci-local --dry-run # print the plan, run nothing
wads ci-local --publish # instead of the plain build: format, bump version (isee), build, PyPI upload, commit, tag, pushIn a polyglot repo, every .github/workflows stub that calls a wads npm-ci*.yml workflow (as populate --frontend writes them) also gets what that workflow's validate job runs in its package-dir: the install (npm ci with a lockfile, else npm install; pnpm install, frozen with a lockfile), then lintCommand, testCommand, buildCommand. They run in a copy of the repo inside the temporary directory, so your tree is never touched. A missing bash, node or package manager fails the run with an install hint; --no-npm leaves the npm half out, and --publish does too, as CI's PyPI publish does not wait on npm CI.
--publish refuses up front on a dirty tree, off the default branch, behind origin, or without a PyPI token ($PYPI_PASSWORD, then $UV_PUBLISH_TOKEN, then ~/.pypirc [pypi] with username = __token__). wads ci-local needs uv and git on PATH, and does not install [tool.wads.ops.*] system packages. Your shell environment reaches the steps, except PyPI credentials (only the upload sees them) the machine's install pins (UV_CONSTRAINT, UV_BUILD_CONSTRAINT, UV_OVERRIDE, PIP_CONSTRAINT), and PYTHONSAFEPATH / PYTHONPATH, none of which hosted CI has; so fleet packages resolve from PyPI as they do in CI, ci-local works from a git worktree, and python -m pytest puts the repo on sys.path as in CI. Each leg's tests run with its venv activated (VIRTUAL_ENV, its bin first on PATH), as run-tests-uv does.
To go back, set mode = "auto" and run wads-migrate ci-to-stub. Workflow files other than ci.yml (cron jobs, Pages, npm) are not governed by the trigger; ci-on-demand lists any that still run unasked.
npm trusted publishing (OIDC) needs, per package, a Trusted Publisher naming the repo and the caller workflow file. wads npm-trust finds them for you:
wads npm-trust # dry run: one row per (package, repo, workflow, environment) + the commands
wads npm-trust --fmt tsv # the same rows as TSV (or --fmt json); --offline skips the npm lookups. TSV has a trailing `publishing-disabled` column (true/false), JSON a `publishing_disabled` key; the status keeps its "(publishing disabled)" suffix
wads npm-trust --apply # run `npm trust github ...` for packages already on npm, then verifyIt discovers publishing workflows (npm publish, pnpm -r publish, changeset publish / changesets/action, pnpm release-style scripts, callers of wads npm-ci*.yml) and the non-private packages each publishes (single package or workspaces / pnpm-workspace.yaml), with the job's environment. Status is first-publish-needed (publish v1 by hand first), on-npm, or trusted. --apply needs npm >= 11.15 and an owner login with 2FA; it continues past per-package failures and exits non-zero if one failed.
Wads uses pyproject.toml as a single source of truth for CI configuration. Here's what you can configure:
New projects default to installing the dev extra in CI (.[dev]), matching
the dev extra the template declares under [project.optional-dependencies]
-- so test-time tooling (pytest, ruff, ...) actually gets installed instead of
silently never running. Override or opt out explicitly:
[tool.wads.ci.install]
extras = "dev" # or a list, e.g. ["dev", "test"]; "" installs core deps only[tool.wads.ci.testing]
python_versions = ["3.10", "3.11", "3.12"] # Test matrix
pytest_args = ["-v", "--tb=short"] # Pytest arguments
coverage_enabled = true # Enable coverage
coverage_threshold = 80 # Minimum coverage %
exclude_paths = ["examples", "scrap"] # Paths to exclude
test_on_windows = true # Run Windows tests
windows_blocking = false # true = a failing Windows leg reddens the run
job_timeout_minutes = 60 # validation jobs stop after this (GitHub's default is 6 h)job_timeout_minutes (default 60) bounds the Linux validation matrix and the Windows job, so a stalled step (an apt mirror crawling, a hung test) fails within the hour instead of holding a runner for GitHub's default six hours.
windows_blocking defaults to false: the Windows job is informational
(continue-on-error), which is how Windows-only defects — backslash path
separators, locale-decoded read_text() — merge behind a green tick. Set it to
true to make the run red. It reddens the run, not the release: publish
does not depend on the Windows job.
This knob only reaches the uv-based CI (github_ci_uv.yml / the reusable
uv-ci.yml workflow, the default for new projects). The legacy
github_ci_publish_2025.yml template and its actions/windows-tests action
still hardcode continue-on-error: true unconditionally — a failing Windows
leg there stays informational regardless of this setting. Repos on the legacy
template should migrate to the uv stub (wads-migrate ci-to-stub) to pick it
up (see #90).
To also test against an older release of a dependency (the oldest one you support, say), declare a pinned run:
[[tool.wads.ci.testing.pinned]]
name = "oldest-sdk" # names the leg; letters, digits, . _ -
requirements = ["elevenlabs==2.58.0"] # PEP 508 requirements
pytest_args = ["voxy/tests/test_elevenlabs_model.py"] # default: the repo's pytest_args
python_version = "3.10" # default: the first python_versions entryEach entry adds one leg to the Linux validation matrix, checked as Validation (pinned <name>): the normal install (with [tool.wads.ci.install].extras), then the project and the requirements installed in one resolve followed by uv pip check, so a pin outside your package's declared range fails instead of being silently overridden; then pytest with the entry's pytest_args (coverage as configured). Lint, format, type check, licence and metrics run on the normal legs only. A pinned leg is a leg of validation, so a failing one blocks publish, like any other validation leg: a release must pass on the oldest dependency it claims to support. An invalid entry (no requirements, a requirement that is not PEP 508, a bad or repeated name, an unquoted python_version) turns the setup job red rather than being skipped. Repos that declare nothing keep exactly their legs and check names (Validation (3.10), ...). wads ci-local runs the same legs. Only the reusable uv-ci.yml workflow (the default stub) runs them.
[tool.wads.ci.quality.ruff]
enabled = true
# line_length = 88
[tool.wads.ci.quality.mypy]
enabled = false
# strict = true[tool.wads.ci.commands]
pre_test = [
"python scripts/setup_test_data.py",
]
post_test = [
"python scripts/cleanup.py",
]Each command runs under bash -c in the job's activated venv: pre_test just before pytest, post_test right after it (also when the tests fail; a failing post_test fails the validation job, which blocks publish). They run once per test run, pinned-dependency legs included. wads ci-local does the same, except that it skips post_test when the tests fail.
[tool.wads.ci.build]
sdist = true
wheel = true
[tool.wads.ci.publish]
enabled = true # Publish to PyPI on main/masterWhich merges does a release contain? The publish job builds the commit its run checked out. When other PRs merged while it ran, its **CI** ... Updated version to X commit is replayed onto the newer branch tip and its subject says so: ... Updated version to X (built from <sha>) [skip ci]. The tag is on that bump commit as it was before the replay, whose parent is the built commit; do not read "the first bump commit after a merge in git log" as the first release containing it. The authoritative answer is git tag --contains <commit> --sort=v:refname | head -1.
Commit-subject markers narrow what a default-branch push does. wads matches them against the commit subject (first line) only, case-insensitively, so a marker quoted in a squash-merged PR body does not count. The one exception is [skip ci] itself: GitHub skips the whole run when it appears anywhere in the pushed commit message, body included. This also means a PR whose title carries a marker skips that job on its own squash-merge, so keep markers out of PR titles unless you mean it.
| Marker (default) | Validation | Publish (PyPI) | GitHub Pages | Rename via |
|---|---|---|---|---|
[skip ci] |
skipped (by GitHub) | skipped | skipped | [tool.wads.ci.publish].skip_ci_marker (renaming it moves only the publish and Pages gates; validation keeps [skip ci]) |
[skip publish] |
runs | skipped | runs | [tool.wads.ci.publish].skip_publish_marker |
[skip github-pages] |
runs | runs | skipped | [tool.wads.ci.docs].skip_marker |
[publish] |
runs | forced when enabled = false |
runs | [tool.wads.ci.publish].publish_marker |
[skip publish] is the one for a docs- or comment-only change: it is tested, and no PyPI version number is burned. The skip markers win over [publish].
A repo that also publishes an npm twin (populate --frontend ts) can keep one version number on both registries:
[tool.wads.ci.version]
sync = ["ts/package.json"] # manifests that carry [project].version tooThe publish job writes each release's bumped version into the listed package.json files (and the package-lock.json beside each, keeping their layout as npm version does), so the **CI** ... Updated version commit carries them all. The setup job fails when a listed file's version differs from [project].version: set them equal by hand once when you turn this on. The version then moves only with a PyPI release, so a PR that bumps only the TS version turns setup red; leave the TS version alone and let the release write it. It needs a static [project].version (not dynamic, setup.cfg or a maturin-derived one); otherwise remove the sync key. Only package.json is accepted (npm requires semver, and a PEP 440 version such as 1.0rc1 fails the publish before anything is uploaded); a Rust crate keeps its own version line.
On the npm side, npm-ci packs the commit that was pushed, which comes before the bump commit of a PyPI release cut by the same push. So when sync lists the npm package's package.json, npm-ci refuses (before anything is installed or uploaded) a publish from a push that also releases the Python package and changes files outside the npm package directory: npm would get the previous release's number with newer code. Publish npm from a commit that changes only that directory, or one whose subject carries the skip-publish marker. A release that orders npm after PyPI in one run is still open (#210). A push carrying the npm publish marker that publishes nothing because every version is already on npm fails instead of staying green; a re-run passes only when npm already holds this run's exact tarballs.
A package built with maturin (build-backend = "maturin") gets the native path automatically: one abi3 wheel per platform plus an sdist, instead of one uv build.
Scaffold one with populate my_pkg --native maturin (combinable with --frontend). It writes the layout this path builds: a root Cargo workspace whose members are rust/*, with rust/core (pure Rust, my-pkg-core) and rust/py (the PyO3 binding, my-pkg-py, built as my_pkg._core, abi3), crates licensed like the package (the SPDX expression of [project].license, else of its License :: classifiers; a licence file is never guessed from, so without either the crates declare none and populate says so), a pinned rust-toolchain.toml, clippy and rustfmt configs, the Python facade my_pkg/__init__.py with its _core.pyi stub and a pure-Python _reference.py oracle, tests/ (API and Hypothesis differential tests), and Cargo.lock when cargo and the pinned toolchain are installed (it never downloads a toolchain: otherwise it tells you to run rustup toolchain install). A new pyproject.toml gets the maturin [build-system], [tool.maturin], [tool.uv] cache-keys and pytest testpaths that include the package, so the facade's doctests run. To add a Rust core to an existing package, run it in the repo: nothing existing is rewritten. Under "Needs attention" it prints the pyproject tables to add (# Required, then # Recommended for values you set otherwise) and, when your __init__.py is kept, the lines the template's tests expect. The templates live in wads/data/native/; wads.profiles.register_native_profile adds a backend.
- Validation (every run) adds, before the install, the Rust toolchain components and a cargo cache (written only on the default branch), and after it
cargo fmt --check,cargo clippy -D warningsandcargo teston the pure-Rust crates (every workspace crate but the binding one maturin builds, which is tested through Python), once, on the first Python version.wads ci-localruns the same checks. - Release (default branch, publishing on):
native-versioncomputes the version once;native-wheelsbuilds one wheel per target with that version (PyO3/maturin-action,--release --locked), imports it from outside the repo when the runner can run it, and uploads it;publish-nativeruns the publish job's own steps withuv build --sdistplus those wheels in place ofuv build, and refuses if a release that landed meanwhile moved the version. macOS and Windows minutes (about 10x and 2x Linux) are spent only on this path, never on a PR. - Default targets:
linux-x86_64,linux-aarch64(native arm runner),macos-arm64,macos-x86_64(cross-compiled, not import-tested),windows-x64.
[tool.wads.ci.build]
native = false # opt out (e.g. you release from your own workflow), or "maturin" to opt in
[tool.wads.ci.build.native] # or the table form, for the details (all optional)
targets = ["linux-x86_64", "macos-arm64", { name = "linux-musl", runner = "ubuntu-latest", target = "x86_64-unknown-linux-musl", manylinux = "musllinux_1_2", smoke = false }] # a musl wheel cannot import on the glibc runner
maturin_args = ["--release", "--locked"]
smoke_import = "mypkg._core" # default: [tool.maturin].module-name
cargo_test_args = ["-p", "mypkg-core"] # default: derived from cargo metadata; [] skipsCommit Cargo.lock (the default --locked refuses a build without it) and enable pyo3's abi3-py3X feature (a non-abi3 wheel is refused). The Cargo workspace is found from [tool.maturin].manifest-path, so it may live below the repo root. If a release lands while the wheels are building, publish-native refuses (the wheels carry the old number): re-run all jobs, not only the failed one. A setting that does not parse fails the setup job. A pure-Python repo runs exactly the jobs it ran before. The native-selftest workflow scaffolds a package with populate --native maturin and builds it through the same actions on every target whenever the native path or its templates change.
Fails the build when the installed dependency closure carries a licence the project's policy forbids — copyleft (GPL / AGPL / LGPL), or source-available / non-commercial (SSPL, BUSL, Elastic-2.0, RAIL, CC-BY-NC).
It walks the transitive closure, not just the declared list, because that is
where the exposures actually hide, and it reads a distribution's declaration
through a precision ladder — PEP 639 License-Expression, then the
License :: trove classifiers, then the first line of the free-text
License field. No single field is enough: click declares an expression and
no classifiers, i2 declares neither and only a free-text field, and a
whole-field substring scan flags BSD-3-Clause numpy as copyleft because its
field carries an LGPL URL for a vendored notice.
Run it anywhere:
wads-licence-check # this project
wads-licence-check path/to/project --json # for a fleet sweep
wads-licence-check . --python .venv/bin/python # read another envThe CI gate is opt-in. A repo that declares nothing sees no change:
[tool.wads.licence]
enabled = true # default false: opt in per repo
include-extras = [] # [] = hard deps only; ["*"] = every extra
unknown-is-failure = true # a blank licence field is *unaudited*, not fine
unclassified-is-failure = false # e.g. MPL-2.0: reported, does not fail
[tool.wads.licence.exceptions]
certifi = "MPL-2.0 — weak, file-level, over an unmodified CA bundle. Audited 2026-08."That is the whole configuration most repos need. The allowed / forbidden
pattern lists are deliberately absent from it: they REPLACE the defaults, they
do not extend them, so writing them out by hand is a narrowing unless the list
is a superset of what ships. If you do set them, write them as TOML literal
strings — single quotes — because a basic string processes escapes and turns
"\bGPL" into a backspace character followed by GPL, which matches nothing:
[tool.wads.licence]
# Start from wads.licence_check.DFLT_FORBIDDEN and ADD, rather than replacing:
forbidden = [
'\bAGPL',
'\bAffero\b',
'\bGPL(?![\w.+-]*\s+with\b)',
'\bGNU General Public\b',
'\bLGPL',
'\bLesser General Public\b',
'\bLibrary General Public\b',
'\bNethack General Public\b',
'\bEUPL\b',
'\bBusiness Source\b',
'\bBUSL\b',
'\bSSPL\b',
'\bElastic[- ]?(2\.0|License|v2)\b',
'(?:\b|-)(?:open)?rail(?:-m)?\b',
'\bCC[- ]BY[- ]NC\b',
'\bNon[- ]?Commercial\b',
'\bProprietary\b',
'\bYourOwnAddition\b', # the point: ADD to the defaults, never restate a subset
]Exceptions take either the terse map above or an array-of-tables, which is the shape to reach for when the decision needs a record behind it:
[[tool.wads.licence.exceptions]]
dependency = "PyGithub"
licence = "LGPL (classifier only; no SPDX expression published)"
scope = "core"
decided = "2026-08-30"
decided_in = "https://github.com/thorwhalen/hubcap/issues/10"
reason = """
Accepted, not removable: PyGithub's objects are this package's values, so there
is no honest "core without it" to install. Consumed by ordinary import, neither
vendored nor patched, so the LGPL relink freedom is intact.
"""Note the table lives under [tool.wads], not [tool.wads.ci]: the policy is a
fact about the package, and the tool is useful outside CI. Only enabled is a
CI concern.
Exit codes are 0 (holds), 1 (breached) and 2 (the tool could not run —
bad config, unreadable environment, a policy that cannot detect).
Every run first proves the live policy still catches known-copyleft declarations and still clears known-permissive ones, and refuses to report at all if it cannot — a detector nobody has demonstrated is a detector nobody has checked.
The bar is per licence FAMILY, caught whole or not at all. Permitting a family
outright is a coherent stance (LGPL for dynamically linked libraries is the
usual one) and stays expressible; it is then named in every run's output, so
"PERIMETER HOLDS" is never read as "there is no LGPL in here". Catching part
of a family is refused, because it is never a stance — it is the bug. A gate
whose LGPL pattern ended in \b caught the legacy GNU Library or Lesser
classifier and missed LGPLv2, LGPLv2+, LGPLv3 and LGPLv3+, i.e. every
modern spelling, while reporting itself as working.
forbidden and a blank declaration (unknown-is-failure, default on) fail, and
so does a declared dependency that is not installed in the environment being
read: that is a piece of the perimeter nobody looked at, and it is the same
confident-green failure as reading the wrong environment. The one exception is a
requirement gated on an environment marker (tomli; python_version < "3.11"),
which is reported as NOT APPLICABLE and does not fail.
For the same reason the tool refuses to run at all on a project whose
[project].dependencies is absent or listed in dynamic — an empty closure it
could not read is not an empty closure. Write dependencies = [] if a project
genuinely has none.
System dependencies are declared using the [tool.wads.ops.*] format and automatically installed in CI via the install-system-deps action.
Format:
[tool.wads.ops.{package-name}]
description = "Description of the package"
url = "https://package-homepage.com"
# Check if already installed (exit code 0 = present)
check.linux = "which package-name"
check.macos = "brew list package-name"
check.windows = "where package-name"
# Install commands (string or list of strings)
install.linux = "sudo apt-get install -y package-name"
install.macos = "brew install package-name"
install.windows = "choco install package-name -y"
# Optional metadata
note = "Additional installation notes"
alternatives = ["alternative-package"]Real-world example (ODBC drivers):
[tool.wads.ops.unixodbc]
description = "ODBC driver interface for database connectivity"
url = "https://www.unixodbc.org/"
check.linux = "dpkg -s unixodbc || rpm -q unixODBC"
check.macos = "brew list unixodbc"
install.linux = [
"sudo apt-get update",
"sudo apt-get install -y unixodbc unixodbc-dev"
]
install.macos = "brew install unixodbc"
note = "On Alpine: apk add unixodbc unixodbc-dev"
alternatives = ["iodbc"]See misc/docs/SYSTEM_DEPENDENCIES.md for comprehensive examples.
- System Dependencies Guide -
[tool.wads.ops.*]format and examples - Migration Guide - Migrate from setup.cfg to pyproject.toml
- Utilities Reference - CLI tools (
wads-ci-debug,wads-migrate) - .claude/CLAUDE.md - AI agent guide for working with this project
If PyPI publishing fails with "appears to already exist":
WARNING Skipping mypackage-0.1.4-py3-none-any.whl because it appears to already exist
This means your git tags are misaligned with the version in pyproject.toml.
Fix:
- Check the current PyPI version: https://pypi.org/project/your-package/
- Update
versioninpyproject.tomlto a higher number - Create and push git tag:
git tag 0.1.5 git push origin 0.1.5
Use wads-ci-debug to analyze failures:
wads-ci-debug myorg/myrepo --fixCommon issues:
- Missing system dependencies → Add to
[tool.wads.ops.*] - Python version incompatibilities → Check
python_versionsin[tool.wads.ci.testing] - Test failures → Review generated fix instructions
Everything above is for users of wads, human or not. This part is for working on wads itself.
Dev setup. The test suite scaffolds and builds packages, so it needs the create extra:
uv venv && . .venv/bin/activate
uv pip install -e ".[create,docs,skills,test]"Run the tests the way CI does. CI calls pytest with no path, so testpaths = ["wads"] collects both wads/tests and every doctest in the package:
python -m pytest --doctest-modules -o doctest_optionflags='ELLIPSIS IGNORE_EXCEPTION_DETAIL' --ignore=examples --ignore=scrapCI tests Python 3.10 and 3.12; run 3.11 as well before merging, because a dataclass default once broke there and nowhere else (#100).
Build the docs with pip install -e ".[docs]" and then epythet build.
Why it is built this way. wads is a foundation package. Its reusable workflow and actions run from @master in every wads-managed repo, and every merge to master publishes a release to PyPI. So changes to .github/workflows/uv-ci.yml, actions/* or the stub template are fleet-wide changes: they come with tests (the push-back script, for example, is exercised against real throwaway git repos), and the populate output is pinned by golden files. .claude/CLAUDE.md has the design rationale, and the wads-dev-workflow skill has the maintainer checklist.
Contributing and questions. Open an issue or a pull request at github.com/i2mint/wads.
Apache Software License 2.0