topmark.diagnostic.machine.schemas

topmark / diagnostic / machine / schemas

Typed payload schemas for machine-readable diagnostics.

This module defines small, JSON-friendly dataclasses used by multiple TopMark domains to represent diagnostics in machine-readable output. These classes belong to the payload layer (schemas → payloads → shapes → serializers):

• MachineDiagnosticEntry represents a single diagnostic (level + message).
• MachineDiagnosticCounts represents aggregated per-level counts.

The NDJSON shape layer emits one record per internal Diagnostic. For JSON envelopes, domains typically prebuild lists of MachineDiagnosticEntry and a MachineDiagnosticCounts instance.

DiagnosticKey

Bases: str, Enum

Stable keys used by diagnostic machine-readable output payloads.

These keys belong to the shared diagnostic domain and are reused by other machine-readable output packages when embedding lists of diagnostics or aggregate diagnostic counts.

Attributes:

Name	Type	Description
DIAGNOSTIC_COUNTS		Container key for aggregate per-level counts.
DIAGNOSTICS		Container key for a list of diagnostic entries.
LEVEL		Severity level field for a single diagnostic entry.
MESSAGE		Human-readable diagnostic text for a single entry.
INFO		Count key for info-level diagnostics.
WARNING		Count key for warning-level diagnostics.
ERROR		Count key for error-level diagnostics.

DiagnosticKind

Bases: str, Enum

Stable NDJSON record kinds owned by the diagnostic domain.

Attributes:

Name	Type	Description
DIAGNOSTIC		One diagnostic record in an NDJSON stream.

MachineDiagnosticEntry dataclass

MachineDiagnosticEntry(*, level, message)

Machine-readable diagnostic entry.

Attributes:

Name	Type	Description
level	str	Severity level string (e.g. "info", "warning", "error").
message	str	Human-readable diagnostic message.

from_diagnostic classmethod

from_diagnostic(d)

Create a machine-readable entry from an internal diagnostic.

Parameters:

Name	Type	Description	Default
d	Diagnostic	Internal diagnostic instance.	required

Returns:

Type	Description
MachineDiagnosticEntry	A MachineDiagnosticEntry containing the severity level and message.

Source code in src/topmark/diagnostic/machine/schemas.py

@classmethod
def from_diagnostic(cls, d: Diagnostic) -> MachineDiagnosticEntry:
    """Create a machine-readable entry from an internal diagnostic.

    Args:
        d: Internal diagnostic instance.

    Returns:
        A `MachineDiagnosticEntry` containing the severity level and message.
    """
    return cls(level=d.level.value, message=d.message)

to_dict

to_dict()

Return a JSON-friendly dict of this diagnostic entry.

Source code in src/topmark/diagnostic/machine/schemas.py

def to_dict(self) -> dict[str, str]:
    """Return a JSON-friendly dict of this diagnostic entry."""
    return {
        DiagnosticKey.LEVEL.value: self.level,
        DiagnosticKey.MESSAGE.value: self.message,
    }

MachineDiagnosticCounts dataclass

MachineDiagnosticCounts(*, info, warning, error)

Aggregated per-level counts for machine-readable output.

Attributes:

Name	Type	Description
info	int	Count of info-level diagnostics.
warning	int	Count of warning-level diagnostics.
error	int	Count of error-level diagnostics.

from_iterable classmethod

from_iterable(diagnostics)

Compute per-level counts from an iterable of internal diagnostics.

Parameters:

Name	Type	Description	Default
diagnostics	Iterable[Diagnostic]	Internal diagnostics to aggregate.	required

Returns:

Type	Description
MachineDiagnosticCounts	A MachineDiagnosticCounts instance with per-level totals.

Source code in src/topmark/diagnostic/machine/schemas.py

@classmethod
def from_iterable(cls, diagnostics: Iterable[Diagnostic]) -> MachineDiagnosticCounts:
    """Compute per-level counts from an iterable of internal diagnostics.

    Args:
        diagnostics: Internal diagnostics to aggregate.

    Returns:
        A `MachineDiagnosticCounts` instance with per-level totals.
    """
    stats: DiagnosticStats = compute_diagnostic_stats(diagnostics)
    return cls(info=stats.n_info, warning=stats.n_warning, error=stats.n_error)

to_dict

to_dict()

Return a JSON-friendly dict of the per-level counts.

Source code in src/topmark/diagnostic/machine/schemas.py

def to_dict(self) -> dict[str, int]:
    """Return a JSON-friendly dict of the per-level counts."""
    return {
        DiagnosticKey.INFO.value: self.info,
        DiagnosticKey.WARNING.value: self.warning,
        DiagnosticKey.ERROR.value: self.error,
    }