Repository navigation
chore(deps): move maintainer tooling to PEP 735 dependency groups - #564
Conversation
#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
Not merging this — one check is red, and my rule for unattended merges is absoluteCI finished: 21 success, 1 skipped, 1 failure out of 23.
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
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.
What the change itself provedThe install step reached the wheel-building stage, so
Over to youMerge it if you're happy treating the 3.15 canary as the advisory lane it is declared to be ( Generated by Claude Code |
Summary
The
devextra 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
devextra removed. Maintainer tooling moves to[dependency-groups], which is never published. Verified by building the wheel and reading its METADATA:Provides-Extrano longer listsdev, and the metadata no longer mentionsruff,nbmakeoropentelemetry-sdk. (opentelemetry-sdkis maintainer tooling here — the library depends onopentelemetry-api; the SDK is how the tests observe the spans it emits.)integrations— one self-reference composing every user-facing integration extra. It excludesllm-anthropic/llm-openaideliberately;evals.ymladds the provider it needs. Contributors now runpip install -e ".[integrations]" --group dev.test-runnersholds the four pytest packages, anddevincludes it rather than restating it. The free-threaded 3.14t lane and the Python-next canary install exactly that group.--groupinstall 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-runnersisn'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 gainedpytest-timeoutwhen #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, andtest_workflows_do_not_hand_copy_the_pytest_runnersstops the next copy from appearing.Resolution is unchanged — measured, not argued
(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-installedis what makes it a real comparison rather than a fact about the container.)uvhonours--grouptoo, 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 devpulls ruff/mypy/nbmake/ipykernel/pytest-timeout. So thelowest-directfloor job keeps working (uv 0.8.17).Testing
ruff check chainweaver/ tests/ examples/) —All checks passed!ruff format --check chainweaver/ tests/ examples/) —308 files already formattedpython -m mypy chainweaver/ tests/) —Success: no issues found in 261 source filespython -m pytest tests/) —2393 passed, 1 skipped in 33.49stests/test_dependency_groups.py, 8 testsBoth halves of the new guard were proven to fail against the defect they name before being kept:
devextra in[project.optional-dependencies]→test_no_dev_extra_is_publishedandtest_published_extras_carry_no_maintainer_toolingfailed;"pytest-timeout>=2.3"tofuzz.yml→test_workflows_do_not_hand_copy_the_pytest_runnersfailed.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
tomlliband where the repo declines to addtomli(same trade-off astest_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:
[dependency-groups]— ✅[project.optional-dependencies]— ✅ (yaml,otel,contrib,langchain,llamaindex,langgraph,openai-agents,mcp,weaver-stack,test,docsall unchanged)integrationsextra, named once inpyproject.tomldocs/getting-started/installation.md,examples/README.md, CHANGELOG, and the stale.[dev]reference in the mypy override commentRelated Issues
Refs #543 (the
pytest-timeoutceiling the copied runner lists were missing).Checklist
AGENTS.mdanddocs/agent-context/)devextra and the newintegrationsextra are in the CHANGELOG under[Unreleased] / Changed, and in the README extras tableOne thing to decide
docsstays 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_toolingskips it explicitly, so if you'd rather it moved to a group, deleting that onecontinueis the whole change.Generated by Claude Code