pluralio 1.0.0__py3-none-any.whl

pluralio/__init__.py

@@ -0,0 +1,360 @@
+"""pluralio — Pluralization and singularization for Python.
+
+Public API:
+    - :func:`pluralize`: Convert a word to plural form.
+    - :func:`singularize`: Convert a word to singular form.
+    - :func:`supported_languages`: List registered language codes.
+    - :func:`add_irregular`: Add an irregular word pair (both directions).
+    - :func:`add_plural`: Add only the singular→plural direction.
+    - :func:`add_singular`: Add only the plural→singular direction.
+    - :func:`add_uncountable`: Mark a word as invariable.
+    - :func:`add_plural_rule`: Insert a pluralization regex rule.
+    - :func:`add_singular_rule`: Insert a singularization regex rule.
+    - :func:`register_language`: Register a new language with its rules.
+    - :func:`is_plural`: Check if a word is in plural form.
+    - :func:`is_singular`: Check if a word is in singular form.
+    - :class:`LanguageRules`: Dataclass for custom language rules.
+    - :func:`register`: Low-level registry registration.
+    - :func:`get_rules`: Low-level registry lookup.
+
+Supported languages (built-in):
+    - English (``en``)
+    - Spanish (``es``)
+
+Example:
+    >>> import pluralio
+    >>> pluralio.pluralize("cat")
+    'cats'
+    >>> pluralio.pluralize("gato", lang="es")
+    'gatos'
+    >>> pluralio.singularize("cities")
+    'city'
+"""
+
+import re
+from importlib.metadata import PackageNotFoundError, version
+
+from pluralio import rules_en, rules_es  # noqa: F401 — triggers registration
+from pluralio.core import pluralize, singularize
+from pluralio.registry import (
+    LanguageRules,
+    get_rules,
+    register,
+    supported_languages,
+)
+
+try:
+    __version__ = version("pluralio")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+"""Package version string (read from installed package metadata)."""
+
+__all__ = [
+    "pluralize",
+    "singularize",
+    "supported_languages",
+    "LanguageRules",
+    "register",
+    "get_rules",
+    "add_irregular",
+    "add_plural",
+    "add_singular",
+    "add_uncountable",
+    "add_plural_rule",
+    "add_singular_rule",
+    "register_language",
+    "is_plural",
+    "is_singular",
+    "__version__",
+]
+
+
+def add_irregular(singular: str, plural: str, lang: str = "en") -> None:
+    """Add an irregular word pair for both pluralize and singularize.
+
+    This registers the word in both ``irregular_plurals``
+    (singular → plural) and ``irregular_singles`` (plural → singular),
+    so that both :func:`pluralize` and :func:`singularize` use the
+    mapping. The entries are stored in lowercase for case-insensitive
+    matching.
+
+    Args:
+        singular: The singular form of the word.
+        plural: The plural form of the word.
+        lang: Language code to register the pair in. Defaults to ``"en"``.
+
+    Example:
+        >>> add_irregular("person", "people")
+        >>> pluralize("person")
+        'people'
+        >>> singularize("people")
+        'person'
+    """
+    rules = get_rules(lang)
+    rules.irregular_plurals[singular.lower()] = plural.lower()
+    rules.irregular_singles[plural.lower()] = singular.lower()
+
+
+def add_plural(singular: str, plural: str, lang: str = "en") -> None:
+    """Add only the singular→plural direction for an irregular word.
+
+    Unlike :func:`add_irregular`, this only affects :func:`pluralize`.
+    :func:`singularize` will not know about the inverse mapping.
+
+    This is useful when the plural→singular direction follows a
+    different rule or needs a separate entry (e.g. Spanish accent
+    restoration).
+
+    Args:
+        singular: The singular form of the word.
+        plural: The plural form of the word.
+        lang: Language code. Defaults to ``"en"``.
+
+    Example:
+        >>> add_plural("joven", "jóvenes", lang="es")
+        >>> pluralize("joven", lang="es")
+        'jóvenes'
+    """
+    rules = get_rules(lang)
+    rules.irregular_plurals[singular.lower()] = plural.lower()
+
+
+def add_singular(plural: str, singular: str, lang: str = "en") -> None:
+    """Add only the plural→singular direction for an irregular word.
+
+    Unlike :func:`add_irregular`, this only affects :func:`singularize`.
+    :func:`pluralize` will not know about the forward mapping.
+
+    This is useful for Spanish accent restoration where the plural
+    form has a predictable ending but the singular requires an accent
+    that the regex rules cannot infer.
+
+    Args:
+        plural: The plural form of the word.
+        singular: The singular form of the word.
+        lang: Language code. Defaults to ``"en"``.
+
+    Example:
+        >>> add_singular("alemanes", "alemán", lang="es")
+        >>> singularize("alemanes", lang="es")
+        'alemán'
+    """
+    rules = get_rules(lang)
+    rules.irregular_singles[plural.lower()] = singular.lower()
+
+
+def add_uncountable(word: str, lang: str = "en") -> None:
+    """Mark a word as uncountable (invariable).
+
+    Uncountable words are returned unchanged by both :func:`pluralize`
+    and :func:`singularize`. They are checked **before** irregulars
+    and regex rules, so they take highest priority.
+
+    Args:
+        word: The word to mark as uncountable.
+        lang: Language code. Defaults to ``"en"``.
+
+    Example:
+        >>> add_uncountable("data")
+        >>> pluralize("data")
+        'data'
+        >>> singularize("data")
+        'data'
+    """
+    rules = get_rules(lang)
+    rules.uncountable.add(word.lower())
+
+
+def add_plural_rule(pattern: str, replacement: str, lang: str = "en") -> None:
+    """Insert a pluralization regex rule at the top (highest priority).
+
+    Rules are checked in order, and the first match wins. By inserting
+    at position 0, the new rule takes priority over all existing rules.
+
+    Args:
+        pattern: Regular expression pattern to match (string, will be
+            compiled internally).
+        replacement: Replacement string for ``re.sub``.
+        lang: Language code. Defaults to ``"en"``.
+
+    Example:
+        >>> add_plural_rule(r"us$", "i")
+        >>> pluralize("cactus")
+        'cacti'
+    """
+    rules = get_rules(lang)
+    rules.plural_rules.insert(0, (re.compile(pattern), replacement))
+
+
+def add_singular_rule(pattern: str, replacement: str, lang: str = "en") -> None:
+    """Insert a singularization regex rule at the top (highest priority).
+
+    Rules are checked in order, and the first match wins. By inserting
+    at position 0, the new rule takes priority over all existing rules.
+
+    Args:
+        pattern: Regular expression pattern to match (string, will be
+            compiled internally).
+        replacement: Replacement string for ``re.sub``.
+        lang: Language code. Defaults to ``"en"``.
+
+    Example:
+        >>> add_singular_rule(r"i$", "us")
+        >>> singularize("cacti")
+        'cactus'
+    """
+    rules = get_rules(lang)
+    rules.singular_rules.insert(0, (re.compile(pattern), replacement))
+
+
+def register_language(
+    lang: str,
+    *,
+    plural_rules: list[tuple[str, str]] | None = None,
+    singular_rules: list[tuple[str, str]] | None = None,
+    irregular_plurals: dict[str, str] | None = None,
+    irregular_singles: dict[str, str] | None = None,
+    uncountable: set[str] | None = None,
+) -> None:
+    """Register a new language with its pluralization rules.
+
+    This is the high-level API for adding a completely new language.
+    It compiles the regex patterns, normalizes keys to lowercase,
+    auto-generates inverse irregular mappings, and registers the
+    resulting :class:`LanguageRules` in the global registry.
+
+    If ``plural_rules`` is omitted, a default rule of ``(r"$", "s")``
+    is used (append ``s``).
+    If ``singular_rules`` is omitted, a default rule of ``(r"s$", "")``
+    is used (strip trailing ``s``).
+
+    For every entry in ``irregular_plurals``, the inverse is
+    automatically added to ``irregular_singles`` unless an explicit
+    entry already exists.
+
+    Args:
+        lang: ISO 639-1 language code for the new language.
+        plural_rules: List of ``(pattern, replacement)`` string tuples
+            for pluralization. Checked in order; first match wins.
+        singular_rules: List of ``(pattern, replacement)`` string tuples
+            for singularization. Checked in order; first match wins.
+        irregular_plurals: Mapping of singular → plural for irregular
+            words. Keys and values are normalized to lowercase.
+        irregular_singles: Mapping of plural → singular for irregular
+            words. Keys and values are normalized to lowercase.
+            Auto-populated from ``irregular_plurals`` where possible.
+        uncountable: Set of invariable words. Normalized to lowercase.
+
+    Example:
+        >>> register_language(
+        ...     "fr",
+        ...     plural_rules=[(r"$", "s")],
+        ...     singular_rules=[(r"s$", "")],
+        ...     irregular_plurals={"cheval": "chevaux"},
+        ...     uncountable={"information"},
+        ... )
+        >>> pluralize("chat", lang="fr")
+        'chats'
+        >>> pluralize("cheval", lang="fr")
+        'chevaux'
+        >>> singularize("chevaux", lang="fr")
+        'cheval'
+        >>> pluralize("information", lang="fr")
+        'information'
+    """
+    plurals = {k.lower(): v.lower() for k, v in (irregular_plurals or {}).items()}
+    singles = {k.lower(): v.lower() for k, v in (irregular_singles or {}).items()}
+    for singular, plural in plurals.items():
+        singles.setdefault(plural, singular)
+
+    compiled_plural = [(re.compile(p), r) for p, r in (plural_rules or [(r"$", "s")])]
+    compiled_singular = [(re.compile(p), r) for p, r in (singular_rules or [(r"s$", "")])]
+
+    register(LanguageRules(
+        code=lang,
+        irregular_plurals=plurals,
+        irregular_singles=singles,
+        plural_rules=compiled_plural,
+        singular_rules=compiled_singular,
+        uncountable={w.lower() for w in (uncountable or set())},
+    ))
+
+
+def is_plural(word: str, lang: str = "en") -> bool:
+    """Check if a word is in its plural form.
+
+    A word is considered plural if singularizing it produces a
+    different word. Uncountable words are neither plural nor
+    singular — they return ``False`` for both checks.
+
+    Args:
+        word: The word to check.
+        lang: ISO 639-1 language code. Defaults to ``"en"``.
+
+    Returns:
+        ``True`` if the word is in plural form, ``False`` otherwise.
+
+    Raises:
+        TypeError: If ``word`` is not a string.
+        ValueError: If ``lang`` is not a registered language.
+
+    Example:
+        >>> is_plural("cats")
+        True
+        >>> is_plural("cat")
+        False
+        >>> is_plural("sheep")
+        False
+        >>> is_plural("gatos", lang="es")
+        True
+    """
+    if not isinstance(word, str):
+        raise TypeError(f"word must be str, got {type(word).__name__}")
+    stripped = word.strip()
+    if not stripped:
+        return False
+    rules = get_rules(lang)
+    lower = stripped.lower()
+    if lower in rules.uncountable:
+        return False
+    return singularize(stripped, lang=lang).lower() != lower
+
+
+def is_singular(word: str, lang: str = "en") -> bool:
+    """Check if a word is in its singular form.
+
+    A word is considered singular if it is not plural and not
+    uncountable. Uncountable words are neither plural nor
+    singular — they return ``False`` for both checks.
+
+    Args:
+        word: The word to check.
+        lang: ISO 639-1 language code. Defaults to ``"en"``.
+
+    Returns:
+        ``True`` if the word is in singular form, ``False`` otherwise.
+
+    Raises:
+        TypeError: If ``word`` is not a string.
+        ValueError: If ``lang`` is not a registered language.
+
+    Example:
+        >>> is_singular("cat")
+        True
+        >>> is_singular("cats")
+        False
+        >>> is_singular("sheep")
+        False
+        >>> is_singular("gato", lang="es")
+        True
+    """
+    if not isinstance(word, str):
+        raise TypeError(f"word must be str, got {type(word).__name__}")
+    stripped = word.strip()
+    if not stripped:
+        return False
+    rules = get_rules(lang)
+    lower = stripped.lower()
+    if lower in rules.uncountable:
+        return False
+    return singularize(stripped, lang=lang).lower() == lower

