cadrumo.domain.iva.country_vocabulary module

Published IVA country-vocabulary indexes.

Private implementation for the canonical establishment resolvers.

normalise_printed_country_name(printed)

Return the form a printed country name is matched under.

Three normalisations and no more. Case is folded because a document sets its address block in whatever typography it likes. Runs of whitespace collapse to one because a name broken across an address line arrives with the break in it. Combining accents are folded away because invoicing systems routinely print ASCII-only, so "Mexico" and "México" are the same printed name.

Punctuation is deliberately NOT stripped: "EE.UU." is carried in the vocabulary with its stops, and squeezing punctuation generally would start matching strings that are not names.

Return type:

str

Parameters:

printed (str)

country_codes_by_printed_name(*, operation)

Return every vocabulary name, normalised, mapped to its alpha-2 code.

Read from the published runtime authority rather than written here, so this resolver shares the validated catalogue identity used by other consumers.

Raises:

IvaCatalogueError – When the bundled vocabulary cannot be read, names a malformed code, or maps one normalised name to two different countries. The last is the check that makes accent folding safe: folding is only sound while no two distinct countries fold together, and this refuses the table rather than resolving the collision to whichever record happened to be read last.

Return type:

dict[str, str]

Parameters:

operation (PinnedAuthorityOperation)

country_codes_by_alpha3(*, operation)

Return every vocabulary record’s alpha-3 code mapped to its alpha-2 code.

Read from the same published country projection as the printed names, and deliberately so: the alpha-3 form is a second way of STATING the country that record already names, so recording it anywhere else would put two authorities on one country.

Raises:

IvaCatalogueError – When the bundled vocabulary cannot be read or a record breaks the one-code-one-country invariant.

Return type:

dict[str, str]

Parameters:

operation (PinnedAuthorityOperation)