httk.core.vectors.leaf_codecs

Leaf codecs: the element-domain axis of the Vector family.

The Vector backends model the container axis (frac/native/numpy); a leaf codec models the orthogonal element-domain axis — how a single leaf value is presented (as an int, a fractions.Fraction, a float, a decimal.Decimal, …). Every codec converts FROM the canonical Fraction hub (a backend’s exact fractions interchange), so it is independent of which backend holds the data.

Conversion policy (mirroring the CellParams lossiness philosophy): because a backend always retains the exact original, a view that cannot represent the data exactly is still produced without raising — each codec applies a documented default conversion, with options to choose alternatives. Only configuration errors — an unknown codec name or invalid options — raise ValueError.

This registry mirrors the compression-codec registry in httk.core.datastream.compression: a frozen LeafCodec dataclass plus register_leaf_codec()/known_leaf_codecs() for extension.

Classes

LeafCodec

A leaf codec: a documented conversion of one exact fractions.Fraction leaf into a

Functions

register_leaf_codec(→ None)	Register (or replace) a codec under its name.
known_leaf_codecs(→ list[str])	Return the registered leaf-codec names, in registration order.
leaf_codec_for_name(→ LeafCodec)	Return the registered codec named name, or raise ValueError listing the known
validate_leaf_codec(→ LeafCodec)	Resolve and validate a leaf codec eagerly and return it.
apply_leaf_codec(→ Any)	Map codec over a (possibly nested) tuple of fractions.Fraction, returning the

Module Contents

class httk.core.vectors.leaf_codecs.LeafCodec

A leaf codec: a documented conversion of one exact fractions.Fraction leaf into a presentation leaf.

A codec is an orthogonal layer beside the vector backends: given a value already reduced to the canonical Fraction hub, it produces the requested element type. Its from_fraction documents both its exactness contract (when the result is exact) and its default conversion (what it does when an exact result is impossible); on data it never raises.

name: str

Canonical codec name (e.g. "int"); also how an explicit leaf= hint selects it.

from_fraction: collections.abc.Callable[Ellipsis, Any]

Convert (value: fractions.Fraction, **options) -> leaf from the canonical Fraction hub.

check_options: collections.abc.Callable[[dict[str, Any]], None]

Validate an options mapping eagerly, raising ValueError on any invalid option.

httk.core.vectors.leaf_codecs.register_leaf_codec(codec: LeafCodec) → None

Register (or replace) a codec under its name.

httk.core.vectors.leaf_codecs.known_leaf_codecs() → list[str]

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

httk.core.vectors.leaf_codecs.leaf_codec_for_name(name: str) → LeafCodec

Return the registered codec named name, or raise ValueError listing the known codecs.

httk.core.vectors.leaf_codecs.validate_leaf_codec(name: str, options: dict[str, Any]) → LeafCodec

Resolve and validate a leaf codec eagerly and return it.

Raises ValueError if name is not a registered codec or if options are invalid for it (the two configuration-error cases). This is called where a leaf= hint is received so that mistakes surface at view construction, never mid-conversion.

httk.core.vectors.leaf_codecs.apply_leaf_codec(codec: LeafCodec, node: Any, **options: Any) → Any

Map codec over a (possibly nested) tuple of fractions.Fraction, returning the converted nested structure (a bare leaf for a scalar node).