Guides¶

Task-oriented walkthroughs of each feature. Each page assumes familiarity with the Tutorial and answers a specific question of the form "how do I do X with didactic".

Modelling¶

• Models covers the authoring patterns: declaring fields, controlling __init__, immutable updates with .with_(...), and inheritance.
• Fields is the per-field reference for dx.field(...): defaults, factories, aliases, descriptions, examples, deprecation.
• Types lists every built-in scalar type and how to add your own.
• References and embedding covers Ref[T], Embed[T], Backref[T], and the in-memory ModelPool for backref resolution.
• Tagged unions covers dx.TaggedUnion for discriminated unions.
• Computed and derived fields covers @dx.computed (recomputed every read) and @dx.derived (computed once at construction).
• Inheritance explains how class B(A) produces a panproto Theory colimit and how multi-inheritance behaves.
• Generic Models covers PEP 695 generic class syntax, the Generic[T] mixin, subscript synthesis, default propagation, and substitution through nested generic shapes.

Validation¶

• Validators covers @dx.validates and the shape of ValidationError.
• Axioms covers class-level constraints declared via __axioms__ and the supported expression syntax.

Schema evolution¶

• Lenses covers dx.Lens, dx.Iso, dx.Mapping, composition, and the law fixtures in dx.testing.
• Migrations covers register_migration, migrate, the structural fingerprint, and the persistence helpers.
• Schema diff covers dx.diff and dx.classify_change for breaking-change detection in CI.

Output and integration¶

• Code generation covers Model.emit_as(target), custom emitters, JSON Schema, Avro, and the source-language emitters.
• Self-describing JSON covers content-addressed schema URIs in payloads.
• VCS repository covers dx.Repository.init and the filesystem-backed schema store.
• CLI covers the didactic command-line tool.

Sibling packages¶

• Pydantic interop covers from_pydantic and to_pydantic from didactic-pydantic.
• Settings covers didactic-settings: env vars, dotenv, structured config files, and CLI args, with per-field provenance.
• FastAPI covers didactic-fastapi for using dx.Model types as request and response bodies.