Registry API

Language registry for pluralio.

This module provides the central registry that maps language codes to their corresponding LanguageRules instances. Each language module in pluralio.rules (e.g. rules.en, rules.es) builds a LanguageRules dataclass and calls register() at import time.

The registry is a plain dictionary, so custom languages can be added at runtime via register() or pluralio.register_language().

Example

>>> from pluralio.registry import supported_languages
>>> supported_languages()
['en', 'eo', 'es', 'fr', 'it', 'pt']

class pluralio.registry.LanguageRules(code: str, irregular_plurals: dict[str, str] = <factory>, irregular_singles: dict[str, str] = <factory>, plural_rules: list[tuple[~re.Pattern[str], str]] = <factory>, singular_rules: list[tuple[~re.Pattern[str], str]] = <factory>, uncountable: set[str] = <factory>)

Bases: object

Container for all pluralization/singularization rules of a language.

Warning

frozen=True prevents reassigning attributes (rules.code = "fr" raises FrozenInstanceError), but the mutable containers (dict, list, set) can still be modified in place. This is by design — the extensibility API (pluralio.add_irregular(), pluralio.add_plural(), etc.) mutates the contents of already-registered instances. Always use those functions instead of mutating containers directly.

code: str

ISO 639-1 language code (e.g. "en", "es", "fr").

irregular_plurals: dict[str, str]

Singular → plural mapping for words that do not follow regex rules. Keys and values are lowercase. Checked before regex rules during pluralization.

irregular_singles: dict[str, str]

Plural → singular mapping for words that do not follow regex rules. Keys and values are lowercase. Checked before regex rules during singularization. Typically the inverse of irregular_plurals, but may include extra entries (e.g. Spanish accent restoration).

plural_rules: list[tuple[Pattern[str], str]]

Ordered (compiled_regex, replacement) tuples applied during pluralization. First match wins.

singular_rules: list[tuple[Pattern[str], str]]

Ordered (compiled_regex, replacement) tuples applied during singularization. First match wins.

uncountable: set[str]

Lowercase invariable words — both pluralize and singularize return them unchanged. Checked first, before irregulars and regex.

pluralio.registry.get_rules(lang: str) → LanguageRules

Retrieve the rules for a given language code.

The lookup is normalized the same way as register() — get_rules(" EN ") resolves to "en".

Parameters:

lang – ISO 639-1 language code (e.g. "en", "es").

Returns:

The LanguageRules instance for the requested language.

Raises:

ValueError – If lang is not registered. The error message includes the list of supported languages.

Example

>>> from pluralio.registry import get_rules
>>> rules = get_rules("en")
>>> rules.code
'en'

pluralio.registry.register(rules: LanguageRules) → None

Register a language’s rules in the global registry.

If a language with the same code already exists, it is overwritten. The regex application cache is cleared to prevent stale results.

The code is normalized (stripped and lowercased) before registration, so LanguageRules(code=" EN ") is registered as "en". When the code needs normalization, a normalized copy of rules is stored.

Parameters:

rules – The LanguageRules instance to register.

Raises:

ValueError – If rules.code is empty or whitespace-only.

Example

>>> from pluralio.registry import LanguageRules, register
>>> state = snapshot()
>>> register(LanguageRules(code="xx"))
>>> "xx" in supported_languages()
True
>>> restore(state)

pluralio.registry.restore(state: dict[str, LanguageRules]) → None

Replace the current registry with a previously snapshotted state.

Clears the regex application cache to prevent stale results after restoration. This is critical for test isolation — conftest uses snapshot / restore around every test.

Parameters:

state – A dict previously returned by snapshot().

Example

>>> from pluralio.registry import snapshot, restore
>>> state = snapshot()
>>> # ... mutations happen ...
>>> restore(state)

pluralio.registry.snapshot() → dict[str, LanguageRules]

Return a deep copy of the current registry state.

Useful for test isolation — call restore() with the returned value to roll back any mutations made by tests.

Returns:

A deep copy of the internal _REGISTRY dict.

Example

>>> from pluralio.registry import snapshot, restore
>>> state = snapshot()
>>> # ... mutations happen ...
>>> restore(state)

pluralio.registry.supported_languages() → list[str]

Return a sorted list of all registered language codes.

Returns:

Sorted list of ISO 639-1 codes (e.g. ["en", "eo", "es", "fr", "it", "pt"]).

Example

>>> from pluralio.registry import supported_languages
>>> supported_languages()
['en', 'eo', 'es', 'fr', 'it', 'pt']