didactic¶

A typed-data library for Python that uses panproto as its substrate. Authoring is class-based and looks like Pydantic. Underneath, every Model corresponds to a panproto Theory, every value to a panproto Schema, and every transformation between Models to a panproto Lens. The package adds the operations that fall out of that substrate: structural fingerprints, schema migrations as registered lenses, schema diffs, breaking-change classification, multi-format code generation, and a wrapper over panproto's filesystem-backed schema repository.

import didactic.api as dx


class User(dx.Model):
    """A user record."""

    id: str
    email: str = dx.field(description="primary contact")
    nickname: str = ""


u = User(id="u1", email="ada@example.org")
print(u.model_dump_json())
# {"id": "u1", "email": "ada@example.org", "nickname": ""}

Where to start¶

The documentation follows the Diátaxis structure:

• The Tutorial walks through the most common operations on a single example. Read this first if you have not used didactic before.
• The Guides are task-oriented. Each guide answers a question of the form "how do I do X". Reach for these when you know what you want to accomplish.
• The Concepts explain the underlying model: what a panproto Theory is, why didactic uses content-addressed fingerprints, what laws lenses obey. Read these when you want to understand why something is the way it is.
• The API reference is the per-symbol detail: full signatures, parameters, raised exceptions, and small examples.

Sibling distributions¶

didactic ships as a namespace package. Three sibling distributions contribute submodules under didactic.<name>:

• didactic-pydantic provides from_pydantic and to_pydantic for converting between pydantic.BaseModel and dx.Model in either direction. Install it when you need to interoperate with Pydantic-shaped code. See Guides > Pydantic interop.
• didactic-settings composes a validated model from layered configuration: a primary file and the config-group fragments it selects, profiles, overlays, environment variables, dotenv files, CLI arguments and dotted overrides, with ${...} interpolation, descent into tagged-union variants, and a record of which layer wrote each leaf. See Guides > Settings.
• didactic-fastapi provides as_response/as_request adapters and a 422 handler so dx.Model types can be used as FastAPI request and response bodies. See Guides > FastAPI.

Install only what you need:

pip install didactic                # core only
pip install didactic-pydantic       # adds didactic.pydantic
pip install didactic-settings       # adds didactic.settings
pip install didactic-fastapi        # adds didactic.fastapi

Project status¶

didactic is pre-1.0. The public API is the surface documented here. The internal panproto encoding may change between minor releases; the structural fingerprint and the migration registry format are stable across such changes (see Concepts > Fingerprints).