httk.store.db.stored_federation

Bounded, durable federation of stored entry-family property plans.

Unlike httk.store.federated_store, which is the general portable query protocol, this module joins only configured durable entry families. It can therefore retain a stable backing inventory, push candidate filtering and bounds into SQL, and delay record hydration until a global page is known.

Exceptions

DuplicateEntryIdError

Several durable origins claim the same public entry id.

Classes

StoredEntrySource	One named configured family in one durable entry store.
StoredEntryOrigin	The durable source of one public entry id.
StoredEntryPage	One immutable globally paginated response.
StoredEntryFederation	Merge one or more configured durable entry-family sources.

Module Contents

class httk.store.db.stored_federation.StoredEntrySource

One named configured family in one durable entry store.

public_id_prefix is concatenated with every backing’s canonical content id. It is intentionally not required to be unique: callers may retain a legacy unprefixed source, in which case collisions are detected when their visible ids are fetched or explicitly audited.

Parameters:

• store – The durable entry store containing the entry family.

• entry_family – The logical entry-family class to serve.

• name – The unique name used to identify this source.

• public_id_prefix – The prefix prepended to canonical content ids.

store: httk.store.store_common.EntryStore

entry_family: type

name: str

public_id_prefix: str = ''

class httk.store.db.stored_federation.StoredEntryOrigin

The durable source of one public entry id.

Parameters:

• source – The configured source name.

• source_index – The source’s position in the federation.

• backing – The concrete backing name.

• content_id – The canonical content id claimed by the backing.

source: str

source_index: int

backing: str

content_id: str

exception httk.store.db.stored_federation.DuplicateEntryIdError(public_id, origins)

Bases: RuntimeError

Several durable origins claim the same public entry id.

Call StoredEntryFederation.audit_duplicate_ids() to perform the intentionally explicit complete audit; ordinary pages inspect only the candidates they would otherwise return.

Parameters:

• public_id (str) – The public id claimed by multiple origins.

• origins (collections.abc.Sequence[StoredEntryOrigin]) – The durable origins claiming the id.

public_id

origins

class httk.store.db.stored_federation.StoredEntryPage

One immutable globally paginated response.

total_count is the exact filtered count before global offset/limit. The sentinel establishing more_data_available is ID-only and is never present in rows.

Parameters:

• rows – The rows visible in this page.

• total_count – The exact filtered count before paging bounds.

• more_data_available – Whether another row exists after this page.

rows: tuple[collections.abc.Mapping[str, Any], Ellipsis]

total_count: int

more_data_available: bool

class httk.store.db.stored_federation.StoredEntryFederation(sources)

Merge one or more configured durable entry-family sources.

Sources preserve caller order. Without a sort, rows remain in source, persisted-backing, and native database order and candidate SQL contains no ORDER BY. With a sort, each backing stream orders in SQL and this object performs a bounded heap merge with a deterministic public-id/source /backing tie-breaker.

Pages probe all sibling backings in prefixes shared by multiple sources. Within-source corruption is otherwise audit-only; use audit_duplicate_ids() to detect it.

Parameters:

sources (collections.abc.Sequence[StoredEntrySource]) – The configured sources to merge in caller order.

property sources: tuple[StoredEntrySource, Ellipsis]

Return the immutable declared source order.

Returns:

The declared sources in caller order.

Return type:

tuple[StoredEntrySource, Ellipsis]

query(filter_string=None, *, sort=(), offset=0, limit=None)

Return one globally merged page with an exact filtered total.

limit=0 intentionally runs only count plus an ID-only sentinel: it is suitable for metadata initialization and never duplicate-probes or hydrates a candidate.

Parameters:

• filter_string (str | httk.core.optimade.FilterAst | None) – The OPTIMADE filter, parsed filter tree, or no filter.

• sort (collections.abc.Sequence[tuple[str, bool]]) – The property sort keys and directions.

• offset (int) – The number of matching rows to skip globally.

• limit (int | None) – The maximum number of rows to return, or no maximum.

Returns:

The globally merged page.

Raises:

DuplicateEntryIdError – If a visible id has multiple cross-source origins.

Return type:

StoredEntryPage

fetch(public_id)

Fetch one public id and detect a collision among its possible origins.

Parameters:

public_id (str) – The public id to fetch.

Returns:

The fetched response row, or None when it is absent.

Raises:

DuplicateEntryIdError – If the id has multiple origins.

Return type:

collections.abc.Mapping[str, Any] | None

audit_duplicate_ids(*, batch_size=_AUDIT_BATCH_SIZE)

Lazily scan sorted ID-only batches and raise on the first collision.

The audit includes duplicate ids across backings within one source as well as duplicates across sources.

Parameters:

batch_size (int) – The maximum number of candidate ids read per batch.

Returns:

None.

Raises:

DuplicateEntryIdError – If any public id has multiple origins.

Return type:

None