topmark.config.machine.serializers

topmark / config / machine / serializers

Serialization helpers for config-related machine-readable output.

This module turns shaped config records/envelopes into JSON or NDJSON strings.

Responsibilities

• Validate that the requested format is a supported machine-readable format.
• Delegate envelope construction to topmark.config.machine.envelopes.
• Delegate JSON/NDJSON string rendering to topmark.core.machine.serializers.

This module is intentionally I/O-free: it returns strings (JSON) or iterators of strings (NDJSON lines) for the CLI layer to print.

serialize_config

serialize_config(
    *,
    meta,
    config,
    fmt,
    resolved_toml,
    show_config_layers=False,
)

Serialize the effective FrozenConfig snapshot in a machine-readable format.

Shapes

• JSON, default:
• JSON, with provenance:
• NDJSON, default:
• NDJSON, with provenance: {"kind": "config_provenance", "meta": ..., "config_provenance": ...}

Parameters:

Name	Type	Description	Default
meta	MetaPayload	Machine-output metadata (tool/version).	required
config	FrozenConfig	Immutable runtime configuration to serialize.	required
fmt	OutputFormat	Target machine-readable format (JSON or NDJSON).	required
resolved_toml	ResolvedTopmarkTomlSources	Resolved TOML sources for optional provenance export.	required
show_config_layers	bool	If True, include layered TOML provenance in the machine-readable output.	False

Returns:

Type	Description
str | Iterator[str]	A pretty-printed JSON string, or an iterator of NDJSON lines, depending on
str | Iterator[str]	fmt (no trailing newline).

Raises:

Type	Description
ValueError	If fmt is not a supported machine-readable format.

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

def serialize_config(
    *,
    meta: MetaPayload,
    config: FrozenConfig,
    fmt: OutputFormat,
    resolved_toml: ResolvedTopmarkTomlSources,
    show_config_layers: bool = False,
) -> str | Iterator[str]:
    """Serialize the effective `FrozenConfig` snapshot in a machine-readable format.

    Shapes:
      - JSON, default:
            {"meta": ..., "config": ...}
      - JSON, with provenance:
            {"meta": ..., "config_provenance": ..., "config": ...}
      - NDJSON, default:
            {"kind": "config", "meta": ..., "config": ...}
      - NDJSON, with provenance:
            {"kind": "config_provenance", "meta": ..., "config_provenance": ...}
            {"kind": "config", "meta": ..., "config": ...}

    Args:
        meta: Machine-output metadata (tool/version).
        config: Immutable runtime configuration to serialize.
        fmt: Target machine-readable format (JSON or NDJSON).
        resolved_toml: Resolved TOML sources for optional provenance export.
        show_config_layers: If `True`, include layered TOML provenance in the
            machine-readable output.

    Returns:
        A pretty-printed JSON string, or an iterator of NDJSON lines, depending on
        `fmt` (no trailing newline).

    Raises:
        ValueError: If `fmt` is not a supported machine-readable format.
    """
    if not is_machine_format(fmt):
        raise ValueError(f"Unsupported machine-readable output format: {fmt!r}")

    if fmt == OutputFormat.JSON:
        return serialize_config_json(
            meta=meta,
            config=config,
            resolved_toml=resolved_toml,
            show_config_layers=show_config_layers,
        )

    if fmt == OutputFormat.NDJSON:
        return serialize_config_ndjson(
            meta=meta,
            config=config,
            resolved_toml=resolved_toml,
            show_config_layers=show_config_layers,
        )

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

serialize_config_json

serialize_config_json(
    *, meta, config, resolved_toml, show_config_layers=False
)

Serialize the effective FrozenConfig snapshot as a JSON envelope.

Shapes

• default:
• with provenance: { "meta": , "config_provenance": , "config": , }

Parameters:

Name	Type	Description	Default
meta	MetaPayload	Machine-output metadata (tool/version).	required
config	FrozenConfig	Immutable runtime configuration to serialize.	required
resolved_toml	ResolvedTopmarkTomlSources	Resolved TOML sources for optional provenance export.	required
show_config_layers	bool	If True, include layered TOML provenance in the JSON envelope.	False

Returns:

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

Raises:

Type	Description
ValueError	If show_config_layers is True but TOML provenance cannot be serialized.

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

