Drive the CLI from an argtree Cli spec (argtree 0.1.2) by JPHutchins · Pull Request #31 · JPHutchins/camas

JPHutchins · 2026-06-01T00:21:44Z

What this is

Replaces camas's hand-rolled argparse parser with a declarative argtree Cli spec, and consumes the typed result in dispatch instead of an Any-typed argparse.Namespace.

Originally opened as an experiment gated on three argtree gaps. Those shipped in argtree 0.1.2, so this now uses the real APIs and is ready for review.

✅ Blockers resolved in argtree 0.1.2

Issue	Shipped as	Used here
JPHutchins/argtree#9	`build_parser(..., parser_class=)` + public `add_arguments()`	`build_parser(Cli, parser_class=CamasArgumentParser, ...)` — no more `parents=[vanilla]` dance
JPHutchins/argtree#10	documented "keep the spec in an interpreted module" pattern	`parser.py` excluded from `mypycify`; argtree added to `[build-system] requires`
JPHutchins/argtree#11	clear `ConfigError` naming the shadowing field	confirmed the `list` → `list_` rename (flag stays `--list`)

What changed

File	Change
`src/camas/main/parser.py`	`Cli` NamedTuple spec (one field per arg); `build_parser` constructs it directly into `CamasArgumentParser` via `parser_class=`; new `reconstruct()` wraps `from_namespace`. Stays interpreted (excluded from mypyc).
`src/camas/main/dispatch.py`	Reads a typed `Cli` instead of poking the namespace; resolves the env-dependent `--effects` default here (`None` ⇒ absent ⇒ `default_effects_expr()`, `""` ⇒ list Effects).
`setup.py`	`parser.py` added to `_main_excluded` (mypyc).
`pyproject.toml`	`argtree>=0.1.2` in runtime deps and `[build-system] requires`.
`tests/main/test_parser.py`	Read the typed `Cli` via `reconstruct` rather than the raw namespace.

The declarative spec is the core; three runtime/state-dependent behaviors stay imperative around it — the dynamic per-matrix-axis --PY flags, the task | expression positional metavar, and the --effects default. argtree gives the real parser back, so these escape hatches remain available; camas just lands as "declarative core + imperative shell."

Why bother — the payoff

The win isn't the prettier spec; it's types. dispatch now consumes Cli (expression: str | None, dry_run: bool, …) instead of an argparse.Namespace where every field is Any. Under five strict type-checkers that removes a class of implicit-Any reads.

Verification (all green)

--help output byte-identical to the current parser
639 tests pass, 100% coverage maintained
All 5 type-checkers clean — mypy, pyright, ty, zuban, pyrefly
mypyc wheel builds and runs end-to-end: compiled dispatch.so → interpreted parser.py; build_parser() returns a CamasArgumentParser through parser_class=, dynamic --PY axis flags work

Open question for review

Is the typed-dispatch readability worth (a) a runtime dependency on argtree and (b) parser.py no longer being mypyc-compiled? Leaning yes; not an obvious slam-dunk over the working argparse.

🤖 Generated with Claude Code

Port camas.main.parser's hand-rolled argparse construction to a declarative argtree `Cli` NamedTuple, and consume the typed result in dispatch instead of an `Any`-typed argparse.Namespace. - parser.py: `Cli` spec built by argtree, bridged to CamasArgumentParser (custom --help) via argparse `parents=`. The dynamic per-axis flags, the state-dependent positional metavar, and the env-dependent --effects default stay imperative around the declarative core. - dispatch.py: read a typed `Cli` (reconstruct/from_namespace) rather than poking the namespace; resolve the --effects env default here. - parser.py excluded from mypyc — argtree resolves field types at runtime via get_type_hints, which mypyc erases — and argtree added to build-system requires so the compiled dispatcher's import still type-checks. Behavior unchanged: --help byte-identical, 639 tests pass, 100% coverage, all five type-checkers clean, and the mypyc wheel builds and runs end-to-end. Blocked on argtree enhancements before this is merge-ready: JPHutchins/argtree#9, JPHutchins/argtree#10, JPHutchins/argtree#11. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

codecov · 2026-06-01T00:22:37Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (b6131bd) to head (9f7e390).

Additional details and impacted files

@@            Coverage Diff            @@
##              main       #31   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           54        54           
  Lines         5103      5115   +12     
  Branches       275       277    +2     
=========================================
+ Hits          5103      5115   +12

