httk.store.db.codecs ==================== .. py:module:: httk.store.db.codecs .. autoapi-nested-parse:: Value codecs: exact, round-trippable encodings of rich Python values into scalar columns. A :class:`ValueCodec` describes how one field value of a given Python type is stored across one or more scalar columns and recovered exactly. The registry (:func:`register_value_codec` / :func:`codec_for` / :func:`codec_named`) mirrors the leaf-codec registry idiom in :mod:`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. - :data:`FRACTION_EXACT_FORMAT` — a reduced fraction as ``"p/q"``, always with the ``/q`` part (``"1/1"`` for one), denominator positive. Used for :class:`fractions.Fraction` and :class:`~httk.core.FracScalar`. - :data:`SURD_EXACT_FORMAT` — a :class:`~httk.core.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)``. - :data:`FRACVECTOR_EXACT_FORMAT` — a :class:`~httk.core.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 ---------- .. autoapisummary:: httk.store.db.codecs.ScalarKind httk.store.db.codecs.FRACTION_EXACT_FORMAT httk.store.db.codecs.SURD_EXACT_FORMAT httk.store.db.codecs.FRACVECTOR_EXACT_FORMAT Classes ------- .. autoapisummary:: httk.store.db.codecs.ValueCodec Functions --------- .. autoapisummary:: httk.store.db.codecs.register_value_codec httk.store.db.codecs.known_value_codecs httk.store.db.codecs.codec_for httk.store.db.codecs.codec_named httk.store.db.codecs.encode_fraction_exact httk.store.db.codecs.decode_fraction_exact httk.store.db.codecs.encode_surdscalar_exact httk.store.db.codecs.decode_surdscalar_exact httk.store.db.codecs.encode_fracvector_exact httk.store.db.codecs.decode_fracvector_exact httk.store.db.codecs.encode_fracvector_floats Module Contents --------------- .. py:type:: ScalarKind :canonical: Literal['int', 'float', 'str', 'bool', 'bytes'] The five scalar column kinds a storage backend must provide. .. py:data:: FRACTION_EXACT_FORMAT :type: Final :value: 'p/q' The canonical exact text of a rational — reduced ``"p/q"``, always with the ``/q`` part. .. py:data:: SURD_EXACT_FORMAT :type: Final :value: 'r1:p1/q1;r2:p2/q2;...' The canonical exact text of a surd scalar — ``radicand:coefficient`` terms sorted by radicand. .. py:data:: FRACVECTOR_EXACT_FORMAT :type: Final :value: 'd;n0,n1,n2,...' The canonical exact text of a rational tensor — common denominator, then numerators row-major. .. py:class:: 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. :param name: The registry name of the codec. :param python_type: The Python type stored by the codec. :param columns: The column suffix and scalar-kind pairs encoded by the codec. :param encode: The function that encodes a value into column values. :param decode: The function that reconstructs a value from column values. :param query_suffix: The suffix of the query and index column. .. py:attribute:: name :type: str Registry name of the codec (e.g. ``"fraction"``). .. py:attribute:: python_type :type: type The Python type this codec stores; matched exactly first, then by subclass. .. py:attribute:: columns :type: tuple[tuple[str, httk.store.db.codecs.ScalarKind], ...] The ``(column name suffix, scalar kind)`` pairs the codec encodes into. .. py:attribute:: encode :type: collections.abc.Callable[[Any], tuple[Any, Ellipsis]] Encode a value into one scalar per entry of ``columns``, in order. .. py:attribute:: decode :type: collections.abc.Callable[[tuple[Any, Ellipsis]], Any] Recover the exact value from the tuple produced by ``encode``. .. py:attribute:: query_suffix :type: str :value: '' Suffix of the column used for querying/indexing (normally the empty suffix). .. py:function:: register_value_codec(codec) Register ``codec`` in the value-codec registry. :param codec: The codec to register. :return: None. :raises ValueError: If the codec name or Python type is already registered. .. py:function:: known_value_codecs() Return the registered value-codec names in registration order. :return: The registered codec names. .. py:function:: codec_for(python_type) 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. :param python_type: The Python type to look up. :return: The matching codec, or ``None`` when no codec covers the type. .. py:function:: codec_named(name) Return the codec registered as ``name``. :param name: The registered codec name. :return: The matching value codec. :raises ValueError: If no codec has that name. .. py:function:: encode_fraction_exact(value) Encode a fraction in the canonical exact text format. :param value: The fraction to encode. :return: The canonical ``p/q`` text. .. py:function:: decode_fraction_exact(text) Decode canonical exact fraction text. :param text: The fraction text to parse. :return: The exact fraction. :raises ValueError: If the text is malformed. :raises ZeroDivisionError: If the denominator is zero. .. py:function:: encode_surdscalar_exact(value) The canonical :data:`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. :param value: The surd scalar to encode. :return: The canonical surd text. .. py:function:: decode_surdscalar_exact(text) Decode canonical exact surd text. :param text: The surd text to parse. :return: The exact surd scalar. :raises ValueError: If the text is malformed. :raises ZeroDivisionError: If a coefficient denominator is zero. .. py:function:: encode_fracvector_exact(value) The canonical :data:`FRACVECTOR_EXACT_FORMAT` text of a rational tensor. The tensor is flattened row-major and normalized through :meth:`~httk.core.FracVector.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. :param value: The rational tensor to encode. :return: The canonical exact tensor text. .. py:function:: decode_fracvector_exact(text, rows, cols) Parse :data:`FRACVECTOR_EXACT_FORMAT` text into a ``rows`` x ``cols`` :class:`~httk.core.FracVector`. The numerators are laid out row-major into a tensor of shape ``(rows, cols)``; their count must equal ``rows * cols``. Raises :class:`ValueError` on malformed text or a count/shape mismatch. :param text: The exact tensor text to parse. :param rows: The expected row count. :param cols: The expected column count. :return: The reconstructed rational tensor. :raises ValueError: If the text or requested shape is invalid. .. py:function:: encode_fracvector_floats(value) The elements of a rational tensor as a flat row-major tuple of nearest floats. This is the (documented approximate) companion of :func:`encode_fracvector_exact`, used to fill the per-element float query/index columns of fixed-shape fields. :param value: The rational tensor to convert. :return: The row-major floating-point values.