0.4.0: top-level legaldown is the workflow and the model; Document.from_dict/to_dict; Template(text, resolve=)

[dvejsada]

This is the last API-simplification step before the 0.4.0 release. The top-level package now shows the workflow and the model, and the tooling lives in legaldown.syntax and legaldown.grammar. Nothing downstream breaks.

Changes

legaldown.__all__: 81 → 48 names

• Kept:
  • the workflow: load, parse, save, serialize, validate, load_template, parse_template, Template, Form, Question, load_answers, AnswersError, AssemblyResult, AssemblyError, LoadFile, file_loader, FrontmatterError;
  • the result types, now including Blank;
  • is_template;
  • the document model;
  • the package metadata;
  • the deprecated names until 0.5.0.
• Moved out of __all__: the lexer, fragment and definition helpers, render_block/render_item, the dict factories and BLOCK_DEFAULTS.
  • They still import from legaldown as the same objects, with no warning. A test checks every name PactTrack and legaldown-render import from legaldown, with warnings treated as errors.
  • Their supported home is legaldown.syntax or legaldown.grammar. syntax gains the definition readers (collect_definitions, definition_lookup, id_term, DefinitionRef, find_definition_anchors, DefinitionAnchor) and render_block/render_item.

Document.from_dict(data) / document.to_dict()

• These are the documented way to build a document from plain data and to dump it. They give the same results as the old functions.
• Document() is a blank document. The docs now say that empty_document() returns a starter contract, not a blank one.

Template(text, *, resolve=None)

• path is set by load_template and stays a readable attribute.
• check= becomes the private _check, used only by tests and the conformance harness.
• No deprecation is needed, because Template is new in the unreleased 0.4.0.

README

• "Python API" states the rule: legaldown is the workflow and the model, and syntax/grammar are the tooling API.
• The model section uses to_dict/from_dict.
• The Tooling API tables and the migration table cover the new names.

Verification

• 3048 tests pass with the spec fixtures corpus, 63 of them new. ruff is clean.
• Tests pin the new __all__ and what from legaldown import * yields. Each name removed from __all__ is checked to be the same object as in its new home.
• Every legaldown import statement in PactTrack (35) and legaldown-render (11) runs against this branch with -W error::DeprecationWarning.
• All 160 spec fixture documents give byte-identical validation results to main.
• Import time is unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_013WmBAc5T7UCKVdpUmg9qxz

---

Generated by Claude Code