cadrumo.core.toml module

Canonical TOML read, freeze and render helpers.

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. render_toml() is the inverse used to present a parsed document back to a reader: its output parses to a value equal to the one it was given.

read_toml() and freeze_toml() are used by the registry source loader that parses committed registry definitions. to_str_keyed_dict() is the narrow bridge from loosely typed parsed TOML mappings into strict schema models that require string keys.

The parse is backed by the Rust rtoml parser, which is several times faster than the standard-library parser on the registry tree and returns the same native Python types for every TOML value shape (str/int/float/bool/list/dict/date/datetime/time). It does not produce 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. parse_toml() and load_toml() are the only places the parser is called; every other module reads TOML through them.

exception TomlDecodeError(message=None, *, context=None, translated_message=None)

Bases: CoreValidationError

A document is not valid TOML.

Parameters:

• message (str | None)

• context (Mapping[str, object] | None)

• translated_message (str | None)

Return type:

None

code

parse_toml(text)

Parse TOML text into its top-level table.

The table is typed as the standard-library parser typed it, so callers that index a document they authored keep doing so; read_toml() is the strictly typed boundary for committed registry input.

Raises:

TomlDecodeError – The text is not valid TOML.

Return type:

dict[str, Any]

Parameters:

text (str)

load_toml(source)

Parse a TOML document from a path or an open binary file.

Raises:

• TomlDecodeError – The document is not valid TOML.

• UnicodeDecodeError – The bytes are not UTF-8.

• OSError – The path cannot be read.

Return type:

dict[str, Any]

Parameters:

source (Path | BinaryIO)

read_toml(path, *, error_factory)

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 (TomlDecodeError).

to_str_keyed_dict(raw, *, error_factory)

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

Parameters:

• raw (Mapping[TypeVar(KeyT), 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)

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)

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])

render_toml(document, *, comments=None)

Render a parsed TOML document as TOML text that parses back to an equal value.

Nested tables become [a.b] headers and a non-empty array whose every element is a table becomes [[a.b]] blocks, so a registry table renders in the shape its source files take; every other value is written inline. Within a table, plain values precede its sub-tables because TOML binds a key to the most recent header. Sequences may be lists or the tuples freeze_toml() produces.

Parameters:

• document (Mapping[str, object]) – The value to render, as parse_toml() would return it.

• comments (Mapping[TypeAliasType, str] | None) – Comment text written above the table at each path; the empty path is the document itself. Each line of the text becomes one # comment line, so a parser drops it.

Raises:

TypeError – When a key is not a string or a value has no TOML form.

Return type:

str