def serialize_config_json(
    *,
    meta: MetaPayload,
    config: FrozenConfig,
    resolved_toml: ResolvedTopmarkTomlSources,
    show_config_layers: bool = False,
) -> str:
    """Serialize the effective `FrozenConfig` snapshot as a JSON envelope.

    Shapes:
        - default:
            {"meta": <MetaPayload>, "config": <ConfigPayload>}
        - with provenance:
            {
                "meta": <MetaPayload>,
                "config_provenance": <TomlProvenancePayload>,
                "config": <ConfigPayload>,
            }

    Args:
        meta: Machine-output metadata (tool/version).
        config: Immutable runtime configuration to serialize.
        resolved_toml: Resolved TOML sources for optional provenance export.
        show_config_layers: If `True`, include layered TOML provenance in the JSON envelope.

    Returns:
        Pretty-printed JSON string (no trailing newline).

    Raises:
        ValueError: If `show_config_layers` is `True` but TOML provenance cannot be serialized.
    """  # noqa: DOC502 - documents propagated exceptions from `_build_required_toml_provenance_payload()``
    cfg_provenance_payload: TomlProvenancePayload | None = (
        _build_required_toml_provenance_payload(resolved_toml) if show_config_layers else None
    )

    envelope: dict[str, object] = build_config_json_envelope(
        config=config,
        resolved_toml=resolved_toml,
        meta=meta,
        cfg_provenance_payload=cfg_provenance_payload,
    )
    return serialize_json_object(envelope)

serialize_config_ndjson

serialize_config_ndjson(
    *, meta, config, resolved_toml, show_config_layers=False
)

Serialize the effective FrozenConfig snapshot as NDJSON.

Record sequence

• default: 1) {"kind": "config", "meta": , "config": }
• with provenance: 1) { "kind": "config_provenance", "meta": , "config_provenance": , } 2) {"kind": "config", "meta": , "config": }

Parameters:

Name	Type	Description	Default
meta	MetaPayload	Machine-output metadata (tool/version).	required
config	FrozenConfig	Immutable runtime configuration to serialize.	required
resolved_toml	ResolvedTopmarkTomlSources	Resolved TOML sources for optional provenance export.	required
show_config_layers	bool	If True, include layered TOML provenance in the NDJSON stream.	False

Returns:

Type	Description
Iterator[str]	Iterator of NDJSON lines (no trailing newline).

Raises:

Type	Description
ValueError	If show_config_layers is True but TOML provenance cannot be serialized.

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

def serialize_config_ndjson(
    *,
    meta: MetaPayload,
    config: FrozenConfig,
    resolved_toml: ResolvedTopmarkTomlSources,
    show_config_layers: bool = False,
) -> Iterator[str]:
    """Serialize the effective `FrozenConfig` snapshot as NDJSON.

    Record sequence:
        - default:
            1) {"kind": "config", "meta": <MetaPayload>, "config": <ConfigPayload>}
        - with provenance:
            1) {
                   "kind": "config_provenance",
                   "meta": <MetaPayload>,
                   "config_provenance": <TomlProvenancePayload>,
               }
            2) {"kind": "config", "meta": <MetaPayload>, "config": <ConfigPayload>}

    Args:
        meta: Machine-output metadata (tool/version).
        config: Immutable runtime configuration to serialize.
        resolved_toml: Resolved TOML sources for optional provenance export.
        show_config_layers: If `True`, include layered TOML provenance in the NDJSON stream.

    Returns:
        Iterator of NDJSON lines (no trailing newline).

    Raises:
        ValueError: If `show_config_layers` is `True` but TOML provenance cannot be serialized.
    """  # noqa: DOC502 - documents propagated exceptions from `_build_required_toml_provenance_payload()``
    cfg_provenance_payload: TomlProvenancePayload | None = (
        _build_required_toml_provenance_payload(resolved_toml) if show_config_layers else None
    )

    iter_records: Iterator[dict[str, object]] = iter_config_ndjson_records(
        config=config,
        resolved_toml=resolved_toml,
        meta=meta,
        cfg_provenance_payload=cfg_provenance_payload,
    )
    return iter_ndjson_strings(iter_records)

serialize_config_diagnostics

serialize_config_diagnostics(*, meta, config, fmt)

Serialize FrozenConfig diagnostics in a machine-readable format.

Shapes

• JSON: one envelope object: {"meta": ..., "config_diagnostics": ...}
• NDJSON: counts-only record + streamed diagnostic records.

Parameters:

Name	Type	Description	Default
meta	MetaPayload	Machine-output metadata (tool/version).	required
config	FrozenConfig	Immutable runtime configuration providing diagnostics.	required
fmt	OutputFormat	Target machine-readable format (JSON or NDJSON).	required

Returns:

Type	Description
str | Iterator[str]	Rendered JSON string or iterable of NDJSON lines (no trailing newline).

Raises:

Type	Description
ValueError	if fmt is not a supported machine-readable format.

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

