cadrumo.core.parsing.codes module

Canonical normalisers for the inbound ISO code tokens ledger records carry.

Currency (ISO 4217) and source jurisdiction (ISO 3166-1 alpha-2) both arrive as free text from bank exports, operator input, and CLI options, and both are persisted on ledger records. Each previously carried a per-boundary copy of its shape check, so the same token could be accepted at one boundary and refused at the next.

These are pure functions at the core layer. They raise the registered CoreValidationError ancestry, and a Pydantic validator delegating here translates that failure to ValueError at its narrow boundary. Each caller re-raises its own domain error to keep operator diagnostics boundary-specific.

normalise_iso_4217_currency(value)

Normalise a raw currency token to its uppercase ISO 4217 code.

Trims surrounding whitespace and uppercases before the shape check, so a padded or lowercase source cell (" usd ") normalises to "USD" rather than being refused for its padding. Callers that validate through Pydantic must run this as a mode="before" validator: a bare min_length / max_length field constraint fires on the padding first and never reaches the normaliser.

Parameters:

value (object) – Raw currency token from a bank export, OFX statement header, operator input, or persisted payload.

Return type:

str

Returns:

The three-letter uppercase ISO 4217 code.

Raises:

CoreValidationError – The token is not exactly three alphabetic characters once trimmed.

normalise_iso_3166_alpha2_jurisdiction(value)

Validate a source-jurisdiction token as an ISO 3166-1 alpha-2 code.

Trims surrounding whitespace, then requires exactly two alphabetic characters that are already uppercase. Unlike normalise_iso_4217_currency() this deliberately refuses a lowercase token rather than folding it: the jurisdiction axis selects the regulatory-source treatment of a ledger row (Spanish-source versus foreign-source), so a caller that supplies "es" is told to declare the canonical code rather than having one guessed for it.

Parameters:

value (str | None) – Raw jurisdiction token, or None when the record explicitly declares the jurisdiction unknown.

Return type:

str | None

Returns:

The trimmed uppercase alpha-2 code, or None when value is None.

Raises:

CoreValidationError – The token is not exactly two uppercase alphabetic characters once trimmed.