refactor: no signature in the package says Any, and a symbol table section that is not a mapping is refused

[FBumann]

Prompt: "Improve the typehinting. We should be able to get rid of any in all places" — "I feel like some more advanced patterns aren't needed. Or they don't earn their keep"

Note

The following content was generated by AI.

Stacked on #566. src/math_spec has no Any left, pyrefly check is at 0 errors with one pragma fewer, and one crash became a refusal along the way: a symbol table whose dimensions: or names: is a list or a string raised AttributeError and now raises SchemaError naming the rewrite.

What each Any became

• The public doors take Mapping[str, object] in place of dict[str, Any]: to_spec, to_program, advice, typeset, typeset_declaration, to_latex/to_typst/to_markdown and SymbolTable.load. A mapping is covariant in its values, so every dict a caller has today still passes; to_spec tests isinstance(model, Mapping) accordingly. The three per-format doors forward **options: Unpack[_Options], a TypedDict of typeset's own keywords, so a misspelled option is a type error rather than a TypeError at the call.
• A raw value is object until pydantic has read it: every mode='before' validator, _without_absence, _is_absent, the YAML reader's return, to_dict, and the raw model the piecewise expansion writes into. Spec.model_validate spells pydantic's own signature (extra, context and the rest) instead of *args: Any, **kwargs: Any; the override stays because its docstring and test_an_expansion_will_not_be_built_around_a_curve hold it to raising the package's errors. The piecewise expansion reads its sections through _section, which asserts the mapping a validated model guarantees, and takes the mask parameter's dims off the schema rather than off the raw dict.
• The grammars hand back the node type their child walk names: parse_text[T] is generic over the walk, as depth[T] beside it already was, so parse_expression needs no cast; the where side names _ParsedWhere, the union the depth measurement walks; the two parse actions return ArithmeticNode and the connective folder returns a where node.
• The exclusivity proof compares a cell with a literal of its own kind. _Literal is what a where comparison is written against. The one gap-walk over Any with its _step/_between pair is two typed walks, _numeric_cells and _dated_cells, and the pragma that excused _between's return is gone with it. _ordered[T: (float, str, datetime.date)] names the three kinds a literal comes in, and _compare narrows both sides before calling it; a cell and a literal of different kinds, which the dtype rules keep apart, are an AssertionError rather than a TypeError at <.

What the second commit took back out

The first cut used a four-method Protocol with Self for _ordered, two type statements, and a cast on the symbol table section. A constrained type variable says the same in one line, the two aliases are the plain unions every other alias in the package is, and the section needs no cast once narrowed. What stays on purpose: parse_text[T] mirrors the existing depth[T]; the TypedDict is the one way to type forwarded keywords without stating typeset's signature four times.

Behaviour

One change a user can see, in tests/typesetting/test_symbols.py: {'dimensions': ['generator']} and {'names': 'p_max'} are refused with dimensions: must be a mapping of names to entries, got list. On the base tree both crash with 'list' object has no attribute 'items'. Nothing else the suite covers changed: the golden output and the schema did not move.

Gates

pixi.sh is refused by this environment's egress proxy, so the gates ran from a uv environment on Python 3.13 with pydantic 2.13.5 against the lock's 2.13.4. That is a departure from the "everything runs in a pixi environment" default.

gate	result
pytest -n auto	1351 passed, 1 skipped (#566: 1349 passed, 1 skipped)
ruff check, ruff format	clean
pyrefly check	0 errors, 9 suppressed (#566: 10 suppressed)
typos, reuse lint	clean
mkdocs build --strict	clean, with the docs.python.org inventory dropped for the run, which the proxy refuses with a 403
compile-tex	not run, for want of a TeX distribution
grep -rn '\bAny\b' src/	no match

Left alone, and what lpspec sees

• to_dict() returns dict[str, object]. lpspec's expressions.py hands it to a dict[str, Any] parameter, which accepts it, so lpspec type-checks as it did; indexing into the result from typed code now needs a narrowing, which is what a YAML document is.
• The implicit-any-lambda pragmas on the parse actions stay, for the reason pyproject.toml gives: a typed callback only moves the error into pyparsing's untyped ParseResults.
• _yaml.py keeps its one unknown-variable-type pragma on construct_document, whose stub returns Any.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EEeM2YoAk4Xr2uWB5qwMsH

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34652705 | 📁 Comparing e1621d6 against latest (3317ecf)

  🔍 Preview build  

21 files changed · ± 21 modified

± Modified

• examples/commitment/index.html
• examples/operators/index.html
• examples/pypsa/index.html
• examples/pypsa_linearized_uc/index.html
• howto/declare-a-column/index.html
• reference/notation/index.html
• reference/reading/index.html
• reference/language/expressions/index.html
• reference/language/operators/index.html
• reference/math_spec/advice/index.html
• and 11 more...