Skip to content

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.

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.