aeat.core._toml module

Canonical TOML read + freeze helpers shared across loaders.

Multiple committed-TOML loaders (registry definitions, the user-profile schema) need the same two operations: parse a TOML file with errors re-raised as a domain-specific exception, and recursively freeze the parsed mapping so list values become tuples. These helpers are the single source of that behaviour.

read_toml() and freeze_toml() are used by the registry loader in domain.calculations.registry._loader and the user-profile schema loader in domain.user_profile._loader. parse_toml_text() gives the same decode-error wrapping to callers that already hold a TOML payload in memory, such as the secure bucket manifest reader. to_str_keyed_dict() is the narrow bridge from loosely typed parsed TOML mappings into strict schema models that require string keys.

The parse itself is backed by rtoml (a Rust-extension TOML parser), not stdlib tomllib, per the registry-toml-parser ADR: ~2.4x faster on the registry’s ~16k-fragment tree, with output proven byte-identical to tomllib across every fragment the registry ships. Both parsers return the same native Python types for every TOML value shape (str/int/float/bool/list/dict/date/datetime/time); neither ever produces a decimal.Decimal (TOML has no native decimal type), so registry money and rate values continue to arrive as plain TOML strings, coerced to Decimal downstream by pydantic field validators exactly as before.

read_toml(path, *, error_factory)[source]

Parse a TOML file, re-raising failures via error_factory.

Parameters:

  • path (Path) – Path of the TOML file to read.

  • error_factory (Callable[[str], Exception]) – Callable that builds the domain-specific exception from a message. Invoked on decode and OS errors so each loader keeps its own error type.

Return type:

dict[str, object]

Returns:

The parsed top-level TOML mapping.

Raises:

Exception – The exception built by error_factory when the file cannot be read (OSError) or contains invalid TOML (rtoml.TomlParsingError).

parse_toml_text(text, *, error_factory)[source]

Parse an in-memory TOML string, re-raising decode failures via error_factory.

The text-input sibling to read_toml() for callers that have already loaded the bytes (e.g. through pathlib.Path.read_text(), secure-object payload decoding, or in-memory test fixtures) and need consistent error wrapping without the file-open layer.

Parameters:

  • text (str) – TOML payload to decode.

  • error_factory (Callable[[str], Exception]) – Callable that builds the domain-specific exception from a message; invoked on rtoml.TomlParsingError.

Return type:

dict[str, object]

Returns:

The parsed top-level TOML mapping.

Raises:

Exception – The exception built by error_factory when the payload is not valid TOML.

to_str_keyed_dict(raw, *, error_factory)[source]

Convert a parsed TOML mapping to a str-keyed dict, rejecting non-string keys.

Parameters:

  • raw (Mapping[object, object]) – Parsed mapping whose keys may not all be strings.

  • error_factory (Callable[[str], Exception]) – Builds the domain-specific exception raised when a key is not a str, so each loader keeps its own error type.

Return type:

dict[str, object]

Returns:

A new dict with the same items and string keys.

Raises:

Exception – The exception built by error_factory when any key is not a str.

freeze_toml_value(value)[source]

Recursively freeze one parsed TOML value, turning lists into tuples.

The TOML parser returns mutable Python lists for TOML arrays. Registry and profile-schema models use strict frozen contracts, so loader boundaries call this helper before validating nested payloads. Mappings stay mappings with their values frozen recursively; scalar TOML values are returned unchanged.

Return type:

object

Parameters:

value (object)

freeze_toml(data)[source]

Recursively freeze a parsed TOML mapping (lists become tuples).

This is the mapping-level companion to freeze_toml_value(), used after read_toml() when a committed TOML document is about to be validated as a frozen registry, category, IVA, or user-profile schema object.

Return type:

dict[str, object]

Parameters:

data (dict[str, object])