def serialize_config_diagnostics(
    *,
    meta: MetaPayload,
    config: FrozenConfig,
    fmt: OutputFormat,
) -> str | Iterator[str]:
    """Serialize `FrozenConfig` diagnostics in a machine-readable format.

    Shapes:
      - JSON: one envelope object: {"meta": ..., "config_diagnostics": ...}
      - NDJSON: counts-only record + streamed diagnostic records.

    Args:
        meta: Machine-output metadata (tool/version).
        config: Immutable runtime configuration providing diagnostics.
        fmt: Target machine-readable format (JSON or NDJSON).

    Returns:
        Rendered JSON string or iterable of NDJSON lines (no trailing newline).

    Raises:
        ValueError: if `fmt` is not a supported machine-readable format.
    """
    if not is_machine_format(fmt):
        raise ValueError(f"Unsupported machine-readable output format: {fmt!r}")

    if fmt == OutputFormat.JSON:
        return serialize_config_diagnostics_json(
            meta=meta,
            config=config,
        )

    if fmt == OutputFormat.NDJSON:
        return serialize_config_diagnostics_ndjson(
            meta=meta,
            config=config,
        )

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

serialize_config_diagnostics_json

serialize_config_diagnostics_json(*, meta, config)

Serialize FrozenConfig diagnostics as a JSON envelope.

Shape

{"meta": , "config_diagnostics": }

Parameters:

Name	Type	Description	Default
meta	MetaPayload	Machine-output metadata (tool/version).	required
config	FrozenConfig	Immutable runtime configuration providing diagnostics.	required

Returns:

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

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

def serialize_config_diagnostics_json(
    *,
    meta: MetaPayload,
    config: FrozenConfig,
) -> str:
    """Serialize `FrozenConfig` diagnostics as a JSON envelope.

    Shape:
        {"meta": <MetaPayload>, "config_diagnostics": <ConfigDiagnosticsPayload>}

    Args:
        meta: Machine-output metadata (tool/version).
        config: Immutable runtime configuration providing diagnostics.

    Returns:
        Pretty-printed JSON string (no trailing newline).
    """
    envelope: dict[str, object] = build_config_diagnostics_json_envelope(
        config=config,
        meta=meta,
    )
    return serialize_json_object(envelope)

serialize_config_diagnostics_ndjson

serialize_config_diagnostics_ndjson(*, meta, config)

Serialize FrozenConfig diagnostics as NDJSON.

Record sequence

1) config_diagnostics (counts-only) 2+) diagnostic (domain="config") one per diagnostic

Parameters:

Name	Type	Description	Default
meta	MetaPayload	Machine-output metadata (tool/version).	required
config	FrozenConfig	Immutable runtime configuration providing diagnostics.	required

Returns:

Type	Description
Iterator[str]	Iterator of NDJSON lines (no trailing newline).

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

def serialize_config_diagnostics_ndjson(
    *,
    meta: MetaPayload,
    config: FrozenConfig,
) -> Iterator[str]:
    """Serialize `FrozenConfig` diagnostics as NDJSON.

    Record sequence:
      1) config_diagnostics (counts-only)
      2+) diagnostic (domain="config") one per diagnostic

    Args:
        meta: Machine-output metadata (tool/version).
        config: Immutable runtime configuration providing diagnostics.

    Returns:
        Iterator of NDJSON lines (no trailing newline).
    """
    iter_records: Iterator[dict[str, object]] = iter_config_diagnostics_ndjson_records(
        config=config,
        meta=meta,
    )
    return iter_ndjson_strings(iter_records)

serialize_config_check

serialize_config_check(
    *, meta, config, resolved_toml, strict, ok, fmt
)

Serialize topmark config check results in a machine-readable format.

JSON

• One envelope: meta, config, config_diagnostics (full), summary.

NDJSON record sequence

1) config 2) config_diagnostics (counts-only) 3) summary (command="config", subcommand="check") 4+) diagnostic (domain="config") one per diagnostic

Parameters:

Name	Type	Description	Default
meta	MetaPayload	Machine-output metadata (tool/version).	required
config	FrozenConfig	Immutable runtime configuration providing diagnostics.	required
resolved_toml	ResolvedTopmarkTomlSources	Resolved TOML sources used to include TOML-authored writer options in the config payload.	required
strict	bool	If True, warnings are treated as failures.	required
ok	bool	Whether the config passed validation	required
fmt	OutputFormat	Target machine-readable format (JSON or NDJSON).	required

Returns:

Type	Description
str | Iterator[str]	Rendered JSON string or iterator of NDJSON lines (no trailing newline).

Raises:

Type	Description
ValueError	If fmt is not a supported machine-readable format.

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

