feat(language): two files that state the same spec write one text, and canonical --check fails a file that is not in it

[FBumann]

Prompt: "I think we should do 2 PRs. One doing the cononical stuff. And another doing all the composition stuff as one, coherent design. And the PR description should explain what it adds, changes, and how the composition works. Also with a tutorial"

Note

The following content was generated by AI.

Spec.to_yaml(canonical=True) writes one text for every file that states the same spec. python -m mathspec canonical writes it. --check fails a file not in the form, and --write rewrites it.

This squashes #530 and #718 onto main after #721, in #721's words, and fixes one gap. The composition PR is stacked on this one.

What this changes

• Spec.to_yaml(canonical=True), in mathspec.canonical. The normal form puts the sections in one order and sorts declarations by name. Every expression is printed from its parsed tree: the terms of a sum, the factors of a product and the keyword arguments of a call are sorted, and a sum of two or more terms is written one term per line. Subtraction, division, powers and positional arguments keep the order written. A where string, the order of cases:, of dims and of piecewise links stay as written.
• python -m mathspec canonical FILE writes the form to stdout, or to -o. --check compares bytes, writes nothing, and exits 1 with the rewrite named. --write rewrites the file in place. The form holds no YAML comments, so --write drops them. The three targets are mutually exclusive.
• Fixed on the way: a named expression written on one line (total: a + b) serialises back as a bare string, and the form passed it through as written. Two files that differ only in its term order printed different text.
• Docs: "Comparing two specs" in reading.md, and the how-to "Compare two specs", which covers git diff through a textconv and --check in CI.

Why

A diff of two spec files shows key order, spacing and term order, none of which changes the spec. With the normal form, what is left in a diff is a difference in the spec. The composition PR also uses it to check that fragments merge back to a given file, where merge joins terms in fragment-name order.

Where it came from, gates, what was not done

Origin. The code is #530 (claude/adoring-dijkstra-yh8ubw-canonical-dump) and #718 (claude/clever-ramanujan-vsgh97, at 1affd55), squashed onto main at 188262a. The conflicts were #721's renames: mathspec.model is mathspec.spec, and the CLI positional is spec. The help text, messages, docstrings, the how-to and the tests now say "spec" where the file is meant, and the docstrings use mkdocstrings cross-references (#720). The how-to is renamed "Compare two specs", and its anchor in reading.md is #comparing-two-specs.

The fix. test_a_named_expression_written_on_one_line_is_normalised_too failed on the squashed tree before the fix, and passes after it. Every hub of the PyPSA split in #723 is a one-line term, which is how the gap showed.

Gates. Pixi cannot be installed in this container. In a Python 3.12 uv virtualenv with the pins of pixi.toml:

pytest tests -n 8                         1851 passed, 27 skipped
ruff check . / ruff format --check .      clean
pyrefly check                             0 errors (9 suppressed)
typos . / reuse lint                      clean
prettier --check (changed docs, mkdocs.yml, CHANGELOG.md)  clean
python -m zensical build --strict         the docs.python.org inventory, which the proxy refuses, and the one autoref it resolves (`pathlib.Path`)

Not run: compile-tex (the tectonic bundle download is blocked), zizmor, taplo.

Not done.

• canonical takes one file per call; a loop covers many, as the how-to shows.
• A composed spec is not written by the CLI. That needs merge, which is in the composition PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Sr4SCw5A7GUF5ARhdCaKR1

---

Generated by Claude Code

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34767415 | 📁 Comparing bdf0ae6 against latest (188262a)

  🔍 Preview build  

6 files changed · + 1 added · ± 5 modified

+ Added

• howto/compare/index.html

± Modified

• index.html
• changelog/index.html
• reference/api/index.html
• reference/reading/index.html
• reference/language/named/index.html

[FabianHofmann]

this is a very nice feature!