Skip to content

chore(deps): move maintainer tooling to PEP 735 dependency groups - #564

Merged
dgenio merged 4 commits into
mainfrom
claude/daily-critical-triage-7tip88
Aug 30, 2026
Merged

dgenio merged 4 commits into
mainfrom
claude/daily-critical-triage-7tip88

Conversation

@dgenio

@dgenio dgenio commented Aug 30, 2026

Copy link
Copy Markdown
Owner

Summary

The dev extra mixed two different things: tools that exist to run this repository's own gate (ruff, mypy, nbmake, a Jupyter kernel) and the integration packages the suite needs to exercise the published extras. Only the second kind belongs in wheel metadata — pip install chainweaver[dev] was offering a linter and a notebook kernel to anyone who wanted the library.

This splits them, and in doing so removes four hand-maintained copies of the same list.

Changes

  • dev extra removed. Maintainer tooling moves to [dependency-groups], which is never published. Verified by building the wheel and reading its METADATA: Provides-Extra no longer lists dev, and the metadata no longer mentions ruff, nbmake or opentelemetry-sdk. (opentelemetry-sdk is maintainer tooling here — the library depends on opentelemetry-api; the SDK is how the tests observe the spans it emits.)
  • New published extra integrations — one self-reference composing every user-facing integration extra. It excludes llm-anthropic/llm-openai deliberately; evals.yml adds the provider it needs. Contributors now run pip install -e ".[integrations]" --group dev.
  • Second group test-runners holds the four pytest packages, and dev includes it rather than restating it. The free-threaded 3.14t lane and the Python-next canary install exactly that group.
  • Every --group install upgrades pip first. PEP 735 support landed in pip 25.1; a gate that silently depends on whatever the runner image ships is a gate that reports a fact about its environment rather than about the code.

The drift this found

test-runners isn't tidiness. The free-threaded and Python-next lanes each hand-copied "pytest>=7" "pytest-cov>=4" "pytest-asyncio>=0.23" into their install step, and neither copy gained pytest-timeout when #543 added it — so the two lanes most likely to hang were the only two running without the ceiling #543 exists to provide. Installing the group fixes both, and test_workflows_do_not_hand_copy_the_pytest_runners stops the next copy from appearing.

Resolution is unchanged — measured, not argued

pip install --dry-run --ignore-installed -e ".[dev]"                        # old, from stashed pyproject
pip install --dry-run --ignore-installed -e ".[integrations]" --group dev   # new

old resolved: 193 | new resolved: 193
only in old: []
only in new: []
version differences: []

(The first attempt at this comparison reported "1 vs 1" because a dry run only lists what it would install and this environment already had the rest — --ignore-installed is what makes it a real comparison rather than a fact about the container.)

uv honours --group too, checked rather than assumed: uv pip install --system --dry-run -e "." --group nosuchgroup → error: The dependency group 'nosuchgroup' was not found in the project, and --group dev pulls ruff/mypy/nbmake/ipykernel/pytest-timeout. So the lowest-direct floor job keeps working (uv 0.8.17).

Testing

  • Linting passes (ruff check chainweaver/ tests/ examples/) — All checks passed!
  • Formatting check passes (ruff format --check chainweaver/ tests/ examples/) — 308 files already formatted
  • Type checking passes (python -m mypy chainweaver/ tests/) — Success: no issues found in 261 source files
  • All existing tests pass (python -m pytest tests/) — 2393 passed, 1 skipped in 33.49s
  • New tests added for new functionality — tests/test_dependency_groups.py, 8 tests

Both halves of the new guard were proven to fail against the defect they name before being kept:

  • reinstating a dev extra in [project.optional-dependencies] → test_no_dev_extra_is_published and test_published_extras_carry_no_maintainer_tooling failed;
  • adding an inline "pytest-timeout>=2.3" to fuzz.yml → test_workflows_do_not_hand_copy_the_pytest_runners failed.

Reverting each restored green. (My first attempt at the extra-guard negative check passed — because I had injected the line into [project.urls] by mistake. That was a bad probe, not a weak guard; redone correctly, it failed as intended.)

The five TOML-reading tests skip on 3.10, which has no stdlib tomllib and where the repo declines to add tomli (same trade-off as test_metadata_consistency). The three workflow scans are plain text and run on every leg; _workflow_texts() asserts it found workflows so the scan cannot pass vacuously.

Issues closed by this PR

Closes #550

