Equivalence¶

equivalence ¶

Result-set equivalence engine: column reconciliation plus the pure build_result_set_diff assembly seam.

ColumnReconciliation ¶

Bases: NamedTuple

The outcome of reconciling actual against expected column names.

Attributes:

Name	Type	Description
`in_both`	`list[str]`	Columns present in both, in expected order; the columns compared on.
`missing`	`list[str]`	Columns expected but absent from actual, in expected order.
`unexpected`	`list[str]`	Columns present in actual but not expected, in actual order.
`order_mismatch`	`bool`	`True` only when `column_order == "strict"` and the sequences differ positionally.

reconcile_columns ¶

reconcile_columns(
    actual: list[str],
    expected: list[str],
    column_order: Literal["ignore", "strict"],
) -> ColumnReconciliation

Reconcile actual against expected column-name sequences.

Row comparison is always keyed by name (rows are dicts), so the order signal is a separate assertion rather than a constraint on row matching.

Parameters:

Name	Type	Description	Default
`actual`	`list[str]`	Column names from the actual result set.	required
`expected`	`list[str]`	Column names from the expected result set.	required
`column_order`	`Literal['ignore', 'strict']`	`"strict"` to flag a positional order difference, `"ignore"` to disregard ordering.	required

Returns:

Type	Description
`ColumnReconciliation`	A `ColumnReconciliation`. The `in_both`/`missing`/`unexpected` lists preserve
`ColumnReconciliation`	source order by construction (the sets are membership lookups only).

build_result_set_diff ¶

build_result_set_diff(
    *,
    expected_row_count: int,
    actual_row_count: int,
    missing_row_count: int,
    extra_row_count: int,
    sample_missing_rows: list[dict[str, Any]],
    sample_extra_rows: list[dict[str, Any]],
    columns: ColumnReconciliation,
    type_mismatches: list[TypeMismatch],
    column_mismatches: list[ColumnMismatch],
) -> ResultSetDiff | None

Assemble a ResultSetDiff from already-computed diff signals.

Warehouse-free: the row counts/samples are computed by the engine and the column/type signals in Python, then passed here. column_mismatches is populated only by the keyed FULL OUTER JOIN path (empty for the keyless EXCEPT ALL path).

Parameters:

Name	Type	Description	Default
`expected_row_count`	`int`	The number of expected rows.	required
`actual_row_count`	`int`	The number of actual rows.	required
`missing_row_count`	`int`	Rows present in expected but absent from actual.	required
`extra_row_count`	`int`	Rows present in actual but absent from expected.	required
`sample_missing_rows`	`list[dict[str, Any]]`	A bounded sample of the missing rows.	required
`sample_extra_rows`	`list[dict[str, Any]]`	A bounded sample of the extra rows.	required
`columns`	`ColumnReconciliation`	The reconciliation of actual against expected column names.	required
`type_mismatches`	`list[TypeMismatch]`	Per-column type differences over the shared columns.	required
`column_mismatches`	`list[ColumnMismatch]`	Per-column counts of key-matched rows whose value differs; empty for the keyless path.	required

Returns:

Type	Description
`ResultSetDiff \| None`	`None` if the assembled diff records no differences (the result sets are equal),
`ResultSetDiff \| None`	else the populated `ResultSetDiff`.

combine ¶

combine(
    verdicts: list[SemanticVerdict], *, scorer: str
) -> ScoreResult

Combine ordered equivalence verdicts into one ScoreResult.

The first "equivalent" verdict yields a passing result; if no verdict confirms, the result is inconclusive (the checks never refute, so an undecided run is not a fail). A verdict never carries a diff, so the result carries none. Every verdict is recorded in metadata["verdicts"].

Parameters:

Name	Type	Description	Default
`verdicts`	`list[SemanticVerdict]`	The verdicts the checks produced, in the order they ran.	required
`scorer`	`str`	The scorer name to stamp on the `ScoreResult`.	required

Returns:

Type	Description
`ScoreResult`	A passing `ScoreResult` when some verdict confirmed equivalence, else an inconclusive one.