moddef.document module

Document layer (spec §4): parse and serialize the three equivalent encodings — .moddef.yaml, .moddef.json, binary .moddef. YAML and JSON follow proto3 JSON (protojson) semantics; unknown fields and invalid enum values are rejected, matching the Go/TS/Rust implementations and the fixtures under moddef/fixtures/invalid.

moddef.document.detect_format(path: str | PathLike[str]) → Literal['yaml', 'json', 'binary']

Infer the format from a file path per the spec §4 extensions.

moddef.document.load(path: str | PathLike[str]) → ModDefDocument

Load and parse a .moddef.yaml / .moddef.json / .moddef file.

moddef.document.parse_document(data: bytes | str, format: Literal['yaml', 'json', 'binary']) → ModDefDocument

Parse a document from text or bytes in the given format.

moddef.document.save(doc: ModDefDocument, path: str | PathLike[str]) → None

Serialize and write a document; the format comes from the extension.

moddef.document.serialize_document(doc: ModDefDocument, format: Literal['yaml', 'json', 'binary']) → bytes | str

Serialize a document. yaml/json return str, binary returns bytes.

Binary serialization is deterministic (ascending map keys), matching the Go-produced golden .moddef files byte for byte. It goes through canonical_bytes rather than SerializeToString(deterministic=True) because the protobuf C/upb backend orders map entries by descending key, which would not match the canonical form.