Against its acceptance criteria:

  • maintainer-only tools live in [dependency-groups] — ✅
  • user-facing integrations remain [project.optional-dependencies] — ✅ (yaml, otel, contrib, langchain, llamaindex, langgraph, openai-agents, mcp, weaver-stack, test, docs all unchanged)
  • CI has an explicit test-support composition for optional integrations — ✅ the integrations extra, named once in pyproject.toml
  • contributor commands/documentation updated atomically — ✅ CONTRIBUTING, README (extras table + quickstart), docs/getting-started/installation.md, examples/README.md, CHANGELOG, and the stale .[dev] reference in the mypy override comment
  • no application-style lockfile introduced — ✅ none added

Related Issues

Refs #543 (the pytest-timeout ceiling the copied runner lists were missing).

Checklist

  • Code follows project conventions (see AGENTS.md and docs/agent-context/)
  • Public API changes are documented — the removed dev extra and the new integrations extra are in the CHANGELOG under [Unreleased] / Changed, and in the README extras table
  • No secrets or credentials included

One thing to decide

docs stays a published extra. It is maintainer-ish (mkdocs), but the README documents it as something a reader may want ("Building the docs site locally"), so removing it looked like a separate decision rather than part of this one. test_published_extras_carry_no_maintainer_tooling skips it explicitly, so if you'd rather it moved to a group, deleting that one continue is the whole change.


Generated by Claude Code

claude added 4 commits August 28, 2026 02:53
#341 moved the concurrency tests from clock-based sleeps to events. That
removed the flake but moved the failure mode: an Event.wait() whose signal
never fires no longer trips a timing assertion, it burns the runner's global
timeout and reports nothing attributable. #341's own risk note anticipated it.

Adds pytest-timeout to the dev extra and a 60s per-test ceiling with
timeout_method = "thread", chosen from measurement rather than taste:

  slowest healthy test, measured at multiplier 1        4.34s
  tests/helpers.py BARRIER_TIMEOUT_S give-up bound      5.00s
  scaled() offsets                                      sub-second

60s leaves >12x headroom over the slowest healthy test and clears
BARRIER_TIMEOUT_S by an order of magnitude, so it cannot become a flake source
itself. thread rather than signal because a test blocked in a C-level call is
not interruptible by SIGALRM, and those are exactly the hangs this catches.
The reasoning is recorded next to the setting, not just here.

One correction to the issue: it asks that the ceiling clear "BARRIER_TIMEOUT_S
multiplied by the largest CHAINWEAVER_TEST_TIMING_MULTIPLIER". BARRIER_TIMEOUT_S
is a fixed 5.0 and is deliberately NOT scaled -- helpers.py says so explicitly.
The real relationship is BARRIER_TIMEOUT_S plus scaled work, so the ceiling is
set against that instead. The multiplier is also not set anywhere under
.github/, so CI runs at 1 today.

No per-lane override added: at a 4.34s worst case nothing comes close to 60s,
so overrides would be unused machinery. Raise the single value if that changes.

Verified the ceiling actually fires rather than assuming it -- a throwaway test
calling threading.Event().wait() produced a named Timeout with a traceback at
the blocking line, not a hang. Probe removed before commit.

Same test count with and without this change, identical flags:
  main            2372 passed, 1 skipped
  this branch     2372 passed, 1 skipped
  ruff check      All checks passed!
  ruff format     263 files already formatted
  mypy            Success: no issues found in 256 source files
  coverage        93.57% (gate 80)

Closes #543

Co-Authored-By: Claude <noreply@anthropic.com>
Closes #550.

The `dev` extra mixed two different things: tools that exist to run this
repository's own gate (ruff, mypy, nbmake, a Jupyter kernel) and the
integration packages the suite needs to exercise the published extras.
Only the second kind belongs in wheel metadata, and `pip install
chainweaver[dev]` offered the first kind to anyone who wanted the
library.

- `dev` extra removed. Maintainer tooling lives in `[dependency-groups]`,
  which is not published: the built wheel's `Provides-Extra` no longer
  lists `dev`, and its METADATA no longer mentions ruff, nbmake or
  opentelemetry-sdk (verified by building the wheel and reading it).
- New published extra `integrations`: the composition of every
  user-facing integration extra, as a single self-reference. Naming it
  once is the point — the old list existed in eight workflow steps,
  CONTRIBUTING, the README, the docs site and the floor job. It excludes
  `llm-anthropic`/`llm-openai` deliberately; evals.yml adds the provider
  it needs.
- Second group `test-runners` holds the four pytest packages. The
  free-threaded 3.14t lane and the Python-next canary install exactly
  that group instead of hand-copying the list, and that copy had already
  drifted: neither gained `pytest-timeout` when #543 added it, so the two
  lanes most likely to hang were the ones running unbounded.
- Every `--group` install upgrades pip first. PEP 735 support landed in
  pip 25.1, and a gate that silently depends on whatever the runner image
  ships is a gate that reports a fact about its environment.

Resolution is unchanged, measured rather than argued:

  pip install --dry-run --ignore-installed -e ".[dev]"                  # old
  pip install --dry-run --ignore-installed -e ".[integrations]" --group dev

