httk.store.db.codecs¶

Value codecs: exact, round-trippable encodings of rich Python values into scalar columns.

A ValueCodec describes how one field value of a given Python type is stored across one or more scalar columns and recovered exactly. The registry (register_value_codec() / codec_for() / codec_named()) mirrors the leaf-codec registry idiom in httk.core.vectors: a frozen dataclass plus module-level registration functions, with built-in codecs registered at import time.

Rational values are stored losslessly: a query/index column holds the nearest float (comparisons on it are documented float-approximate), while a companion *_exact text column holds a canonical exact form that is the round-trip source of truth. The canonical text formats are:

float.hex() — the exact finite IEEE-754 binary64 value, including the sign of zero. Used for scalar float fields and float sequence elements; the accompanying SQL DOUBLE remains the query/sort presentation.
FRACTION_EXACT_FORMAT — a reduced fraction as "p/q", always with the /q part ("1/1" for one), denominator positive. Used for fractions.Fraction and FracScalar.
SURD_EXACT_FORMAT — a SurdScalar as its canonical radicand map: "r1:p1/q1;r2:p2/q2;..." sorted by squarefree radicand ("0" for zero), e.g. "1:1/2;2:3/4" for 1/2 + (3/4)*sqrt(2).
FRACVECTOR_EXACT_FORMAT — a FracVector tensor as "d;n0,n1,n2,...": the least positive common denominator d followed by the integer numerators flattened row-major. Used by the schema layer for fixed-shape (Shape) fields and per-row child-table storage.

httk-core is a hard dependency of httk-store, so the httk.core vector types are imported unconditionally; nothing in this module needs sqlalchemy.

Attributes¶

`ScalarKind`	The five scalar column kinds a storage backend must provide.
`FRACTION_EXACT_FORMAT`	The canonical exact text of a rational — reduced `"p/q"`, always with the `/q` part.
`SURD_EXACT_FORMAT`	The canonical exact text of a surd scalar — `radicand:coefficient` terms sorted by radicand.
`FRACVECTOR_EXACT_FORMAT`	The canonical exact text of a rational tensor — common denominator, then numerators row-major.

Classes¶

ValueCodec

An exact encoding of one Python value type across one or more scalar columns.

Functions¶

`register_value_codec`(codec)	Register `codec` in the value-codec registry.
`known_value_codecs`()	Return the registered value-codec names in registration order.
`codec_for`(python_type)	Return the codec for `python_type`, or None if no codec covers it.
`codec_named`(name)	Return the codec registered as `name`.
`encode_fraction_exact`(value)	Encode a fraction in the canonical exact text format.
`decode_fraction_exact`(text)	Decode canonical exact fraction text.
`encode_surdscalar_exact`(value)	The canonical `SURD_EXACT_FORMAT` text of `value` (`"0"` for zero).
`decode_surdscalar_exact`(text)	Decode canonical exact surd text.
`encode_fracvector_exact`(value)	The canonical `FRACVECTOR_EXACT_FORMAT` text of a rational tensor.
`decode_fracvector_exact`(text, rows, cols)	Parse `FRACVECTOR_EXACT_FORMAT` text into a `rows` x `cols` `FracVector`.
`encode_fracvector_floats`(value)	The elements of a rational tensor as a flat row-major tuple of nearest floats.

Module Contents¶

type httk.store.db.codecs.ScalarKind = Literal['int', 'float', 'str', 'bool', 'bytes'][source]¶: The five scalar column kinds a storage backend must provide.

httk.store.db.codecs.FRACTION_EXACT_FORMAT: Final = 'p/q'[source]¶: The canonical exact text of a rational — reduced "p/q", always with the /q part.

httk.store.db.codecs.SURD_EXACT_FORMAT: Final = 'r1:p1/q1;r2:p2/q2;...'[source]¶: The canonical exact text of a surd scalar — radicand:coefficient terms sorted by radicand.

httk.store.db.codecs.FRACVECTOR_EXACT_FORMAT: Final = 'd;n0,n1,n2,...'[source]¶: The canonical exact text of a rational tensor — common denominator, then numerators row-major.

class httk.store.db.codecs.ValueCodec[source]¶

An exact encoding of one Python value type across one or more scalar columns.

The columns tuple gives (suffix, kind) pairs: the empty suffix names the field’s own column (by convention the query column), non-empty suffixes are appended to the field name by the schema layer (e.g. "_exact"). encode and decode map a value to and from the column-value tuple, in columns order, and must round-trip exactly.

Parameters:

name – The registry name of the codec.
python_type – The Python type stored by the codec.
columns – The column suffix and scalar-kind pairs encoded by the codec.
encode – The function that encodes a value into column values.
decode – The function that reconstructs a value from column values.
query_suffix – The suffix of the query and index column.

