common_db.schemas.results
results.py — the honesty layer: every op returns a typed report.
Dataclasses (the system reporting on itself — no boundary validation). Attributes carry POINTERS to produced things (frames of failed rows, retired keys), never copies. Failures RETURN results; the pipeline never raises past its op boundary. No secrets at any tier.
Classes
AssessmentReport
The preflight’s answer — what WOULD happen, target untouched.
compatible gates writes when asked; the issue lists carry per-column
findings; the would_* counts are the dry-run diff; samples points at
example problem rows. A broken assess (missing table, bad input) comes
back as a failure REPORT — error/error_type carried, never raised.
__init__
def __init__(compatible: bool, table: TableRef | str, schema_issues: list[str] = list(), dtype_issues: list[str] = list(), would_insert: int = 0, would_update: int = 0, would_unchanged: int = 0, would_retire: int = 0, samples: Any | None = None, duration: float = 0.0, error: Exception | None = None, error_type: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
compatible
compatible: booldtype_issues
dtype_issues: list[str] = field(default_factory=list)duration
duration: float = 0.0error
error: Exception | None = Noneerror_type
error_type: str | None = Nonehas_issues
Read-only property.
has_issues: boolsamples
samples: Any | None = Noneschema_issues
schema_issues: list[str] = field(default_factory=list)table
table: TableRef | strwould_insert
would_insert: int = 0would_retire
would_retire: int = 0would_unchanged
would_unchanged: int = 0would_update
would_update: int = 0describe
def describe() -> strReadResult
One read’s report — the data rides as a pointer, shaped per ReadConfig.
__init__
def __init__(ok: bool, data: Any | None = None, rows: int = 0, output: str = 'polars', duration: float = 0.0, error: Exception | None = None, error_type: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
data
data: Any | None = Noneduration
duration: float = 0.0error
error: Exception | None = Noneerror_type
error_type: str | None = Noneok
ok: booloutput
output: str = 'polars'rows
rows: int = 0failure
@classmethoddef failure(error: Exception, *, duration: float = 0.0) -> ReadResultsuccess
@classmethoddef success(data: Any, rows: int, *, output: str, duration: float = 0.0) -> ReadResultReconcileReport
Bases: WriteResult
A reconcile’s report — the write counts PLUS the stale story.
stale is the exact number discovered before the policy acts and
stale_keys points at the first bounded set of their key rows. Those
two fields are populated even for policy="report", where the target
is deliberately untouched. retired/retired_keys describe rows
actually archived (or deleted, for the compatibility count).
__init__
def __init__(ok: bool, op: OpKind | str, table: TableRef | DatasetRef | str, inserted: int = 0, updated: int = 0, unchanged: int = 0, deleted: int = 0, failed: int = 0, failed_rows: Any | None = None, healed: dict[str, int] = dict(), duration: float = 0.0, batch_id: str | None = None, error: Exception | None = None, error_type: str | None = None, scope: dict[str, Any] = dict(), policy: str = 'archive', stale: int = 0, stale_keys: Any | None = None, retired: int = 0, retired_keys: Any | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
policy
policy: str = 'archive'retired
retired: int = 0retired_keys
retired_keys: Any | None = Nonescope
scope: dict[str, Any] = field(default_factory=dict)stale
stale: int = 0stale_keys
stale_keys: Any | None = Nonedescribe
def describe() -> strWriteResult
One write op’s report — counts tell the whole story.
healed maps heal-kind -> count (dtype coercions, null normalizations,
dup collapses) so nothing self-healed is ever silent. failed_rows is
the bad rows THEMSELVES (a frame with a reason column), never a lost
exception.
__init__
def __init__(ok: bool, op: OpKind | str, table: TableRef | DatasetRef | str, inserted: int = 0, updated: int = 0, unchanged: int = 0, deleted: int = 0, failed: int = 0, failed_rows: Any | None = None, healed: dict[str, int] = dict(), duration: float = 0.0, batch_id: str | None = None, error: Exception | None = None, error_type: str | None = None) -> NoneFields and properties declared here; inherited members belong to the bases above.
batch_id
batch_id: str | None = Nonedeleted
deleted: int = 0duration
duration: float = 0.0error
error: Exception | None = Noneerror_type
error_type: str | None = Nonefailed
failed: int = 0failed_rows
failed_rows: Any | None = Nonehealed
healed: dict[str, int] = field(default_factory=dict)inserted
inserted: int = 0ok
ok: boolop
op: OpKind | strtable
table: TableRef | DatasetRef | strtotal_seen
Read-only property.
total_seen: intunchanged
unchanged: int = 0updated
updated: int = 0written
Read-only property.
written: intdescribe
def describe() -> strfailure
@classmethoddef failure(op: OpKind | str, table: TableRef | DatasetRef | str, error: Exception, **counts: Any) -> WriteResultsuccess
@classmethoddef success(op: OpKind | str, table: TableRef | DatasetRef | str, **counts: Any) -> WriteResult