Code generation

Emitter framework

didactic.codegen.Emitter

Bases: Protocol

The protocol every custom emitter implements.

ATTRIBUTE DESCRIPTION
file_extension

A class-level attribute naming the canonical filename extension for this emitter ("avsc", "ts", "graphql"). Used by didactic.codegen.write when no explicit filename template is given.

TYPE: str

Notes

Implement either or both of emit_class (Model class -> bytes) and emit_instance (Model instance -> bytes). Calls to the missing direction raise NotImplementedError.

emit_class 

emit_class(cls: type[Model]) -> bytes

Emit a Model class as bytes (e.g. a schema declaration).

emit_instance 

emit_instance(instance: Model) -> bytes

Emit a Model instance as bytes (e.g. a serialised value).

didactic.codegen.IndentWriter 

IndentWriter(indent_str: str = '    ')

A small buffer with managed indentation for emitter authors.

Mirrors panproto_protocols::emit::IndentWriter from the panproto Rust crate. Use as the standard helper for emitting nested format text.

PARAMETER DESCRIPTION
indent_str

The string used for each indent level. Defaults to four spaces.

TYPE: str DEFAULT: ' '

Examples:

>>> w = IndentWriter()
>>> w.line("class Foo:")
>>> with w.indent():
...     w.line("x: int")
>>> w.text_str()
'class Foo:\\n    x: int\\n'

line 

line(text: str = '') -> None

Emit text at the current indent level, followed by \n.

text 

text(text: str) -> None

Emit text without trailing newline. No indentation applied.

indent 

indent() -> _IndentCtx

Return a context manager that increases the indent level.

text_str 

text_str() -> str

Finalise the buffer to a string.

bytes 

bytes() -> bytes

Finalise the buffer to UTF-8 bytes.

push_indent 

push_indent() -> None

Increase the indent level by one. Prefer with w.indent():.

pop_indent 

pop_indent() -> None

Decrease the indent level by one. Prefer with w.indent():.

didactic.codegen.emitter 

emitter(name: str) -> Callable[[type[E]], type[E]]

Register a class as the emitter for name.

PARAMETER DESCRIPTION
name

The target name (e.g. "graphql_lite", "sql_postgres"). Used in Model.emit_as.

TYPE: str

RETURNS DESCRIPTION
decorator

A class decorator that calls register_emitter with an instance of the decorated class.

Examples:

>>> from didactic.codegen import emitter
>>>
>>> @emitter("yaml_compact")
... class YamlCompactEmitter:
...     file_extension = "yaml"
...
...     def emit_class(self, cls):
...         return b""  # implementation

didactic.codegen.register_emitter 

register_emitter(name: str, instance: Emitter) -> None

Register instance as the emitter for name.

PARAMETER DESCRIPTION
name

The target name.

TYPE: str

instance

An object that satisfies the Emitter protocol.

TYPE: Emitter

RAISES DESCRIPTION
TypeError

If instance does not satisfy the protocol.

didactic.codegen.list_emitters 

list_emitters() -> list[str]

List every registered emitter name.

JSON Schema

didactic.codegen.json_schema_of 

json_schema_of(cls: type[Model]) -> JsonSchemaDoc

Build a JSON Schema (Draft 2020-12) document for cls.

PARAMETER DESCRIPTION
cls

A Model subclass.

TYPE: type[Model]

RETURNS DESCRIPTION
dict

A JSON Schema object with $schema, title, type, properties, required, and (if any fields have constraints) per-property minimum / maximum / etc.

Examples:

>>> import didactic.api as dx
>>> class User(dx.Model):
...     id: str
...     age: int = 0
>>> schema = json_schema_of(User)
>>> schema["properties"]["id"]["type"]
'string'
>>> "id" in schema["required"]
True
>>> "age" in schema["required"]
False

Bulk export

didactic.codegen.write 

write(
    models: Iterable[type[Model]],
    targets: Mapping[str, str],
    *,
    filename: str = "{model_name}.{ext}",
) -> dict[str, Path]

Emit each model under each target, writing files to disk.

PARAMETER DESCRIPTION
models

The Model classes to emit.

TYPE: Iterable[type[Model]]

targets

Mapping of target_name -> output_directory. Each directory is created if it does not exist.

TYPE: Mapping[str, str]

filename

A format string for filenames. Available placeholders: {model_name} (the class name as written), {model_snake_case} (snake-case of the class name), and {ext} (the canonical extension for the target).

TYPE: str DEFAULT: '{model_name}.{ext}'

RETURNS DESCRIPTION
dict

Map of "{target}/{model_name}" to the absolute Path written.
RAISES DESCRIPTION
LookupError