name: str[source]¶: Registry name of the codec (e.g. "fraction").

python_type: type[source]¶: The Python type this codec stores; matched exactly first, then by subclass.

columns: tuple[tuple[str, httk.store.db.codecs.ScalarKind], ...][source]¶: The (column name suffix, scalar kind) pairs the codec encodes into.

encode: collections.abc.Callable[[Any], tuple[Any, Ellipsis]][source]¶: Encode a value into one scalar per entry of columns, in order.

decode: collections.abc.Callable[[tuple[Any, Ellipsis]], Any][source]¶: Recover the exact value from the tuple produced by encode.

query_suffix: str = ''[source]¶: Suffix of the column used for querying/indexing (normally the empty suffix).

httk.store.db.codecs.register_value_codec(codec)[source]¶

Parameters:: codec (ValueCodec) – The codec to register.
Returns:: None.
Raises:: ValueError – If the codec name or Python type is already registered.
Return type:: None

httk.store.db.codecs.known_value_codecs()[source]¶

Return the registered value-codec names in registration order.

Returns:: The registered codec names.
Return type:: list[str]

httk.store.db.codecs.codec_for(python_type)[source]¶

Return the codec for python_type, or None if no codec covers it.

An exact type match wins. Subclasses reuse only codecs for core-native canonical types; custom codec registrations are exact-type only so SQL encoding and content identity cannot disagree.

Parameters:: python_type (Any) – The Python type to look up.
Returns:: The matching codec, or None when no codec covers the type.
Return type:: ValueCodec | None

httk.store.db.codecs.codec_named(name)[source]¶

Return the codec registered as name.

Parameters:: name (str) – The registered codec name.
Returns:: The matching value codec.
Raises:: ValueError – If no codec has that name.
Return type:: ValueCodec

httk.store.db.codecs.encode_fraction_exact(value)[source]¶

Encode a fraction in the canonical exact text format.

Parameters:: value (fractions.Fraction) – The fraction to encode.
Returns:: The canonical p/q text.
Return type:: str

httk.store.db.codecs.decode_fraction_exact(text)[source]¶

Decode canonical exact fraction text.

Parameters:

text (str) – The fraction text to parse.

Returns:

The exact fraction.

Raises:

ValueError – If the text is malformed.
ZeroDivisionError – If the denominator is zero.

Return type:

fractions.Fraction

httk.store.db.codecs.encode_surdscalar_exact(value)[source]¶

The canonical SURD_EXACT_FORMAT text of value ("0" for zero).

The terms are the canonical radicand map of the surd — squarefree radicands in increasing order, each with its reduced rational coefficient — so the text is unique per value and round-trips exactly.

Parameters:: value (httk.core.SurdScalar) – The surd scalar to encode.
Returns:: The canonical surd text.
Return type:: str

httk.store.db.codecs.decode_surdscalar_exact(text)[source]¶

Decode canonical exact surd text.

Parameters:

text (str) – The surd text to parse.

Returns:

The exact surd scalar.

Raises:

ValueError – If the text is malformed.
ZeroDivisionError – If a coefficient denominator is zero.

Return type:

httk.core.SurdScalar

httk.store.db.codecs.encode_fracvector_exact(value)[source]¶

The canonical FRACVECTOR_EXACT_FORMAT text of a rational tensor.

The tensor is flattened row-major and normalized through to_fractions(): d is the least positive common denominator of the (reduced) elements and the numerators are the elements scaled by d. The text is therefore canonical — independent of the internal denominator the input happened to carry — and lossless at arbitrary precision. The shape itself is not encoded; fixed-shape schema fields carry it in their declaration.

Parameters:: value (httk.core.FracVector) – The rational tensor to encode.
Returns:: The canonical exact tensor text.
Return type:: str

httk.store.db.codecs.decode_fracvector_exact(text, rows, cols)[source]¶

Parse FRACVECTOR_EXACT_FORMAT text into a rows x cols FracVector.

The numerators are laid out row-major into a tensor of shape (rows, cols); their count must equal rows * cols. Raises ValueError on malformed text or a count/shape mismatch.

Parameters:

text (str) – The exact tensor text to parse.
rows (int) – The expected row count.
cols (int) – The expected column count.

Returns:

The reconstructed rational tensor.

Raises:

ValueError – If the text or requested shape is invalid.

Return type:

httk.core.FracVector

httk.store.db.codecs.encode_fracvector_floats(value)[source]¶

The elements of a rational tensor as a flat row-major tuple of nearest floats.

This is the (documented approximate) companion of encode_fracvector_exact(), used to fill the per-element float query/index columns of fixed-shape fields.

Parameters:: value (httk.core.FracVector) – The rational tensor to convert.
Returns:: The row-major floating-point values.
Return type:: tuple[float, Ellipsis]