Core API

Core pluralization and singularization engine.

This module implements the main algorithm that transforms a word between its singular and plural forms. The algorithm follows a three-step priority chain for each word:

1. Uncountable check — if the word is in the language’s uncountable set, it is returned unchanged.

2. Irregular lookup — if the word appears in the irregular mapping (irregular_plurals or irregular_singles), the mapped form is returned.

3. Regex rules — the first matching regex rule in the ordered list is applied. If no rule matches, the word is returned unchanged.

Additional features handled here:

• Case preservation: the output mirrors the casing of the input (title case, all caps, lowercase).

• Hyphenated words: only the first segment is transformed (e.g. "mother-in-law" → "mothers-in-law").

• Count-aware pluralization: when count == 1 the word is returned in singular form regardless of other rules.

• Input validation: non-string inputs raise TypeError; empty or whitespace-only strings are returned as-is.

pluralio.core.pluralize(word: str, lang: str = 'en', count: int | None = None) → str

Convert a word to its plural form.

The function follows the three-step priority chain (uncountable → irregular → regex) and preserves the input casing in the output.

Parameters:

• word – The singular word to pluralize.

• lang – ISO 639-1 language code. Defaults to "en".

• count – Optional integer count. When count == 1 the word is returned unchanged (singular form). Any other value (including 0, negative numbers, and None) produces the plural form.

Returns:

The plural form of word, with original casing preserved.

Raises:

• TypeError – If word is not a string.

• ValueError – If lang is not a registered language.

Example

>>> pluralize("cat")
'cats'
>>> pluralize("box")
'boxes'
>>> pluralize("child")
'children'
>>> pluralize("gato", lang="es")
'gatos'
>>> pluralize("item", count=1)
'item'
>>> pluralize("Library")
'Libraries'
>>> pluralize("mother-in-law")
'mothers-in-law'

pluralio.core.singularize(word: str, lang: str = 'en') → str

Convert a word to its singular form.

The function follows the three-step priority chain (uncountable → irregular → regex) and preserves the input casing in the output.

Parameters:

• word – The plural word to singularize.

• lang – ISO 639-1 language code. Defaults to "en".

Returns:

The singular form of word, with original casing preserved.

Raises:

• TypeError – If word is not a string.

• ValueError – If lang is not a registered language.

Example

>>> singularize("cities")
'city'
>>> singularize("mice")
'mouse'
>>> singularize("lápices", lang="es")
'lápiz'
>>> singularize("Libraries")
'Library'
>>> singularize("mothers-in-law")
'mother-in-law'

Internal functions

pluralio.core._match_case(source: str, target: str) → str

Apply the casing pattern of source to target.

Four modes are supported:

1. All caps: if source is entirely uppercase, target is returned in uppercase.

2. Title case: if only the first character of source is uppercase and the rest are lowercase, target is capitalized on its first character.

3. Mixed case: if source has uppercase letters beyond the first character but is not all caps, each character position in target mirrors the case of the corresponding position in source. Extra characters in target default to lowercase.

4. Lowercase: otherwise target is returned unchanged.

Parameters:

• source – The original word whose casing pattern to replicate.

• target – The transformed word to re-case.

Returns:

target with the casing of source applied.

Example

>>> _match_case("Library", "libraries")
'Libraries'
>>> _match_case("LIBRARY", "libraries")
'LIBRARIES'
>>> _match_case("library", "libraries")
'libraries'
>>> _match_case("McDonald", "mcdonalds")
'McDonalds'
>>> _match_case("iPhone", "iphones")
'iPhones'

pluralio.core._apply_rules(word: str, lower: str, rules: LanguageRules, is_plural: bool) → str

Apply the three-step transformation chain to a single word.

This is the shared inner logic used by both pluralize() and singularize(). It applies regex rules and preserves the input casing in the result. Uncountable and irregular checks are performed by the caller before reaching this function.

Parameters:

• word – The original word (with original casing).

• lower – The lowercase version of word.

• rules – The LanguageRules for the target language.

• is_plural – True for pluralization rules, False for singularization rules.

Returns:

The transformed word with original casing preserved.

pluralio.core._clear_regex_cache() → None

Clear the regex application cache.

Must be called whenever language rules are modified at runtime (e.g. via add_irregular(), add_plural_rule(), etc.) to prevent stale cached results.