topmark.registry.machine.serializers¶

topmark / registry / machine / serializers

Pure serializers for registry machine-readable output.

This module converts shaped registry machine-readable output objects into serialized wire representations.

Layers: - payloads builds JSON-serializable payload structures. - envelopes wraps payloads into canonical JSON envelopes / NDJSON record objects. - This module serializes those objects: - JSON: one pretty-printed JSON string (no trailing newline). - NDJSON: an iterable of per-line JSON strings (no trailing newline per item).

Consumers (CLI commands) are responsible for emitting these strings to the active ConsoleLike (or stdout).

serialize_filetypes ¶

serialize_filetypes(*, fmt, meta, show_details)

Serialize machine-readable output for topmark registry filetypes.

Parameters:

Name	Type	Description	Default
`fmt`	`OutputFormat`	Target output format (JSON or NDJSON).	required
`meta`	`MetaPayload`	Machine metadata payload.	required
`show_details`	`bool`	If True, include extended fields.	required

Returns:

Type	Description
`str \| Iterator[str]`	JSON: pretty-printed JSON string (no trailing newline)
`str \| Iterator[str]`	NDJSON: iterable of JSON strings (one per record; no trailing newline per item)

Raises:

Type	Description
`ValueError`	If `fmt` is not JSON or NDJSON.

Source code in src/topmark/registry/machine/serializers.py

def serialize_filetypes(
    *,
    fmt: OutputFormat,
    meta: MetaPayload,
    show_details: bool,
) -> str | Iterator[str]:
    """Serialize machine-readable output for `topmark registry filetypes`.

    Args:
        fmt: Target output format (JSON or NDJSON).
        meta: Machine metadata payload.
        show_details: If True, include extended fields.

    Returns:
        - JSON: pretty-printed JSON string (no trailing newline)
        - NDJSON: iterable of JSON strings (one per record; no trailing newline per item)

    Raises:
        ValueError: If `fmt` is not JSON or NDJSON.
    """
    if fmt == OutputFormat.JSON:
        return serialize_filetypes_json(
            meta=meta,
            show_details=show_details,
        )

    if fmt == OutputFormat.NDJSON:
        return serialize_filetypes_ndjson(
            meta=meta,
            show_details=show_details,
        )

    raise ValueError(f"Unsupported machine-readable output format: {fmt!r}")

serialize_filetypes_json ¶

serialize_filetypes_json(*, meta, show_details)

Serialize machine-readable output for topmark registry filetypes.

Parameters:

Name	Type	Description	Default
`meta`	`MetaPayload`	Machine metadata payload.	required
`show_details`	`bool`	If True, include extended fields.	required

Returns:

Type	Description
`str \| Iterator[str]`	JSON: pretty-printed JSON string (no trailing newline)
`str \| Iterator[str]`	NDJSON: iterable of JSON strings (one per record; no trailing newline per item)

Source code in src/topmark/registry/machine/serializers.py

def serialize_filetypes_json(
    *,
    meta: MetaPayload,
    show_details: bool,
) -> str | Iterator[str]:
    """Serialize machine-readable output for `topmark registry filetypes`.

    Args:
        meta: Machine metadata payload.
        show_details: If True, include extended fields.

    Returns:
        - JSON: pretty-printed JSON string (no trailing newline)
        - NDJSON: iterable of JSON strings (one per record; no trailing newline per item)
    """
    payload: FileTypesPayload = build_filetypes_payload(
        show_details=show_details,
    )
    envelope: dict[str, object] = build_filetypes_json_envelope(
        meta=meta,
        payload=payload,
    )
    return serialize_json_object(envelope)

serialize_filetypes_ndjson ¶

serialize_filetypes_ndjson(*, meta, show_details)

Serialize machine-readable output for topmark registry filetypes.

Parameters:

Name	Type	Description	Default
`meta`	`MetaPayload`	Machine metadata payload.	required
`show_details`	`bool`	If True, include extended fields.	required

Returns:

Type	Description
`Iterator[str]`	Iterator of JSON strings (one per record; no trailing newline per item)

Source code in src/topmark/registry/machine/serializers.py