pluralio/core.py

@@ -0,0 +1,223 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pluralio.registry import LanguageRules, get_rules
+
+
+def _match_case(source: str, target: str) -> str:
+    """Apply the casing pattern of ``source`` to ``target``.
+
+    Three modes are supported:
+    - **All caps**: if ``source`` is entirely uppercase, ``target``
+      is returned in uppercase.
+    - **Title case**: if only the first character of ``source`` is
+      uppercase, ``target`` is capitalized on its first character.
+    - **Lowercase**: otherwise ``target`` is returned unchanged.
+
+    Args:
+        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'
+    """
+    if source.isupper():
+        return target.upper()
+    if source[0].isupper():
+        return target[0].upper() + target[1:]
+    return target
+
+
+def _apply_rules(
+    word: str,
+    rules: LanguageRules,
+    irregulars: dict[str, str],
+    rule_list: list[tuple[re.Pattern[str], str]],
+) -> str:
+    """Apply the three-step transformation chain to a single word.
+
+    This is the shared inner logic used by both :func:`pluralize` and
+    :func:`singularize`. It checks uncountables first, then irregulars,
+    then regex rules, preserving the input casing in the result.
+
+    Args:
+        word: The word to transform (already stripped, no hyphens).
+        rules: The :class:`LanguageRules` for the target language.
+        irregulars: Either ``irregular_plurals`` or ``irregular_singles``
+            from the language rules, depending on direction.
+        rule_list: Either ``plural_rules`` or ``singular_rules`` from
+            the language rules, depending on direction.
+
+    Returns:
+        The transformed word with original casing preserved.
+    """
+    lower = word.lower()
+    if lower in rules.uncountable:
+        return word
+    if lower in irregulars:
+        return _match_case(word, irregulars[lower])
+    for pattern, replacement in rule_list:
+        if pattern.search(lower):
+            return _match_case(word, pattern.sub(replacement, lower, count=1))
+    return word
+
+
+def _pluralize_hyphenated(word: str, lang: str, count: int | None) -> str:
+    """Pluralize only the first segment of a hyphenated word.
+
+    Args:
+        word: The hyphenated word (e.g. ``"mother-in-law"``).
+        lang: Language code to pass through.
+        count: Count value to pass through for count-aware behavior.
+
+    Returns:
+        The word with its first segment pluralized
+        (e.g. ``"mothers-in-law"``).
+    """
+    parts = word.split("-")
+    parts[0] = pluralize(parts[0], lang=lang, count=count)
+    return "-".join(parts)
+
+
+def _singularize_hyphenated(word: str, lang: str) -> str:
+    """Singularize only the first segment of a hyphenated word.
+
+    Args:
+        word: The hyphenated word (e.g. ``"mothers-in-law"``).
+        lang: Language code to pass through.
+
+    Returns:
+        The word with its first segment singularized
+        (e.g. ``"mother-in-law"``).
+    """
+    parts = word.split("-")
+    parts[0] = singularize(parts[0], lang=lang)
+    return "-".join(parts)
+
+
+def 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.
+
+    Args:
+        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'
+    """
+    if not isinstance(word, str):
+        raise TypeError(f"word must be str, got {type(word).__name__}")
+    stripped = word.strip()
+    if not stripped:
+        return word
+    if count is not None and count == 1:
+        return word
+    rules = get_rules(lang)
+    if "-" in stripped:
+        return _pluralize_hyphenated(stripped, lang, count)
+    return _apply_rules(stripped, rules, rules.irregular_plurals, rules.plural_rules)
+
+
+def 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.
+
+    Args:
+        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'
+    """
+    if not isinstance(word, str):
+        raise TypeError(f"word must be str, got {type(word).__name__}")
+    stripped = word.strip()
+    if not stripped:
+        return word
+    rules = get_rules(lang)
+    if "-" in stripped:
+        return _singularize_hyphenated(stripped, lang)
+    return _apply_rules(stripped, rules, rules.irregular_singles, rules.singular_rules)