topmark.version.machine.envelopes¶

Envelope and record shaping utilities for machine-readable output.

This module defines shape builders for TopMark machine-readable output: - JSON envelopes (single JSON objects) containing "meta" plus named payloads. - NDJSON record objects containing "kind", "meta", and a payload container.

This module is intentionally: - Console-free (no printing) - Click-free - serialization-free (no json.dumps)

Where things live: - topmark.core.machine.payloads: build payload objects (domain data). - topmark.core.machine.envelopes: build envelopes/records around payloads. - topmark.core.machine.serializers: serialize envelopes/records to strings.

NDJSON convention (Pattern A): - Every record includes "kind" and "meta". - Prefer omitting container_key so the container key equals kind.

build_version_ndjson_record ¶

build_version_ndjson_record(*, meta, payload)

Build an NDJSON version record for the version command.

Parameters:

Name	Type	Description	Default
`meta`	`MetaPayload`	Metadata payload (tool/version).	required
`payload`	`Mapping[str, object]`	Version payload with version info.	required

Returns:

Type	Description
`dict[str, object]`	Shaped NDJSON record mapping:
`dict[str, object]`	`{"kind": "version", "meta": {...}, "version": {...}}`

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

def build_version_ndjson_record(
    *,
    meta: MetaPayload,
    payload: Mapping[str, object],
) -> dict[str, object]:
    """Build an NDJSON version record for the `version` command.

    Args:
        meta: Metadata payload (tool/version).
        payload: Version payload with version info.

    Returns:
        Shaped NDJSON record mapping:
        `{"kind": "version", "meta": {...}, "version": {...}}`
    """
    return build_ndjson_record(
        kind=VersionKind.VERSION,
        meta=meta,
        payload=payload,
        # Prefer omitting container_key so it defaults to kind ("version").
    )

build_version_diagnostic_ndjson_record ¶

build_version_diagnostic_ndjson_record(
    *, meta, message, level=DiagnosticLevel.WARNING
)

Build an NDJSON diagnostic record for the version command.

Emitted when SemVer conversion was requested but failed and TopMark fell back to the original PEP 440 version string.

Parameters:

Name	Type	Description	Default
`meta`	`MetaPayload`	Metadata payload (tool/version).	required
`message`	`str`	Human-readable diagnostic message.	required
`level`	`DiagnosticLevel`	Diagnostic severity (defaults to WARNING).	`WARNING`

Returns:

Type	Description
`dict[str, object]`	Shaped NDJSON record:
`dict[str, object]`	{"kind": "diagnostic", "meta": {...}, "diagnostic": {...}}

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

def build_version_diagnostic_ndjson_record(
    *,
    meta: MetaPayload,
    message: str,
    level: DiagnosticLevel = DiagnosticLevel.WARNING,
) -> dict[str, object]:
    """Build an NDJSON diagnostic record for the `version` command.

    Emitted when SemVer conversion was requested but failed and TopMark fell back
    to the original PEP 440 version string.

    Args:
        meta: Metadata payload (tool/version).
        message: Human-readable diagnostic message.
        level: Diagnostic severity (defaults to WARNING).

    Returns:
        Shaped NDJSON record:
        {"kind": "diagnostic", "meta": {...}, "diagnostic": {...}}
    """
    return build_ndjson_record(
        kind=DiagnosticKind.DIAGNOSTIC,
        meta=meta,
        payload={
            MachineKey.DOMAIN.value: MachineDomain.VERSION,
            DiagnosticKey.LEVEL.value: level.value,
            DiagnosticKey.MESSAGE.value: message,
        },
    )

iter_version_ndjson_records ¶

iter_version_ndjson_records(*, meta, semver)

Build NDJSON records for topmark version (Pattern A).

Contract: every record includes kind and meta.

Records

1) kind="version" with payload under key "version" 2) (optional) kind="diagnostic" if SemVer conversion was requested and failed

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
`dict[str, object]`	Shaped NDJSON record mappings.

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

def iter_version_ndjson_records(
    *,
    meta: MetaPayload,
    semver: bool,
) -> Iterator[dict[str, object]]:
    """Build NDJSON records for `topmark version` (Pattern A).

    Contract: every record includes `kind` and `meta`.

    Records:
      1) kind="version" with payload under key "version"
      2) (optional) kind="diagnostic" if SemVer conversion was requested and failed

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

    Yields:
        Shaped NDJSON record mappings.
    """
    result: VersionPayloadResult = build_version_payload(semver=semver)

    yield build_version_ndjson_record(
        meta=meta,
        payload=result.payload,
    )
    if result.err is not None:
        yield build_version_diagnostic_ndjson_record(
            meta=meta,
            message=str(result.err),
        )