Python API reference¶

Signatures and members only. For parameter contracts, rejection policies, SQLRules defaults, and async caveats, use the narrative API guide and error catalog.

Entry points¶

rowguard.select(*, session=None, connection=None, table, model, where=(), field_map=None, attribute_map=None, column_map=None, parameters=None, on_reject='raise', reject_callback=None, quarantine=None, on_callback_error='raise', callback_values='full', on_quarantine_error='raise', quarantine_values='full', quarantine_retention='receipt', quarantine_transaction='separate', redact_fields=None, max_rejections=None, max_rejection_rate=None, use_sqlrules=True, compiled_rules=None, strict=None, orm_validation='mapping', unloaded_attributes='error')[source]¶

Build and execute a validation-first SQLAlchemy SELECT query.

table may be a Core Table or an ORM / SQLModel mapped class.

rowguard.execute(*, session=None, connection=None, statement, model, source=None, where=(), field_map=None, attribute_map=None, column_map=None, parameters=None, on_reject='raise', reject_callback=None, quarantine=None, on_callback_error='raise', callback_values='full', on_quarantine_error='raise', quarantine_values='full', quarantine_retention='receipt', quarantine_transaction='separate', redact_fields=None, max_rejections=None, max_rejection_rate=None, use_sqlrules=True, compiled_rules=None, strict=None, orm_validation='mapping', unloaded_attributes='error')[source]¶: Execute an existing SQLAlchemy statement and validate every row.

rowguard.stream(*, session=None, connection=None, table=None, statement=None, model, source=None, where=(), field_map=None, attribute_map=None, column_map=None, parameters=None, on_reject='raise', reject_callback=None, quarantine=None, on_callback_error='raise', callback_values='full', on_quarantine_error='raise', quarantine_values='full', quarantine_retention='receipt', quarantine_transaction='separate', redact_fields=None, max_rejections=None, max_rejection_rate=None, use_sqlrules=True, compiled_rules=None, strict=None, orm_validation='mapping', unloaded_attributes='error', yield_per=None, observers=None)[source]¶

Stream validated models without buffering all accepted rows.

Pass exactly one of table or statement. Accepted models are yielded incrementally and never retained on the result object.

async rowguard.aselect(*, session=None, connection=None, table, model, where=(), field_map=None, attribute_map=None, column_map=None, parameters=None, on_reject='raise', reject_callback=None, quarantine=None, on_callback_error='raise', callback_values='full', on_quarantine_error='raise', quarantine_values='full', quarantine_retention='receipt', quarantine_transaction='separate', redact_fields=None, max_rejections=None, max_rejection_rate=None, use_sqlrules=True, compiled_rules=None, strict=None, orm_validation='mapping', unloaded_attributes='error')[source]¶: Async variant of select using AsyncSession or AsyncConnection.

async rowguard.aexecute(*, session=None, connection=None, statement, model, source=None, where=(), field_map=None, attribute_map=None, column_map=None, parameters=None, on_reject='raise', reject_callback=None, quarantine=None, on_callback_error='raise', callback_values='full', on_quarantine_error='raise', quarantine_values='full', quarantine_retention='receipt', quarantine_transaction='separate', redact_fields=None, max_rejections=None, max_rejection_rate=None, use_sqlrules=True, compiled_rules=None, strict=None, orm_validation='mapping', unloaded_attributes='error')[source]¶: Async variant of execute using AsyncSession or AsyncConnection.

rowguard.astream(*, session=None, connection=None, table=None, statement=None, model, source=None, where=(), field_map=None, attribute_map=None, column_map=None, parameters=None, on_reject='raise', reject_callback=None, quarantine=None, on_callback_error='raise', callback_values='full', on_quarantine_error='raise', quarantine_values='full', quarantine_retention='receipt', quarantine_transaction='separate', redact_fields=None, max_rejections=None, max_rejection_rate=None, use_sqlrules=True, compiled_rules=None, strict=None, orm_validation='mapping', unloaded_attributes='error', yield_per=None, observers=None)[source]¶

Async stream of validated models without buffering accepted rows.

Returns immediately; iteration starts on async with / async for. Pydantic validation remains synchronous on the event loop.