resolve the same 193 distributions at the same versions — set difference
empty in both directions, no version differences. uv 0.8.17 honours
`--group` too (checked: an unknown group name is rejected, and a real one
pulls ruff/mypy/nbmake), so the `lowest-direct` floor job keeps working.

New `tests/test_dependency_groups.py` (8 tests) fails when a maintainer
tool reappears in a published extra, when a workflow installs `.[dev]` or
pins a pytest runner inline, when `dev` restates the runners instead of
including the group, or when the `integrations` composition and the
integration extras disagree. Both halves were proven to fail against the
defect they name before being kept: reinstating a `dev` extra failed two
of them, and adding an inline `"pytest-timeout>=2.3"` to fuzz.yml failed
the drift guard; reverting each restored green. The TOML-reading tests
skip on 3.10, which has no stdlib tomllib and where the repo declines to
add tomli; the workflow scans run everywhere.

Validation:
  ruff check chainweaver/ tests/ examples/    All checks passed!
  ruff format --check chainweaver/ tests/ examples/   308 files already formatted
  mypy chainweaver/                           Success: no issues found in 105 source files
  pytest tests/ -q --no-cov                   2393 passed, 1 skipped

Docs updated atomically: CONTRIBUTING, README extras table and quickstart,
docs/getting-started/installation.md, examples/README.md, CHANGELOG.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XhJp1Rnr6mF4vdSLkj14jU
mypy runs at python_version = "3.10", where tomllib does not exist. Guard
the import behind the same sys.version_info check test_metadata_consistency
uses so the branch is unreachable under the configured version, and give
the helper signatures their type arguments for --strict.

mypy chainweaver/ tests/  Success: no issues found in 261 source files
ruff check / format       clean
pytest tests/test_dependency_groups.py  8 passed

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XhJp1Rnr6mF4vdSLkj14jU

dgenio commented Aug 30, 2026

Copy link
Copy Markdown
Owner Author

Not merging this — one check is red, and my rule for unattended merges is absolute

CI finished: 21 success, 1 skipped, 1 failure out of 23.

  • skipped: latest/pre-release deps (Python 3.14) — schedule-only, correct.
  • failure: Python 3.15 pre-release.

I am leaving this open rather than merging it. My standing instruction for these unattended runs is never merge with CI red, including when the red is pre-existing and demonstrably not caused by the PR. This one qualifies for "not caused by the PR", and I am still not merging it — that exception is exactly the one the rule exists to refuse.

What the red actually is

error: the configured Python interpreter version (3.15) is newer than PyO3's maximum supported version
💥 maturin failed
ERROR: Failed building wheel for cachebox
× Failed to build installable wheels for some pyproject.toml based projects
╰─> cachebox

cachebox is not something this PR installs. It arrives through deepdiff, which is a base runtime dependency of ChainWeaver — deepdiff declares cachebox>=5.2,<6 (confirmed, read from the installed distribution's metadata). Nothing in the test-runners group can pull a Rust extension; the group is four pytest packages.

So the canary is doing its job: it is reporting that ChainWeaver's dependency tree cannot build on CPython 3.15.0-rc.1 yet, because PyO3 does not support that interpreter. That is upstream, and it is the kind of warning the lane exists to surface.

inference, not confirmed: that this would fail identically on main today. Run 18 of this canary (2026-08-28, this same branch, before the change) and run 17 (scheduled, main, 2026-08-26) were both green, so something moved in the last two days — a newer cachebox, or a newer 3.15 release candidate on the runner. I did not bisect it. Worth its own issue either way; I have not opened one.

What the change itself proved

The install step reached the wheel-building stage, so pip install -e ".[test,yaml,mcp]" --group test-runners parsed and resolved fine. The lanes that actually exercise the new machinery are all green:

Lane What it proves Result
floor deps (min versions, Python 3.10) uv pip install --resolution lowest-direct -e ".[integrations]" --group dev ✅
free-threaded smoke (Python 3.14t) --group test-runners on the lane that could not take the full set ✅
lint, format, types, workflows the new anti-drift tests, and the workflow structural checks ✅
15 × OS/Python matrix cells pip install -e ".[integrations]" --group dev everywhere ✅
bench, build docs, weaver-spec conformance unaffected paths still fine ✅

Over to you

Merge it if you're happy treating the 3.15 canary as the advisory lane it is declared to be (continue-on-error: true; the workflow run concludes success — only the job-level check reports failure). Nothing here needs another push from me.


Generated by Claude Code

@dgenio
dgenio merged commit 02f1589 into main Aug 30, 2026
22 of 23 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Separate maintainer tooling into PEP 735 dependency groups

2 participants