Skip to content

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) -> None

Fields and properties declared here; inherited members belong to the bases above.

compatible

compatible: bool

dtype_issues

dtype_issues: list[str] = field(default_factory=list)

duration

duration: float = 0.0

error

error: Exception | None = None

error_type

error_type: str | None = None

has_issues

Read-only property.

has_issues: bool

samples

samples: Any | None = None

schema_issues

schema_issues: list[str] = field(default_factory=list)

table

table: TableRef | str

would_insert

would_insert: int = 0

would_retire

would_retire: int = 0

would_unchanged

would_unchanged: int = 0

would_update

would_update: int = 0

describe

def describe() -> str

ReadResult

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) -> None

Fields and properties declared here; inherited members belong to the bases above.

data

data: Any | None = None

duration

duration: float = 0.0

error

error: Exception | None = None

error_type

error_type: str | None = None

ok

ok: bool

output

output: str = 'polars'

rows

rows: int = 0

failure

@classmethod
def failure(error: Exception, *, duration: float = 0.0) -> ReadResult

success

@classmethod
def success(data: Any, rows: int, *, output: str, duration: float = 0.0) -> ReadResult

ReconcileReport

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) -> None

Fields and properties declared here; inherited members belong to the bases above.

policy

policy: str = 'archive'

retired

retired: int = 0

retired_keys

retired_keys: Any | None = None

scope

scope: dict[str, Any] = field(default_factory=dict)

stale

stale: int = 0

stale_keys

stale_keys: Any | None = None

describe

def describe() -> str

WriteResult

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) -> None

Fields and properties declared here; inherited members belong to the bases above.

batch_id

batch_id: str | None = None

deleted

deleted: int = 0

duration

duration: float = 0.0

error

error: Exception | None = None

error_type

error_type: str | None = None

failed

failed: int = 0

failed_rows

failed_rows: Any | None = None

healed

healed: dict[str, int] = field(default_factory=dict)

inserted

inserted: int = 0

ok

ok: bool

op

op: OpKind | str

table

table: TableRef | DatasetRef | str

total_seen

Read-only property.

total_seen: int

unchanged

unchanged: int = 0

updated

updated: int = 0

written

Read-only property.

written: int

describe

def describe() -> str

failure

@classmethod
def failure(op: OpKind | str, table: TableRef | DatasetRef | str, error: Exception, **counts: Any) -> WriteResult

success

@classmethod
def success(op: OpKind | str, table: TableRef | DatasetRef | str, **counts: Any) -> WriteResult