topmark.core.machine package index¶
Core machine-readable output infrastructure.
This package implements TopMark's canonical JSON/NDJSON machine-readable formats.
Separation of concerns (naming + placement):
1) Schema primitives (keys/kinds/domains + normalization)
- topmark.core.machine.schemas
- Examples:
- MachineKey, MachineKind, MachineDomain, MetaPayload
- normalize_payload(...)
2) Payload builders (domain data only; no envelope/kind/meta)
- topmark.<domain>.machine.payloads
- Naming: build_*_payload(...), iter_*_items(...)
- Returns: dataclass / dict / TypedDict (not an envelope)
3) Shape builders (envelopes and NDJSON records; still not serialized)
- topmark.core.machine.envelopes
- Naming:
- build_json_envelope(...) -> dict
- build_ndjson_record(...) -> dict
- build_*_json_envelope(...) / build_*_ndjson_records(...)
4) Serialization (turn shapes into strings; no printing)
- topmark.core.machine.serializers
- Naming:
- serialize_* returns str
- iter_*_strings yields per-record strings
- Notes:
- json.dumps() does not add a trailing newline.
- serialize_ndjson(...) returns a string that ends with \\n.
5) CLI emission (printing to ConsoleLike / stdout)
- Lives under topmark.cli.*
- Naming:
- reserve emit_* for side-effecting "print" operations
- keep pure functions under serialize_* / build_*
Rule of thumb:
- If it imports ConsoleLike or click, it should not live in core.machine.
- If it imports json only, it is typically a serializer and belongs in core.machine.serializers.
Immediate children in this package¶
- topmark.core.machine.envelopes
- Envelope and record shaping utilities for machine-readable output.
- topmark.core.machine.payloads
- Payload builders for core machine-readable output.
- topmark.core.machine.schemas
- Canonical schema primitives for TopMark machine-readable output.
- topmark.core.machine.serializers
- Pure JSON/NDJSON serialization utilities for machine-readable output.