rowguard.validate_rows(*, rows, model, field_map=None, on_reject='raise', reject_callback=None, quarantine=None, on_callback_error='raise', callback_values='full', on_quarantine_error='raise', quarantine_values='full', quarantine_retention='receipt', quarantine_transaction='separate', redact_fields=None, max_rejections=None, max_rejection_rate=None, strict=None)[source]¶: Validate row mappings without executing SQL.

rowguard.compile_plan(*, model, table=None, statement=None, source=None, where=(), field_map=None, attribute_map=None, column_map=None, parameters=None, on_reject='raise', reject_callback=None, quarantine=None, on_callback_error='raise', callback_values='full', on_quarantine_error='raise', quarantine_values='full', quarantine_retention='receipt', quarantine_transaction='separate', redact_fields=None, max_rejections=None, max_rejection_rate=None, use_sqlrules=True, compiled_rules=None, pushdown_source=None, strict=None, orm_validation='mapping', unloaded_attributes='error', async_execution=False)[source]¶: Compile an immutable execution plan without running a query.

Results and planning¶

class rowguard.QueryResult(models: 'tuple[T, ...]', rejected: 'tuple[RejectedRow, ...]', statistics: 'QueryStatistics', statement: 'Any | None' = None, diagnostics: 'tuple[Diagnostic, ...]' = (), quarantine_receipts: 'tuple[QuarantineReceipt, ...]' = ())[source]¶

Bases: Generic[T]

models¶

rejected¶

statistics¶

statement¶

diagnostics¶

quarantine_receipts¶

property has_rejections¶: True if any row was rejected during execution (including skip).

property is_clean¶: True when no rows were rejected during execution.

property valid_count¶

property rejected_count¶: Number of retained rejected rows (empty under skip).

property execution_time¶: End-to-end execution wall time in seconds (fetch + validation).

class rowguard.StreamResult(*, plan, context, streaming=None, observers=())[source]¶

Bases: Generic[T]

Incremental validated-row iterator with context-managed DB cleanup.

Accepted models are yielded and never retained. Rejected rows are retained only when the rejection policy requests it (collect).

Prefer with rowguard.stream(...) as stream: or for model in stream — both paths close the underlying SQLAlchemy result.

property closed¶

property statistics¶

property rejected¶

property quarantine_receipts¶

property diagnostics¶

property statement¶

property has_rejections¶

property is_clean¶

property rejected_count¶

property execution_time¶

close()[source]¶

class rowguard.AsyncStreamResult(*, plan, context, streaming=None, observers=())[source]¶

Bases: Generic[T]

Async incremental validated-row iterator with context-managed DB cleanup.

Accepted models are yielded and never retained. Prefer async with rowguard.astream(...) as stream: or async for model in stream.

property closed¶

property statistics¶

property rejected¶

property quarantine_receipts¶

property diagnostics¶

property statement¶

property has_rejections¶

property is_clean¶

property rejected_count¶

property execution_time¶

async close()[source]¶

class rowguard.RejectedRow(index: 'int', model: 'type[BaseModel]', mapping: 'Mapping[str, object] | None', validation_error: 'ValidationError | None', adaptation_error: 'Exception | None' = None, raw_row: 'object | None' = None, source_identity: 'Mapping[str, object] | None' = None)[source]¶

Bases: object

index¶

model¶

mapping¶

validation_error¶

adaptation_error¶

raw_row¶

source_identity¶

class rowguard.QueryStatistics(rows_read: int, rows_validated: int, rows_accepted: int, rows_rejected: int, execution_time_ns: int = 0, adaptation_time_ns: int = 0, validation_time_ns: int = 0, rejection_time_ns: int = 0)[source]¶

Bases: object

rows_read¶

rows_validated¶

rows_accepted¶

rows_rejected¶

execution_time_ns¶

adaptation_time_ns¶

validation_time_ns¶

rejection_time_ns¶

property rejection_rate¶

class rowguard.ExecutionPlan(statement, model, pushdown_plan, adapter_plan, validation_plan, rejection_plan, parameters=<factory>, diagnostics=(), execution_id='', resolved_source=None, use_sqlrules=False)[source]¶