Skip to content

topmark.version.machine.payloads

topmark / version / machine / payloads

Payload builders for machine-readable output.

"Payload" here means: the domain object that will be inserted into a JSON envelope (top-level JSON output) or into an NDJSON record (streaming output).

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

It provides small, stable "global" payloads used across multiple commands:

  • build_version_payload(): Version information suitable for JSON envelopes and NDJSON records, including the effective version format when SemVer conversion is requested.

If a payload needs keys/kinds/domains, import those from topmark.core.machine.schemas (not from a serializer/emitter).

VersionPayloadResult dataclass 

VersionPayloadResult(*, payload, err=None)

Payload build result for machine-readable version output.

Attributes:

Name Type Description
payload dict[str, object]

Mapping with version information for machine envelopes.
err Exception | None

Conversion exception when SemVer was requested and failed; otherwise None.

build_version_payload 

build_version_payload(*, semver)

Build the version payload for machine-readable output.

This helper never raises on SemVer conversion failure. If SemVer conversion was requested and fails, it falls back to the original PEP 440 version string and returns the conversion error alongside the payload.

Parameters:

Name Type Description Default
semver bool

Whether to attempt SemVer conversion.

 required

Returns:

Type Description
VersionPayloadResult

A typed result containing the payload and any SemVer conversion error.
Source code in src/topmark/version/machine/payloads.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
def build_version_payload(
    *,
    semver: bool,
) -> VersionPayloadResult:
    """Build the version payload for machine-readable output.

    This helper never raises on SemVer conversion failure. If SemVer conversion
    was requested and fails, it falls back to the original PEP 440 version
    string and returns the conversion error alongside the payload.

    Args:
        semver: Whether to attempt SemVer conversion.

    Returns:
        A typed result containing the payload and any SemVer conversion error.
    """
    version_info: VersionInfo = compute_version_info(semver=semver)

    return VersionPayloadResult(
        payload={
            VersionKey.VERSION.value: version_info.version_text,
            VersionKey.VERSION_FORMAT.value: version_info.version_format,
        },
        err=version_info.err,
    )