httk.store.store_common

Backend-neutral save-path machinery shared by storage backends.

Exceptions

EntryIdConflictError	An entry id is already owned by a different lineage or alternative group.
EntryMetadataConflictError	Stored identity-excluded metadata differs from a repeated save.
EntryReplacementError	A replacement deduplicated onto a row from a different lineage.
EntryDispatchIntegrityError	A persisted entry dispatch row does not name exactly its expected backing.

Classes

EntryIdScheme	Configuration used to mint human-readable entry identifiers.
EntryStore	The store surface consumed by httk.store.backend.sql.stored_federation.
SaveProjection	One-save projection cache shared by core identity and SQL encoding.
IdentityCaches	Weak identity caches shared by storage backends.

Functions

reject_cursor_proxy(obj)

Reject a lazy cursor row before a backend attempts to save it.

Module Contents

class httk.store.store_common.EntryIdScheme

Configuration used to mint human-readable entry identifiers.

Parameters:

• base – Dot-separated database namespace.

• series – Campaign-series token.

• type_in_base – Whether the served entry type is appended to base.

base: str

series: str

type_in_base: bool = False

exception httk.store.store_common.EntryIdConflictError(table_name, entry_id, existing_logical_id, requested_logical_id)

Bases: ValueError

An entry id is already owned by a different lineage or alternative group.

Parameters:

• table_name (str) – The table containing the conflicting identifier.

• entry_id (str) – The conflicting entry identifier.

• existing_logical_id (int | None) – The lineage or group already owning the identifier.

• requested_logical_id (int | None) – The lineage or group requesting it, when known.

table_name

entry_id

existing_logical_id

requested_logical_id

class httk.store.store_common.EntryStore

Bases: Protocol

The store surface consumed by httk.store.backend.sql.stored_federation.

This protocol deliberately describes the small backend seam used by the federation. The stored-property plan and candidate-stream objects remain backend-specific; their SQL implementations use searcher().

property entry_layout: tuple[httk.store.storage_layout.EntryFamilyLayout, Ellipsis]

Return the configured entry-family layouts in stable order.

searcher(*, as_of=None)

Return a backend searcher used to build candidate ID streams.

fetch(cls, sid, *, eager=False)

Fetch the stored record of cls identified by sid.

Parameters:

• cls (type[_StoredRecord]) – The storable record class.

• sid (int) – The stored row identifier to fetch.

• eager (bool) – Whether to fully materialize the record instead of returning a lazy row.

Returns:

The reconstructed instance.

Return type:

_StoredRecord

fetch_many(cls, sids, *, eager=False)

Fetch the stored records of cls identified by sids.

Batched counterpart of fetch().

Parameters:

• cls (type[_StoredRecord]) – The storable record class.

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

• eager (bool) – Whether to fully materialize each record instead of returning lazy rows.

Returns:

The reconstructed instances in sids order.

Raises:

KeyError – When any requested row is absent.

Return type:

list[_StoredRecord]

stored_property_plan(family)

Return the backend-specific stored-property plan for one family.

Parameters:

family (type) – The logical entry-family class to plan.

Returns:

The validated stored-property plan consumed by federation.

Return type:

Any

exception httk.store.store_common.EntryMetadataConflictError

Bases: ValueError

Stored identity-excluded metadata differs from a repeated save.

exception httk.store.store_common.EntryReplacementError(table_name, predecessor_logical_id, conflicting_logical_id)

Bases: ValueError

A replacement deduplicated onto a row from a different lineage.

Parameters:

• table_name (str) – The table (or collection) whose replacement failed.

• predecessor_logical_id (int) – The logical_id of the intended predecessor.

• conflicting_logical_id (int) – The logical_id of the row actually hit.

table_name

predecessor_logical_id

conflicting_logical_id

exception httk.store.store_common.EntryDispatchIntegrityError

Bases: RuntimeError

A persisted entry dispatch row does not name exactly its expected backing.

class httk.store.store_common.SaveProjection(*, store_timestamp=None)

One-save projection cache shared by core identity and SQL encoding.

store_timestamp = None

values_by_source: dict[tuple[type, int], collections.abc.Mapping[str, object]]

validated: set[tuple[type, int]]

metadata_rows: dict[tuple[type, int], collections.abc.Mapping[str, Any]]

metadata_children: dict[tuple[type, int, str], Any]

metadata_content_ids: dict[tuple[type, int], str]

active: set[tuple[type, int]]

inserted: list[tuple[type, int]] = []

projector(record_type, source)

content_id(record_type, source, *, extras=None)

httk.store.store_common.reject_cursor_proxy(obj)

Reject a lazy cursor row before a backend attempts to save it.

class httk.store.store_common.IdentityCaches

Weak identity caches shared by storage backends.