Skip to content

topmark.core.machine.serializers

topmark / core / machine / serializers

Pure JSON/NDJSON serialization utilities for machine-readable output.

This module converts already-shaped machine-readable output objects (envelopes or NDJSON record mappings) into strings.

It is intentionally: - Console-free (no ConsoleLike, no printing) - Click-free - side-effect-free (serialization only)

Separation of concerns: - topmark.core.machine.payloads builds payload objects (domain data, no envelope). - topmark.core.machine.envelopes builds envelopes/records (adds meta/kind/container keys). - This module serializes those shapes to JSON/NDJSON strings.

Conventions: - json.dumps() does not append a trailing newline. - serialize_ndjson() returns a string that does end with a final \\n, which is convenient for CLI printing and piping.

serialize_json_object 

serialize_json_object(obj)

Serialize an object to pretty-printed JSON (no trailing newline).

Parameters:

Name Type Description Default
obj object

The object to serialize.

 required

Returns:

Type Description
str

A pretty-printed JSON string (no trailing newline).
Source code in src/topmark/core/machine/serializers.py 
49
50
51
52
53
54
55
56
57
58
59
60
def serialize_json_object(obj: object) -> str:
    """Serialize an object to pretty-printed JSON (no trailing newline).

    Args:
        obj: The object to serialize.

    Returns:
        A pretty-printed JSON string (no trailing newline).
    """
    normalized: object = normalize_payload(obj)
    # json.dumps() doesn't append a trailing newline
    return json.dumps(normalized, indent=2)

serialize_json_envelope 

serialize_json_envelope(meta, **payloads)

Serialize a JSON envelope with meta plus named payloads.

Parameters:

Name Type Description Default
meta MetaPayload

Metadata payload (tool/version).

 required
**payloads object

Named payload objects. Each value may be a dict-like object or an object exposing to_dict().

 {}

Returns:

Type Description
str

Pretty-printed JSON string (no trailing newline).
Source code in src/topmark/core/machine/serializers.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def serialize_json_envelope(meta: MetaPayload, **payloads: object) -> str:
    """Serialize a JSON envelope with `meta` plus named payloads.

    Args:
        meta: Metadata payload (tool/version).
        **payloads: Named payload objects. Each value may be a dict-like object or
            an object exposing `to_dict()`.

    Returns:
        Pretty-printed JSON string (no trailing newline).
    """
    envelope: dict[str, object] = build_json_envelope(
        meta=meta,
        **payloads,
    )
    # json.dumps() doesn't append a trailing newline
    return serialize_json_object(envelope)

iter_ndjson_strings 

iter_ndjson_strings(records)

Serialize shaped NDJSON records into per-line JSON strings.

Each record mapping must already include its envelope (typically "kind" and "meta").

Parameters:

Name Type Description Default
records Iterator[Mapping[str, object]]

Iterator of shaped NDJSON record mappings.

 required

Yields:

Type Description
str

One JSON string per record (no trailing newline).
Source code in src/topmark/core/machine/serializers.py 
82
83
84
85
86
87
88
89
90
91
92
93
94
95
def iter_ndjson_strings(records: Iterator[Mapping[str, object]]) -> Iterator[str]:
    r"""Serialize shaped NDJSON records into per-line JSON strings.

    Each record mapping must already include its envelope (typically `"kind"` and `"meta"`).

    Args:
        records: Iterator of shaped NDJSON record mappings.

    Yields:
        One JSON string per record (no trailing newline).
    """
    for record in records:
        # json.dumps() doesn't append a trailing newline
        yield json.dumps(record)

serialize_ndjson 

serialize_ndjson(records)

Serialize NDJSON record mappings into a newline-delimited string.

Parameters:

Name Type Description Default
records Iterator[Mapping[str, object]]

Iterator of shaped NDJSON record mappings.

 required

Returns:

Type Description
str

A string containing one JSON object per line, ending with a trailing newline.
Source code in src/topmark/core/machine/serializers.py 
 98
 99
100
101
102
103
104
105
106
107
def serialize_ndjson(records: Iterator[Mapping[str, object]]) -> str:
    """Serialize NDJSON record mappings into a newline-delimited string.

    Args:
        records: Iterator of shaped NDJSON record mappings.

    Returns:
        A string containing one JSON object per line, ending with a trailing newline.
    """
    return "\n".join(iter_ndjson_strings(records)) + "\n"