Skip to content

common_db.contracts.ops

ops.py — the operation vocabulary: what kinds of DB ops exist and the closed policy sets that parameterize them.

Classification primitives (fixed for an op’s life), never mechanics — the HOW lives in the client domain; these are the nouns every layer speaks.

Classes

CoercePolicy

Bases: StrEnum

The self-heal posture when incoming dtypes drift from the model.

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

COERCE

COERCE = 'coerce'

HEAL

HEAL = 'heal'

STRICT

STRICT = 'strict'

OpKind

Bases: StrEnum

The op axis — every verb the suite performs is one of these.

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

APPEND

APPEND = 'append'

ASSESS

ASSESS = 'assess'

COMBINE

COMBINE = 'combine'

EVOLVE

EVOLVE = 'evolve'

KEY_UPGRADE

KEY_UPGRADE = 'key_upgrade'

READ

READ = 'read'

RECONCILE

RECONCILE = 'reconcile'

REPLACE

REPLACE = 'replace'

STASH

STASH = 'stash'

UPSERT

UPSERT = 'upsert'

UPSERT_APPEND

UPSERT_APPEND = 'upsert_append'

OutputKind

Bases: StrEnum

Read-side output shape — total flexibility, one closed set.

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

ARROW

ARROW = 'arrow'

DICTS

DICTS = 'dicts'

PANDAS

PANDAS = 'pandas'

POLARS

POLARS = 'polars'

ROWS

ROWS = 'rows'

ReconcilePolicy

Bases: StrEnum

What happens to STALE rows (present in the target’s scope, absent from the new data). Sam’s ruling: never destructive by default.

(FLAG was removed 2026-08-16 — unearned: no op ever wrote a flag column, and vocabulary must be earned by a real mechanic.)

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

ARCHIVE

ARCHIVE = 'archive'

DELETE

DELETE = 'delete'

REPORT

REPORT = 'report'

StorageKind

Bases: StrEnum

The persistence axis a table policy targets.

PG is the keyed/reconciled census. PQ is the append-heavy parquet dataset leg. TablePolicy accepts the historical "pg"/"pq" spellings and normalizes them into this closed vocabulary at construction, so a typo can never silently fall through to the Postgres branch.

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

PG

PG = 'pg'

PQ

PQ = 'pq'