httk.store.db.rows

Batched storage rows with lazy, exact field reconstruction.

Exceptions

StaleResultError

A search result sid disappeared before its lazy row was hydrated.

Classes

RowHydrator

Hydrate a sid sequence in 500-row batches without touching field values yet.

Functions

decode_field(store, schema, spec, sid, row)	Decode one pinned parent-row value.
row_class(cls)	Return the cached lazy subclass for a frozen storable dataclass.

Module Contents

exception httk.store.db.rows.StaleResultError

Bases: RuntimeError

A search result sid disappeared before its lazy row was hydrated.

class httk.store.db.rows.RowHydrator(store, schema_or_cls, sids, *, context=None)

Hydrate a sid sequence in 500-row batches without touching field values yet.

Parameters:

• store (httk.store.db.store.SqlStore) – The store that owns the rows.

• schema_or_cls (httk.store.db.schema.TableSchema | type) – The resolved schema or storable class to hydrate.

• sids (collections.abc.Sequence[int]) – The row identifiers to hydrate.

• context (_Context | None) – The shared recursive hydration context, if one exists.

row(sid)

Return the lazy row for sid.

Parameters:

sid (int) – The row identifier.

Returns:

The lazy row proxy.

Raises:

KeyError – If sid is not in this hydrator’s sequence.

Return type:

Any

Database presence is validated when the row’s chunk is loaded or the row is materialized.

materialize_many()

Materialize every row in this batch while retaining recursive chunk batching.

Returns:

The materialized rows in the input order.

Raises:

httk.store.db.rows.StaleResultError – If a requested row no longer exists.

Return type:

tuple[Any, Ellipsis]

materialize(sid)

Materialize and return one row.

Parameters:

sid (int) – The row identifier.

Returns:

The materialized storable instance.

Raises:

• KeyError – If sid is not in this hydrator’s sequence.

• httk.store.db.schema.SchemaError – If eager hydration encounters a reference cycle.

• httk.store.db.rows.StaleResultError – If the row no longer exists.

Return type:

Any

httk.store.db.rows.decode_field(store, schema, spec, sid, row)

Decode one pinned parent-row value.

Parameters:

• store (httk.store.db.store.SqlStore) – The store supplying recursive row hydration.

• schema (httk.store.db.schema.TableSchema) – The schema of the parent row.

• spec (httk.store.db.schema.FieldSpec) – The field specification to decode.

• sid (int) – The parent row identifier.

• row (Any) – The pinned parent row.

Returns:

The decoded field value.

Raises:

TypeError – If the field needs its row chunk for child or reference hydration.

Return type:

Any

httk.store.db.rows.row_class(cls)

Return the cached lazy subclass for a frozen storable dataclass.

Parameters:

cls (type) – The frozen storable dataclass to proxy.

Returns:

The cached lazy row subclass.

Raises:

httk.store.db.schema.SchemaError – If the class uses unsupported slots or custom equality or hashing.

Return type:

type