If Model.emit_as does not know how to emit one of the (model, target) pairs.

Instance-level emit

didactic.codegen.io.emit 

emit(protocol: str, instance: Model) -> bytes

Encode instance as bytes in the named protocol.

PARAMETER DESCRIPTION
protocol

A panproto protocol name (e.g. "avro", "json_schema", "openapi"). Use list_protocols to enumerate.

TYPE: str

instance

A Model instance.

TYPE: Model

RETURNS DESCRIPTION
bytes

The encoded bytes.
RAISES DESCRIPTION
IoError

If the codec rejects the instance (mismatch with the Model's Theory, value out of range, etc.).

didactic.codegen.io.parse 

parse(
    protocol: str, data: bytes, *, schema: type[M]
) -> M

Decode data from protocol back to a Model instance.

PARAMETER DESCRIPTION
protocol

A panproto protocol name.

TYPE: str

data

The encoded bytes.

TYPE: bytes

schema

The expected Model class. The decoded payload is validated against this class.

TYPE: type[M]

RETURNS DESCRIPTION
Model

A new schema instance.
RAISES DESCRIPTION
IoError

If the codec cannot decode data against the schema.

didactic.codegen.io.list_protocols 

list_protocols() -> list[str]

List the supported instance-protocol names.

RETURNS DESCRIPTION
list of str

Every codec the running panproto build registers, sorted.

didactic.codegen.io.check_round_trip 

check_round_trip(protocol: str, instance: Model) -> None

Assert that parse(emit(instance)) == instance for protocol.

PARAMETER DESCRIPTION
protocol

A panproto protocol name.

TYPE: str

instance

A Model instance. The check round-trips it through the codec and asserts equality.

TYPE: Model

RAISES DESCRIPTION
AssertionError

If the round trip does not produce an equal Model.
IoError

If the codec rejects either direction.

Source-level emit

didactic.codegen.source.emit_pretty 

emit_pretty(model: type[Model], *, target: str) -> bytes

Render model as fresh source in the named target language.

PARAMETER DESCRIPTION
model

A Model subclass.

TYPE: type[Model]

target

A panproto grammar name (e.g. "rust", "typescript", "python"). Use available_targets to enumerate.

TYPE: str

RETURNS DESCRIPTION
bytes

Source code that the target grammar accepts as syntactically valid.
RAISES DESCRIPTION
PanprotoError

If the grammar rejects the schema (typically because the grammar lacks a grammar.json for de-novo emission).
Notes

The output is syntactically valid; idiomatic formatting (rustfmt spacing rules, gofmt conventions) is left to a post-processor. Configure one in pyproject.toml under [tool.didactic.emit.targets.{target}.post_process].

didactic.codegen.source.emit 

emit(schema: object, *, protocol: str) -> bytes

Re-emit a parse-recovered schema as source bytes.

PARAMETER DESCRIPTION
schema

A panproto.Schema previously returned by parse. The schema must carry byte-position fragments from the parse step.

TYPE: object

protocol

The grammar name to emit under (typically the same as the parse step).

TYPE: str

RETURNS DESCRIPTION
bytes

The reconstructed source.
Notes

Use this for edit pipelines (parse, transform, emit). For fresh emission from a Model class, use emit_pretty.

didactic.codegen.source.parse 

parse(
    source: bytes,
    *,
    protocol: str,
    file_path: str = "<source>",
) -> object

Parse source bytes into a panproto.Schema.

PARAMETER DESCRIPTION
source

The source bytes to parse.

TYPE: bytes

protocol

The grammar name (e.g. "rust", "typescript").

TYPE: str

file_path

A filename for error messages. Does not need to exist.

TYPE: str DEFAULT: '<source>'

RETURNS DESCRIPTION
Schema

The parsed schema with byte-position fragments. Pass to emit to re-emit, or to didactic.codegen.source.for_protocol for lens-style round-trip checks.

didactic.codegen.source.available_targets 

available_targets() -> list[str]

List every grammar the running panproto build supports.

RETURNS DESCRIPTION
list of str

Grammar names, sorted. "rust", "typescript", "go", "python", etc.

didactic.codegen.source.detect_language 

detect_language(path: str) -> str | None

Return the grammar name that handles path's extension, if any.

didactic.codegen.source.for_protocol 

for_protocol(protocol: str) -> Callable[[bytes], object]

Build a parse function bound to protocol.

PARAMETER DESCRIPTION
protocol

The grammar name.

TYPE: str

RETURNS DESCRIPTION
Callable

A function that takes source bytes and returns a Schema. Use in lens compositions or as a partial-application helper.