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.

code

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

Type:

str

irregular_plurals

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

Type:

dict[str, str]

irregular_singles

Mapping of plural → singular 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).

Type:

dict[str, str]

plural_rules

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

Type:

list[tuple[re.Pattern[str], str]]

singular_rules

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

Type:

list[tuple[re.Pattern[str], str]]

uncountable

Set of lowercase words that are invariable — both pluralize and singularize return them unchanged. Checked first, before irregulars and regex.

Type:

set[str]

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

irregular_plurals: dict[str, str]

irregular_singles: dict[str, str]

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

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

uncountable: set[str]

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

Retrieve the rules for a given language code.

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.

Parameters:

rules – The LanguageRules instance to register.

Raises:

ValueError – If rules.code is empty.

Example

>>> from pluralio.registry import LanguageRules, register
>>> register(LanguageRules(code="xx"))

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