Flag	Coverage Δ
unittests	`100.00% <100.00%> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

argtree 0.1.2 ships the three enhancements this branch was waiting on (JPHutchins/argtree#9, #10, #11). Swap the workarounds for the real APIs: - #9: build the parser with `parser_class=CamasArgumentParser` instead of the `parents=[vanilla]` adoption dance. The overload types the result as the subclass, so `.state` assigns without a cast. - #11: the builtin-shadow case is now a clear ConfigError; the `list_` field rename stays (the flag is still `--list`). - #10: argtree's guidance is to keep the spec in an interpreted module, which is exactly what `_main_excluded` already does — no change, now the blessed pattern. Bump the build-system argtree pin to >=0.1.2 since the build-env mypy analyzes parser.py's `parser_class=` usage. Re-verified: --help byte-identical, 639 tests pass, 100% coverage, all five type-checkers clean, mypyc wheel builds and runs (build_parser() returns a CamasArgumentParser through the compiled dispatcher). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

This PR migrates camas’s CLI definition from a hand-written argparse setup to a declarative argtree Cli spec, then updates dispatch to consume a typed CLI object instead of an argparse.Namespace with Any-typed fields.

Changes:

Introduces an argtree-based Cli NamedTuple spec and builds the parser via argtree.build_parser(..., parser_class=CamasArgumentParser).
Updates the dispatcher to use the typed Cli (via reconstruct(from_namespace)) and resolves the env-dependent --effects default in dispatch.
Updates packaging metadata to include argtree>=0.1.2 at runtime and in [build-system], and excludes parser.py from mypyc compilation.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
uv.lock	Locks the new `argtree==0.1.2` dependency.
tests/main/test_parser.py	Adjusts tests to reconstruct and assert against the typed `Cli`.
src/camas/main/parser.py	Adds the `Cli` argtree spec, switches parser construction to argtree, and adds `reconstruct()`.
src/camas/main/dispatch.py	Switches to typed CLI consumption and moves `--effects` default resolution into dispatch.
setup.py	Excludes `parser.py` from mypyc compilation due to runtime type-hint resolution needs.
pyproject.toml	Adds `argtree>=0.1.2` to runtime deps and build-system requirements.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+	matrix: list[str] = arg(
+		"--matrix",
+		action="append",
+		default=[],
+		metavar="KEY=VAL[,VAL...]",
+		help="override a matrix axis (repeatable; e.g. --matrix PY=3.13)",


The argtree runtime dependency broke `nix flake check`: nixpkgs' pythonRuntimeDepsCheck reports `Missing dependencies: argtree<1,>=0.1.2` because argtree isn't in the pinned nixpkgs and nix/package.nix never provided it. (Every other CI job was green — only the nix jobs failed.) - nix/argtree.nix: buildPythonPackage for argtree 0.1.2 (hatchling/hatch-vcs, no runtime deps, sdist pinned by hash). doCheck=false — argtree's dev tests depend on camas, so running them here would be a build cycle. - flake.nix: inject argtree into python3Packages via pythonPackagesExtensions so package.nix references it as plain `python3Packages.argtree` (the form a future nixpkgs build uses); extend the nixfmt check to cover argtree.nix. - nix/package.nix: add argtree as a base dependency. Verified locally with the CI command: `nix flake check` passes — all five package variants build (incl. the four mypyc ones), the runtime-deps check passes, nixfmt clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

JPHutchins · 2026-06-07T05:03:47Z

+	effects: str | None = arg(
+		"--effects",
+		nargs="?",
+		const="",
+		help="tuple of Effect instances; pass with no value to list available Effects "
+		"(default: Termtree, or Status('github') when GITHUB_ACTIONS=true)",
+	)


This is tricky. Does the | None really stand in for an empty tuple? Anyway, that's not really what happens. The default is TermTree, unless GitHub CI environment variable is set, and then there's the feature of adding configurable defaults.

My point is that there usually is a default, and it can't be known until runtime, and it should be displayed here, correctly, rather than giving the misleading "| None".

Aw, the "| None" is for the purpose of listing effects. IDK if we should do this, it feels like help has everything that's needed. Is there precedent for a CLI param meaning "show me the possible args" when left empty?

JPHutchins · 2026-06-14T19:21:01Z

Holding off, unsure of value. Maybe useful if sub commands are added.

JPHutchins marked this pull request as ready for review June 5, 2026 00:25

Copilot AI review requested due to automatic review settings June 5, 2026 00:25

Copilot started reviewing on behalf of JPHutchins June 5, 2026 00:25 View session

JPHutchins changed the title ~~explore: drive the CLI from an argtree Cli spec~~ Drive the CLI from an argtree Cli spec (argtree 0.1.2) Jun 5, 2026

Copilot AI reviewed Jun 5, 2026

View reviewed changes

Comment thread src/camas/main/parser.py

Comment on lines +94 to +99

matrix: list[str] = arg(

"--matrix",

action="append",

default=[],

metavar="KEY=VAL[,VAL...]",

help="override a matrix axis (repeatable; e.g. --matrix PY=3.13)",

JPHutchins commented Jun 7, 2026

View reviewed changes

JPHutchins marked this pull request as draft June 14, 2026 19:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Drive the CLI from an argtree Cli spec (argtree 0.1.2)#31

Drive the CLI from an argtree Cli spec (argtree 0.1.2)#31
JPHutchins wants to merge 3 commits into
mainfrom
explore/argtree-cli

JPHutchins commented Jun 1, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jun 1, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

JPHutchins Jun 7, 2026

Uh oh!

JPHutchins Jun 7, 2026

Uh oh!

JPHutchins commented Jun 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

JPHutchins commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this is

✅ Blockers resolved in argtree 0.1.2

What changed

Why bother — the payoff

Verification (all green)

Open question for review

Uh oh!

codecov Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

JPHutchins Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

JPHutchins Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

JPHutchins commented Jun 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JPHutchins commented Jun 1, 2026 •

edited

Loading

codecov Bot commented Jun 1, 2026 •

edited

Loading