httk.store.storage_layout

Backend-neutral store declaration machinery shared by storage backends.

This module owns the logical entry-family declaration, its canonical JSON encoding, and trust-on-reopen validation. Physical names and backend-specific layout validation belong to each storage backend.

Attributes

DECLARATION_PROTOCOL_VERSION

The current backend-neutral declaration protocol.

Exceptions

StorageLayoutUpgradeRequiredError

A database does not exactly implement the current persisted store layout.

Classes

EntryFamilyLayout	One immutable configured entry family and its concrete records.
StorageLayout	The immutable normalized entry declaration of an initialized store.

Functions

normalize_entry_records(entry_records)	Validate an explicit class declaration and replace it with stable registry names.
declaration_json(layout)	Serialize a normalized declaration in its exact deterministic persisted form.

Module Contents

httk.store.storage_layout.DECLARATION_PROTOCOL_VERSION: Final = 'v2.1.0'

The current backend-neutral declaration protocol.

exception httk.store.storage_layout.StorageLayoutUpgradeRequiredError(diff)

Bases: RuntimeError

A database does not exactly implement the current persisted store layout.

diff is immutable and JSON-shaped. Its top-level keys are stable categories (currently protocol, declaration and schema), so a caller can present a precise upgrade diagnostic without parsing the human-readable exception message.

diff: collections.abc.Mapping[str, object]

class httk.store.storage_layout.EntryFamilyLayout

One immutable configured entry family and its concrete records.

name: str

family: type

record_names: tuple[str, Ellipsis]

records: tuple[type, Ellipsis]

class httk.store.storage_layout.StorageLayout

The immutable normalized entry declaration of an initialized store.

protocol_version: str

families: tuple[EntryFamilyLayout, Ellipsis]

property entry_records: collections.abc.Mapping[type, tuple[type, Ellipsis]]

Configured family classes mapped to their ordered concrete record classes.

property declaration: collections.abc.Mapping[str, tuple[str, Ellipsis]]

Configured stable family names mapped to their ordered stable record names.

httk.store.storage_layout.normalize_entry_records(entry_records)

Validate an explicit class declaration and replace it with stable registry names.

Registry aliases are rejected rather than selected arbitrarily: a persistent declaration must have exactly one stable spelling for every supplied class.

httk.store.storage_layout.declaration_json(layout)

Serialize a normalized declaration in its exact deterministic persisted form.