httk.data.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:

• 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-data, 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(→ None)	Register codec; raise ValueError on a duplicate name or Python type.
known_value_codecs(→ list[str])	Return the registered value-codec names, in registration order.
codec_for(→ ValueCodec | None)	Return the codec for python_type, or None if no codec covers it.
codec_named(→ ValueCodec)	Return the codec registered as name; raise ValueError listing the known names.
encode_fraction_exact(→ str)	The canonical FRACTION_EXACT_FORMAT text of value (e.g. "-7/3", "1/1").
decode_fraction_exact(→ fractions.Fraction)	Parse FRACTION_EXACT_FORMAT text back into an exact fractions.Fraction.
encode_surdscalar_exact(→ str)	The canonical SURD_EXACT_FORMAT text of value ("0" for zero).
decode_surdscalar_exact(→ httk.core.SurdScalar)	Parse SURD_EXACT_FORMAT text back into an exact SurdScalar.
encode_fracvector_exact(→ str)	The canonical FRACVECTOR_EXACT_FORMAT text of a rational tensor.
decode_fracvector_exact(→ httk.core.FracVector)	Parse FRACVECTOR_EXACT_FORMAT text into a rows x cols FracVector.
encode_fracvector_floats(→ tuple[float, Ellipsis])	The elements of a rational tensor as a flat row-major tuple of nearest floats.

Module Contents

type httk.data.db.codecs.ScalarKind = Literal['int', 'float', 'str', 'bool', 'bytes']

The five scalar column kinds a storage backend must provide.

httk.data.db.codecs.FRACTION_EXACT_FORMAT: Final = 'p/q'

The canonical exact text of a rational — reduced "p/q", always with the /q part.

httk.data.db.codecs.SURD_EXACT_FORMAT: Final = 'r1:p1/q1;r2:p2/q2;...'

The canonical exact text of a surd scalar — radicand:coefficient terms sorted by radicand.

httk.data.db.codecs.FRACVECTOR_EXACT_FORMAT: Final = 'd;n0,n1,n2,...'

The canonical exact text of a rational tensor — common denominator, then numerators row-major.

class httk.data.db.codecs.ValueCodec

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.

name: str

Registry name of the codec (e.g. "fraction").

python_type: type

The Python type this codec stores; matched exactly first, then by subclass.

columns: tuple[tuple[str, ScalarKind], Ellipsis]

The (column name suffix, scalar kind) pairs the codec encodes into.

encode: collections.abc.Callable[[Any], tuple[Any, Ellipsis]]

Encode a value into one scalar per entry of columns, in order.

decode: collections.abc.Callable[[tuple[Any, Ellipsis]], Any]

Recover the exact value from the tuple produced by encode.

query_suffix: str = ''

Suffix of the column used for querying/indexing (normally the empty suffix).

httk.data.db.codecs.register_value_codec(codec: ValueCodec) → None

Register codec; raise ValueError on a duplicate name or Python type.

httk.data.db.codecs.known_value_codecs() → list[str]

Return the registered value-codec names, in registration order.

httk.data.db.codecs.codec_for(python_type: Any) → ValueCodec | None

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

An exact type match wins; otherwise the registered codecs are scanned once in registration order and the first whose python_type is a base class of python_type is returned (deterministic by registration order).

httk.data.db.codecs.codec_named(name: str) → ValueCodec

Return the codec registered as name; raise ValueError listing the known names.

httk.data.db.codecs.encode_fraction_exact(value: fractions.Fraction) → str

The canonical FRACTION_EXACT_FORMAT text of value (e.g. "-7/3", "1/1").

httk.data.db.codecs.decode_fraction_exact(text: str) → fractions.Fraction

Parse FRACTION_EXACT_FORMAT text back into an exact fractions.Fraction.

httk.data.db.codecs.encode_surdscalar_exact(value: httk.core.SurdScalar) → str

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.

httk.data.db.codecs.decode_surdscalar_exact(text: str) → httk.core.SurdScalar

Parse SURD_EXACT_FORMAT text back into an exact SurdScalar.

httk.data.db.codecs.encode_fracvector_exact(value: httk.core.FracVector) → str

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.

httk.data.db.codecs.decode_fracvector_exact(text: str, rows: int, cols: int) → httk.core.FracVector

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.

httk.data.db.codecs.encode_fracvector_floats(value: httk.core.FracVector) → tuple[float, Ellipsis]

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.