You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Every Python script turns what it reads into domain types before acting on it #248
A field that GitHub, a package registry or a subprocess renames or leaves out reaches the middle of most of the repo's Python scripts as a missing key or an Any, instead of stopping the script at its input with a sentence that names the problem. Of the 13 scripts the repo runs, 9 read JSON from gh, a registry or a subprocess, and 7 of those parse it without Pydantic. Any appears in 6 of them, most in review_dependency_bump.py, and 9 read their arguments from an argparse.Namespace. Only merge.py and capture_window.py use NewTypes for domain values.
Ideal state
Every script the repo runs turns its command-line arguments and each source of data it reads into domain types in one parse step per source, as the boundary Must in python.md describes
No value typed Any, no raw dict and no argparse.Namespace reaches code past that step, and ty confirms it
A script given malformed input ends with a sentence naming every problem it found, before it changes anything
Every script parses its command-line arguments the way the decision record below settles
How do the repo's scripts parse command-line arguments: argparse read only inside a typed parse function, or a library whose result the type checker knows, such as tyro or Typer? (new external dependency, and a CLI pattern every script follows)
Starting points
tools/agents/config/standards/python.md: the boundary Must the scripts are measured against
tools/agents/config/skills/review-code/scripts/review_dependency_bump.py: the script with the most Any and raw dict values today
tools/agents/config/skills/prove-it-works/scripts/capture_window.py: the one script that already parses both its arguments and its subprocess output into domain types
Found while reworking capture_window.py, which reads its arguments with argparse inside one typed parse function, the argparse option this ticket leaves open.
What the parse function collects: every problem in a value argparse hands over, such as a blank --app, an --out that isn't .png, a --window-id that isn't a positive number, or --title given with --window-id. With no flag marked required, missing flags are collected too. One run reported four problems together.
What it cannot collect: a flag argparse cannot read at all, such as an unknown flag or one missing its value. argparse exits 2 on the first of these, before the parse function runs, so any other problems in the same command go unreported.
What this means here: with plain argparse, the boundary rule in python.md that a parse "reports every problem it finds at once" holds for values, but not for malformed flags.
features/auth/auth.py and features/secret/secret.py are two more scripts the repo runs. Both use NewTypes and frozen-dataclass unions, and auth.py parses argocd's JSON with json.loads, without Pydantic. Both are stdlib-only and run with uv run --offline, so auth can start while the Google credentials the work package index needs have expired. A parsing library added to every script would have to keep that working.
Activity
ooloth commentedon Nov 3, 2026
Measurements for the open question
Measured on a personal Mac. Each import time is the median of 12 runs of
import x, beyond starting Python.argparseargparse.Namespace, typedAnyrichNewTypefields intactCliApp--appwas missing, it readAPP=Safarifrom the environment without saying so.NewTypefields worked.standards/python: let pre-install code parse with the stdlib
ooloth commentedon Nov 3, 2026
argparsecannot report every problem at onceFound while reworking
capture_window.py, which reads its arguments withargparseinside one typed parse function, theargparseoption this ticket leaves open.argparsehands over, such as a blank--app, an--outthat isn't.png, a--window-idthat isn't a positive number, or--titlegiven with--window-id. With no flag marked required, missing flags are collected too. One run reported four problems together.argparsecannot read at all, such as an unknown flag or one missing its value.argparseexits 2 on the first of these, before the parse function runs, so any other problems in the same command go unreported.argparse, the boundary rule inpython.mdthat a parse "reports every problem it finds at once" holds for values, but not for malformed flags.standards/python: scope "every problem at once" to the values read
ooloth commentedon Nov 5, 2026
features/auth/auth.pyandfeatures/secret/secret.pyare two more scripts the repo runs. Both useNewTypes and frozen-dataclass unions, andauth.pyparses argocd's JSON withjson.loads, without Pydantic. Both are stdlib-only and run withuv run --offline, soauthcan start while the Google credentials the work package index needs have expired. A parsing library added to every script would have to keep that working.