refactor: the expression parser is package-private, and the parsed tree is named apart from the program's

[FBumann]

Prompt: "Lets work on #337, starting from pulled main!"

Note

The following content was generated by AI.

expression_parser.py becomes _expression_parser.py — package-private and off the generated API docs (the docs hooks skip _*.py), the end state #323 gave the where grammar. The public surface is now exactly Spec + Program, with everything between private; __init__'s "reachable by module path for a renderer" sentence dies with the exposure it described. The parsed union is renamed ParsedNode, so ExpressionNode means one thing in the package: the lowered vocabulary a consumer reads. Closes #337.

Breaking (described here per the refused-marker rule): importers of math_spec.expression_parser break on the module path. There is no known external importer — no lpspec repo exists, docs never referenced the module — so the break is theoretical.

Two sentences swept with the decision: __init__'s "stays path-reachable deliberately" paragraph (written in #327, before #337 decided otherwise), and the module docstring's claim that the AST "can be evaluated against a namespace of linopy variables and xarray parameters" — an engine claim #315 retired from the program side.

Stack: on #346, at the maintainer's direction — the small independent diff goes to main first, the rename rides on it.

Verified

pixi run ci exit 0 in this worktree on #346's head (itself on origin/main post-#345): lint clean, 1011 passed, mkdocs build --strict builds (the module's API page drops out via the hooks' [!_]*.py glob — a dangling nav entry would fail the strict build), 27 TeX documents compile; working tree clean after the run. git grep math_spec.expression_parser finds nothing; ParsedNode lives in _expression_parser with four internal importers (degree, dimensions, expansion, resolution).

No behaviour change — every test passes untouched except import paths; the 13 lint fixes in the diff are ruff's import re-sorts for the underscored name.

Deliberately not done: renaming ArithmeticNode (no collision), and any grammar/AST split within the private module — privacy removes the reason the where side needed one.

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34348479 | 📁 Comparing b8331ba against latest (3657ec6)

  🔍 Preview build  

25 files changed · ± 24 modified · - 1 deleted

± Modified

• index.html
• CHANGELOG/index.html
• reference/typeset/index.html
• reference/language/expressions/index.html
• reference/math_spec/advice/index.html
• reference/math_spec/boundedness/index.html
• reference/math_spec/degree/index.html
• reference/math_spec/dimensions/index.html
• reference/math_spec/errors/index.html
• reference/math_spec/exclusivity/index.html
• and 14 more...

- Deleted

• reference/math_spec/expression_parser/index.html