topmark.version.machine.serializers¶

topmark / version / 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.version.machine.payloads builds payload objects (domain data, no envelope). - topmark.version.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_version ¶

serialize_version(*, meta, fmt, semver)

Serialize topmark version output in machine-readable JSON/NDJSON form.

JSON envelope

{"meta": {...}, "version_info": {"version": "...", "version_format": "..."}}

NDJSON stream

1) {"kind": "version", "meta": {...}, "version": {...}} 2) Optional diagnostic record if SemVer conversion failed and a fallback occurred.

Parameters:

Name	Type	Description	Default
`meta`	`MetaPayload`	Metadata payload (tool/version).	required
`fmt`	`OutputFormat`	Output format. Only JSON and NDJSON are supported here.	required
`semver`	`bool`	Whether to attempt SemVer conversion of the tool version.	required

Returns:

Type	Description
`str \| Iterator[str]`	Serialized JSON string or or NDJSON string iterable.

Raises:

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

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

def serialize_version(
    *,
    meta: MetaPayload,
    fmt: OutputFormat,
    semver: bool,
) -> str | Iterator[str]:
    """Serialize `topmark version` output in machine-readable JSON/NDJSON form.

    JSON envelope:
        `{"meta": {...}, "version_info": {"version": "...", "version_format": "..."}}`

    NDJSON stream:
        1) `{"kind": "version", "meta": {...}, "version": {...}}`
        2) Optional diagnostic record if SemVer conversion failed and a fallback occurred.

    Args:
        meta: Metadata payload (tool/version).
        fmt: Output format. Only JSON and NDJSON are supported here.
        semver: Whether to attempt SemVer conversion of the tool version.

    Returns:
        Serialized JSON string or or NDJSON string iterable.

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

    if fmt == OutputFormat.NDJSON:
        return serialize_version_ndjson(meta=meta, semver=semver)

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

serialize_version_json ¶

serialize_version_json(*, meta, semver)

Serialize topmark version output in machine-readable JSON/NDJSON form.

JSON envelope

{"meta": {...}, "version_info": {"version": "...", "version_format": "..."}}

Parameters:

Name	Type	Description	Default
`meta`	`MetaPayload`	Metadata payload (tool/version).	required
`semver`	`bool`	Whether to attempt SemVer conversion of the tool version.	required

Returns:

Type	Description
`str`	Serialized NDJSON string.

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

def serialize_version_json(
    *,
    meta: MetaPayload,
    semver: bool,
) -> str:
    """Serialize `topmark version` output in machine-readable JSON/NDJSON form.

    JSON envelope:
        `{"meta": {...}, "version_info": {"version": "...", "version_format": "..."}}`

    Args:
        meta: Metadata payload (tool/version).
        semver: Whether to attempt SemVer conversion of the tool version.

    Returns:
        Serialized NDJSON string.
    """
    result: VersionPayloadResult = build_version_payload(semver=semver)
    return serialize_json_envelope(
        meta=meta,
        **{
            VersionKey.VERSION_INFO.value: result.payload,
        },
    )

serialize_version_ndjson ¶

serialize_version_ndjson(*, meta, semver)

Serialize topmark version output in machine-readable JSON/NDJSON form.

NDJSON stream

1) {"kind": "version", "meta": {...}, "version": {...}} 2) Optional diagnostic record if SemVer conversion failed and a fallback occurred.

Parameters:

Name	Type	Description	Default
`meta`	`MetaPayload`	Metadata payload (tool/version).	required
`semver`	`bool`	Whether to attempt SemVer conversion of the tool version.	required

Yields:

Type	Description
`str`	Serialized JSON string.

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

def serialize_version_ndjson(
    *,
    meta: MetaPayload,
    semver: bool,
) -> Iterator[str]:
    """Serialize `topmark version` output in machine-readable JSON/NDJSON form.

    NDJSON stream:
        1) `{"kind": "version", "meta": {...}, "version": {...}}`
        2) Optional diagnostic record if SemVer conversion failed and a fallback occurred.

    Args:
        meta: Metadata payload (tool/version).
        semver: Whether to attempt SemVer conversion of the tool version.

    Yields:
        Serialized JSON string.
    """
    records: Iterator[dict[str, object]] = iter_version_ndjson_records(meta=meta, semver=semver)
    yield serialize_ndjson(records)