def serialize_filetypes_ndjson(
    *,
    meta: MetaPayload,
    show_details: bool,
) -> Iterator[str]:
    """Serialize machine-readable output for `topmark registry filetypes`.

    Args:
        meta: Machine metadata payload.
        show_details: If True, include extended fields.

    Returns:
        Iterator of JSON strings (one per record; no trailing newline per item)
    """
    payload: FileTypesPayload = build_filetypes_payload(
        show_details=show_details,
    )
    records: Iterator[dict[str, object]] = iter_filetypes_ndjson_records(
        meta=meta,
        payload=payload,
    )
    return iter_ndjson_strings(records)

serialize_processors ¶

serialize_processors(*, fmt, meta, show_details)

Serialize machine-readable output for topmark registry processors.

Parameters:

Name	Type	Description	Default
`fmt`	`OutputFormat`	Target output format (JSON or NDJSON).	required
`meta`	`MetaPayload`	Machine metadata payload.	required
`show_details`	`bool`	If True, include extended fields.	required

Returns:

Type	Description
`str \| Iterator[str]`	JSON: pretty-printed JSON string (no trailing newline)
`str \| Iterator[str]`	NDJSON: iterable of JSON strings (one per record; no trailing newline per item)

Raises:

Type	Description
`ValueError`	If `fmt` is not JSON or NDJSON.

Source code in src/topmark/registry/machine/serializers.py

def serialize_processors(
    *,
    fmt: OutputFormat,
    meta: MetaPayload,
    show_details: bool,
) -> str | Iterator[str]:
    """Serialize machine-readable output for `topmark registry processors`.

    Args:
        fmt: Target output format (JSON or NDJSON).
        meta: Machine metadata payload.
        show_details: If True, include extended fields.

    Returns:
        - JSON: pretty-printed JSON string (no trailing newline)
        - NDJSON: iterable of JSON strings (one per record; no trailing newline per item)

    Raises:
        ValueError: If `fmt` is not JSON or NDJSON.
    """
    if fmt == OutputFormat.JSON:
        return serialize_processors_json(
            meta=meta,
            show_details=show_details,
        )

    if fmt == OutputFormat.NDJSON:
        return serialize_processors_ndjson(
            meta=meta,
            show_details=show_details,
        )

    raise ValueError(f"Unsupported machine-readable output format: {fmt!r}")

serialize_processors_json ¶

serialize_processors_json(*, meta, show_details)

Serialize machine-readable output for topmark registry processors.

Parameters:

Name	Type	Description	Default
`meta`	`MetaPayload`	Machine metadata payload.	required
`show_details`	`bool`	If True, include extended fields.	required

Returns:

Type	Description
`str`	Pretty-printed JSON string (no trailing newline)

Source code in src/topmark/registry/machine/serializers.py

def serialize_processors_json(
    *,
    meta: MetaPayload,
    show_details: bool,
) -> str:
    """Serialize machine-readable output for `topmark registry processors`.

    Args:
        meta: Machine metadata payload.
        show_details: If True, include extended fields.

    Returns:
        Pretty-printed JSON string (no trailing newline)
    """
    payload: ProcessorsPayload = build_processors_payload(
        show_details=show_details,
    )
    envelope: dict[str, object] = build_processors_json_envelope(
        meta=meta,
        payload=payload,
    )
    return serialize_json_object(envelope)

serialize_processors_ndjson ¶

serialize_processors_ndjson(*, meta, show_details)

Serialize machine-readable output for topmark registry processors.

Parameters:

Name	Type	Description	Default
`meta`	`MetaPayload`	Machine metadata payload.	required
`show_details`	`bool`	If True, include extended fields.	required

Returns:

Type	Description
`Iterator[str]`	Iterator of JSON strings (one per record; no trailing newline per item)

Source code in src/topmark/registry/machine/serializers.py

def serialize_processors_ndjson(
    *,
    meta: MetaPayload,
    show_details: bool,
) -> Iterator[str]:
    """Serialize machine-readable output for `topmark registry processors`.

    Args:
        meta: Machine metadata payload.
        show_details: If True, include extended fields.

    Returns:
        Iterator of JSON strings (one per record; no trailing newline per item)
    """
    payload: ProcessorsPayload = build_processors_payload(
        show_details=show_details,
    )
    records: Iterator[dict[str, object]] = iter_processors_ndjson_records(
        meta=meta,
        payload=payload,
    )
    return iter_ndjson_strings(records)