def serialize_config_check(
    *,
    meta: MetaPayload,
    config: FrozenConfig,
    resolved_toml: ResolvedTopmarkTomlSources,
    strict: bool,
    ok: bool,
    fmt: OutputFormat,
) -> str | Iterator[str]:
    """Serialize `topmark config check` results in a machine-readable format.

    JSON:
      - One envelope: meta, config, config_diagnostics (full), summary.

    NDJSON record sequence:
      1) config
      2) config_diagnostics (counts-only)
      3) summary (command="config", subcommand="check")
      4+) diagnostic (domain="config") one per diagnostic

    Args:
        meta: Machine-output metadata (tool/version).
        config: Immutable runtime configuration providing diagnostics.
        resolved_toml: Resolved TOML sources used to include TOML-authored
            writer options in the config payload.
        strict: If True, warnings are treated as failures.
        ok: Whether the config passed validation
        fmt: Target machine-readable format (JSON or NDJSON).

    Returns:
        Rendered JSON string or iterator of NDJSON lines (no trailing newline).

    Raises:
        ValueError: If `fmt` is not a supported machine-readable format.
    """
    if not is_machine_format(fmt):
        raise ValueError(f"Unsupported machine-readable output format: {fmt!r}")

    if fmt == OutputFormat.JSON:
        return serialize_config_check_json(
            meta=meta,
            config=config,
            resolved_toml=resolved_toml,
            strict=strict,
            ok=ok,
        )

    if fmt == OutputFormat.NDJSON:
        return serialize_config_check_ndjson(
            meta=meta,
            config=config,
            resolved_toml=resolved_toml,
            strict=strict,
            ok=ok,
        )

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

serialize_config_check_json

serialize_config_check_json(
    *, meta, config, resolved_toml, strict, ok
)

Serialize topmark config check results as a JSON envelope.

Shape

{"meta": ..., "config": ..., "config_diagnostics": ..., "summary": ...}

Parameters:

Name	Type	Description	Default
meta	MetaPayload	Machine-output metadata (tool/version).	required
config	FrozenConfig	Immutable runtime configuration providing diagnostics.	required
resolved_toml	ResolvedTopmarkTomlSources	Resolved TOML sources used to include TOML-authored writer options in the config payload.	required
strict	bool	If True, warnings are treated as failures.	required
ok	bool	Whether the config passed validation	required

Returns:

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

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

def serialize_config_check_json(
    *,
    meta: MetaPayload,
    config: FrozenConfig,
    resolved_toml: ResolvedTopmarkTomlSources,
    strict: bool,
    ok: bool,
) -> str:
    """Serialize `topmark config check` results as a JSON envelope.

    Shape:
        {"meta": ..., "config": ..., "config_diagnostics": ..., "summary": ...}

    Args:
        meta: Machine-output metadata (tool/version).
        config: Immutable runtime configuration providing diagnostics.
        resolved_toml: Resolved TOML sources used to include TOML-authored
            writer options in the config payload.
        strict: If True, warnings are treated as failures.
        ok: Whether the config passed validation

    Returns:
        Pretty-printed JSON string (no trailing newline).
    """
    envelope: dict[str, object] = build_config_check_json_envelope(
        meta=meta,
        config=config,
        resolved_toml=resolved_toml,
        strict=strict,
        ok=ok,
    )
    return serialize_json_object(envelope)

serialize_config_check_ndjson

serialize_config_check_ndjson(
    *, meta, config, resolved_toml, strict, ok
)

Serialize topmark config check results as NDJSON.

Record sequence

1) config 2) config_diagnostics (counts-only) 3) summary 4+) diagnostic (domain="config") one per diagnostic

Parameters:

Name	Type	Description	Default
meta	MetaPayload	Machine-output metadata (tool/version).	required
config	FrozenConfig	Immutable runtime configuration providing diagnostics.	required
resolved_toml	ResolvedTopmarkTomlSources	Resolved TOML sources used to include TOML-authored writer options in the config payload.	required
strict	bool	If True, warnings are treated as failures.	required
ok	bool	Whether the config passed validation	required

Returns:

Type	Description
Iterator[str]	Iterator of NDJSON lines (no trailing newline).

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

def serialize_config_check_ndjson(
    *,
    meta: MetaPayload,
    config: FrozenConfig,
    resolved_toml: ResolvedTopmarkTomlSources,
    strict: bool,
    ok: bool,
) -> Iterator[str]:
    """Serialize `topmark config check` results as NDJSON.

    Record sequence:
      1) config
      2) config_diagnostics (counts-only)
      3) summary
      4+) diagnostic (domain="config") one per diagnostic

    Args:
        meta: Machine-output metadata (tool/version).
        config: Immutable runtime configuration providing diagnostics.
        resolved_toml: Resolved TOML sources used to include TOML-authored
            writer options in the config payload.
        strict: If True, warnings are treated as failures.
        ok: Whether the config passed validation

    Returns:
        Iterator of NDJSON lines (no trailing newline).
    """
    iter_records: Iterator[dict[str, object]] = iter_config_check_ndjson_records(
        meta=meta,
        config=config,
        resolved_toml=resolved_toml,
        strict=strict,
        ok=ok,
    )
    return iter_ndjson_strings(iter_records)