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(codec)

Register or replace a codec under its name.

known_leaf_codecs()

Return the registered leaf-codec names in registration order.

leaf_codec_for_name(name)

Return the registered codec named name.

validate_leaf_codec(name, options)

Resolve and validate a leaf codec eagerly and return it.

apply_leaf_codec(codec, node, **options)

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.

Parameters:

  • name – The canonical name used to select the codec.

  • from_fraction – The conversion operation applied to each exact hub leaf.

  • check_options – The option-validation operation.

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)

Register or replace a codec under its name.

Parameters:

codec (LeafCodec) – The codec to register.

httk.core.vectors.leaf_codecs.known_leaf_codecs()

Return the registered leaf-codec names in registration order.

Returns:

The registered codec names.

Return type:

list[str]

httk.core.vectors.leaf_codecs.leaf_codec_for_name(name)

Return the registered codec named name.

Parameters:

name (str) – The codec name to resolve.

Returns:

The registered codec.

Raises:

ValueError – If name is not registered.

Return type:

LeafCodec

httk.core.vectors.leaf_codecs.validate_leaf_codec(name, options)

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.

Parameters:

  • name (str) – The codec name to resolve.

  • options (dict[str, Any]) – The options to validate for the codec.

Returns:

The resolved and validated codec.

Raises:

ValueError – If the codec name or options are invalid.

Return type:

LeafCodec

httk.core.vectors.leaf_codecs.apply_leaf_codec(codec, node, **options)

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

Parameters:

  • codec (LeafCodec) – The codec to apply.

  • node (Any) – The scalar or nested exact data to convert.

  • **options (Any) – Options passed to the codec for each leaf.

Returns:

The converted scalar or nested structure.

Return type:

Any