serialize_bindings ¶

serialize_bindings(*, fmt, meta, show_details)

Serialize machine-readable output for topmark registry bindings.

Parameters:

Name	Type	Description	Default
`fmt`	`OutputFormat`	Target output format (JSON or NDJSON).	required
`meta`	`MetaPayload`	Machine metadata payload.	required
`show_details`	`bool`	If True, include extended fields.	required

Returns:

Type	Description
`str \| Iterator[str]`	JSON: pretty-printed JSON string (no trailing newline)
`str \| Iterator[str]`	NDJSON: iterable of JSON strings (one per record; no trailing newline per item)

Raises:

Type	Description
`ValueError`	If `fmt` is not JSON or NDJSON.

Source code in src/topmark/registry/machine/serializers.py

def serialize_bindings(
    *,
    fmt: OutputFormat,
    meta: MetaPayload,
    show_details: bool,
) -> str | Iterator[str]:
    """Serialize machine-readable output for `topmark registry bindings`.

    Args:
        fmt: Target output format (JSON or NDJSON).
        meta: Machine metadata payload.
        show_details: If True, include extended fields.

    Returns:
        - JSON: pretty-printed JSON string (no trailing newline)
        - NDJSON: iterable of JSON strings (one per record; no trailing newline per item)

    Raises:
        ValueError: If `fmt` is not JSON or NDJSON.
    """
    if fmt == OutputFormat.JSON:
        return serialize_bindings_json(
            meta=meta,
            show_details=show_details,
        )

    if fmt == OutputFormat.NDJSON:
        return serialize_bindings_ndjson(
            meta=meta,
            show_details=show_details,
        )

    raise ValueError(f"Unsupported machine-readable output format: {fmt!r}")

serialize_bindings_json ¶

serialize_bindings_json(*, meta, show_details)

Serialize machine-readable output for topmark registry bindings.

Parameters:

Name	Type	Description	Default
`meta`	`MetaPayload`	Machine metadata payload.	required
`show_details`	`bool`	If True, include extended fields.	required

Returns:

Type	Description
`str`	Pretty-printed JSON string (no trailing newline)

Source code in src/topmark/registry/machine/serializers.py

def serialize_bindings_json(
    *,
    meta: MetaPayload,
    show_details: bool,
) -> str:
    """Serialize machine-readable output for `topmark registry bindings`.

    Args:
        meta: Machine metadata payload.
        show_details: If True, include extended fields.

    Returns:
        Pretty-printed JSON string (no trailing newline)
    """
    payload: BindingsPayload = build_bindings_payload(
        show_details=show_details,
    )
    envelope: dict[str, object] = build_bindings_json_envelope(
        meta=meta,
        payload=payload,
    )
    return serialize_json_object(envelope)

serialize_bindings_ndjson ¶

serialize_bindings_ndjson(*, meta, show_details)

Serialize machine-readable output for topmark registry bindings.

Parameters:

Name	Type	Description	Default
`meta`	`MetaPayload`	Machine metadata payload.	required
`show_details`	`bool`	If True, include extended fields.	required

Returns:

Type	Description
`Iterator[str]`	Iterator of JSON strings (one per record; no trailing newline per item)

Source code in src/topmark/registry/machine/serializers.py

def serialize_bindings_ndjson(
    *,
    meta: MetaPayload,
    show_details: bool,
) -> Iterator[str]:
    """Serialize machine-readable output for `topmark registry bindings`.

    Args:
        meta: Machine metadata payload.
        show_details: If True, include extended fields.

    Returns:
        Iterator of JSON strings (one per record; no trailing newline per item)
    """
    payload: BindingsPayload = build_bindings_payload(
        show_details=show_details,
    )
    records: Iterator[dict[str, object]] = iter_bindings_ndjson_records(
        meta=meta,
        payload=payload,
    )
    return iter_ndjson_strings(records)