pluralio 2.1.2__tar.gz → 2.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. {pluralio-2.1.2 → pluralio-2.3.0}/.github/ISSUE_TEMPLATE/bug_report.md +1 -1
  2. pluralio-2.3.0/.github/workflows/docs.yml +46 -0
  3. {pluralio-2.1.2 → pluralio-2.3.0}/.gitignore +2 -1
  4. {pluralio-2.1.2 → pluralio-2.3.0}/CHANGELOG.md +65 -0
  5. {pluralio-2.1.2 → pluralio-2.3.0}/CONTRIBUTING.md +7 -1
  6. {pluralio-2.1.2 → pluralio-2.3.0}/PKG-INFO +104 -31
  7. {pluralio-2.1.2 → pluralio-2.3.0}/README.md +95 -28
  8. {pluralio-2.1.2 → pluralio-2.3.0}/SECURITY.md +2 -2
  9. pluralio-2.3.0/docs/api/core.rst +15 -0
  10. pluralio-2.3.0/docs/api/en.rst +6 -0
  11. pluralio-2.3.0/docs/api/eo.rst +6 -0
  12. pluralio-2.3.0/docs/api/es.rst +6 -0
  13. pluralio-2.3.0/docs/api/extensibility.rst +85 -0
  14. pluralio-2.3.0/docs/api/fr.rst +6 -0
  15. pluralio-2.3.0/docs/api/it.rst +6 -0
  16. pluralio-2.3.0/docs/api/pt.rst +6 -0
  17. pluralio-2.3.0/docs/api/registry.rst +6 -0
  18. pluralio-2.3.0/docs/api/rules.rst +20 -0
  19. pluralio-2.3.0/docs/api/utils.rst +7 -0
  20. pluralio-2.3.0/docs/changelog.rst +5 -0
  21. pluralio-2.3.0/docs/conf.py +74 -0
  22. pluralio-2.3.0/docs/cookbook.rst +199 -0
  23. pluralio-2.3.0/docs/index.rst +84 -0
  24. pluralio-2.3.0/docs/languages.rst +125 -0
  25. pluralio-2.3.0/docs/usage.rst +99 -0
  26. {pluralio-2.1.2 → pluralio-2.3.0}/pluralio/__init__.py +19 -7
  27. {pluralio-2.1.2 → pluralio-2.3.0}/pluralio/core.py +22 -17
  28. pluralio-2.3.0/pluralio/py.typed +0 -0
  29. {pluralio-2.1.2 → pluralio-2.3.0}/pluralio/registry.py +48 -24
  30. {pluralio-2.1.2 → pluralio-2.3.0}/pluralio/rules/__init__.py +1 -1
  31. {pluralio-2.1.2 → pluralio-2.3.0}/pluralio/rules/en.py +0 -2
  32. {pluralio-2.1.2 → pluralio-2.3.0}/pluralio/rules/es.py +1 -2
  33. {pluralio-2.1.2 → pluralio-2.3.0}/pluralio/rules/fr.py +26 -8
  34. {pluralio-2.1.2 → pluralio-2.3.0}/pluralio/rules/it.py +25 -15
  35. {pluralio-2.1.2 → pluralio-2.3.0}/pluralio/rules/pt.py +12 -3
  36. pluralio-2.3.0/pluralio/utils.py +172 -0
  37. {pluralio-2.1.2 → pluralio-2.3.0}/pyproject.toml +13 -2
  38. pluralio-2.3.0/tests/__init__.py +0 -0
  39. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_core.py +18 -0
  40. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_cross_edge_cases.py +2 -2
  41. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_fr_edge_cases.py +3 -0
  42. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_fr_plurals.py +10 -0
  43. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_it_plurals.py +33 -6
  44. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_pt_plurals.py +6 -0
  45. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_pt_singles.py +3 -0
  46. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_registry.py +9 -0
  47. pluralio-2.3.0/tests/test_utils.py +369 -0
  48. pluralio-2.3.0/tests/test_version.py +44 -0
  49. {pluralio-2.1.2 → pluralio-2.3.0}/.github/ISSUE_TEMPLATE/feature_request.md +0 -0
  50. {pluralio-2.1.2 → pluralio-2.3.0}/.github/pull_request_template.md +0 -0
  51. {pluralio-2.1.2 → pluralio-2.3.0}/.github/workflows/ci.yml +0 -0
  52. {pluralio-2.1.2 → pluralio-2.3.0}/.github/workflows/release.yml +0 -0
  53. {pluralio-2.1.2 → pluralio-2.3.0}/CODE_OF_CONDUCT.md +0 -0
  54. {pluralio-2.1.2 → pluralio-2.3.0}/LICENSE +0 -0
  55. /pluralio-2.1.2/pluralio/py.typed → /pluralio-2.3.0/docs/_static/.gitkeep +0 -0
  56. /pluralio-2.1.2/tests/__init__.py → /pluralio-2.3.0/docs/_templates/.gitkeep +0 -0
  57. {pluralio-2.1.2 → pluralio-2.3.0}/pluralio/rules/eo.py +0 -0
  58. {pluralio-2.1.2 → pluralio-2.3.0}/tests/conftest.py +0 -0
  59. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_en_edge_cases.py +0 -0
  60. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_en_plurals.py +0 -0
  61. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_en_singles.py +0 -0
  62. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_eo_plurals.py +0 -0
  63. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_eo_singles.py +0 -0
  64. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_es_edge_cases.py +0 -0
  65. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_es_plurals.py +0 -0
  66. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_es_singles.py +0 -0
  67. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_fr_singles.py +0 -0
  68. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_inspect.py +0 -0
  69. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_it_edge_cases.py +0 -0
  70. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_it_singles.py +0 -0
  71. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_property.py +0 -0
  72. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_pt_edge_cases.py +0 -0
  73. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_registry_isolation.py +0 -0
  74. {pluralio-2.1.2 → pluralio-2.3.0}/tests/test_round_trip.py +0 -0
@@ -28,7 +28,7 @@ What actually happened.
28
28
 
29
29
  ## Environment
30
30
 
31
- - **pluralio version**: [e.g. 0.1.0]
31
+ - **pluralio version**: [e.g. 2.3.0]
32
32
  - **Python version**: [e.g. 3.12]
33
33
  - **OS**: [e.g. Ubuntu 24.04, Windows 11, macOS 14]
34
34
 
@@ -0,0 +1,46 @@
1
+ name: docs
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ workflow_dispatch:
7
+
8
+ permissions:
9
+ contents: read
10
+ pages: write
11
+ id-token: write
12
+
13
+ concurrency:
14
+ group: pages
15
+ cancel-in-progress: true
16
+
17
+ jobs:
18
+ build:
19
+ runs-on: ubuntu-latest
20
+ steps:
21
+ - uses: actions/checkout@v4
22
+ - uses: actions/setup-python@v5
23
+ with:
24
+ python-version: "3.13"
25
+
26
+ - name: Install dependencies
27
+ run: pip install -e ".[docs]"
28
+
29
+ - name: Build Sphinx docs
30
+ run: python -m sphinx -b html docs docs/_build/html
31
+
32
+ - name: Upload artifact
33
+ uses: actions/upload-pages-artifact@v3
34
+ with:
35
+ path: docs/_build/html
36
+
37
+ deploy:
38
+ needs: build
39
+ runs-on: ubuntu-latest
40
+ environment:
41
+ name: github-pages
42
+ url: ${{ steps.deployment.outputs.page_url }}
43
+ steps:
44
+ - name: Deploy to GitHub Pages
45
+ id: deployment
46
+ uses: actions/deploy-pages@v4
@@ -15,4 +15,5 @@ venv/
15
15
  .coverage
16
16
  htmlcov/
17
17
  .hypothesis/
18
- ref/
18
+ ref/
19
+ docs/_build/
@@ -2,6 +2,39 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [2.3.0] - 2026-10-06
6
+
7
+ ### Fixed
8
+
9
+ - `register()` now normalizes language codes (`strip` + lowercase), so `LanguageRules(code=" xx ")` registers as `"xx"`; `get_rules()` applies the same normalization, making `lang=" EN "` work everywhere
10
+ - `pluralize()` / `singularize()` / `is_plural()` / `is_singular()` now validate `lang` even for empty words (documented `ValueError`)
11
+ - Regex rules that produce an empty string are now honored instead of being silently discarded (consistent with `add_irregular("x", "")`)
12
+ - `count="1"` (string) now returns the singular form, consistent with `template()`'s `int(str(...))` coercion
13
+ - `ordinal()` raises `ValueError` for non-integral floats instead of silently truncating (`3.7` was `"3rd"`)
14
+ - French: accentless `-aux`/`-eux` singulars (`emaux`, `regaux`, …) no longer leak into `irregular_plurals` — `pluralize("email")` now correctly returns `"emails"`; `regal`/`recital` follow the `-als` exceptions
15
+ - French: invariable verb+noun compounds (`porte-monnaie`, `porte-avions`, `brise-glace`, …) and the `vice-` prefix in hyphenated compounds
16
+ - Italian: `sabato`, `domenica`, months, and seasons are no longer treated as invariable (`sabati`, `domeniche`, `estati`, …) with correct singularization round-trips
17
+ - Portuguese: added `n$` → `ns` rule (`wagon` → `wagons`) and irregulars for accented `-n` words (`hífen` → `hifens`, `abdómen` → `abdomens`, `pólen`, `gérmen`, `líquen`)
18
+
19
+ ### Changed
20
+
21
+ - `LanguageRules` attributes moved to PEP 224 docstrings, fixing duplicate object description warnings in the Sphinx build
22
+ - `docs/conf.py` reads `release` from the package version instead of a hardcoded string
23
+ - `doctest_global_setup` now imports the public API and restores a pristine registry snapshot per document — `sphinx -b doctest` runs all 123 docstring examples cleanly
24
+ - `SECURITY.md` supported versions updated to `2.x`
25
+
26
+ ## [2.2.0] - 2025-07-13
27
+
28
+ ### Added
29
+
30
+ - `join()` — join words into a natural-language list with configurable conjunction and separators
31
+ - `ordinal()` — convert a number to its ordinal string representation (1 → "1st", 2 → "2nd", 11 → "11th")
32
+ - `template()` — interpolate pluralize/singularize into string templates with count-aware support
33
+ - `pluralio.utils` module with full docstrings and type hints
34
+ - 90 tests covering all utility functions, including property-based tests with hypothesis
35
+ - Sphinx documentation page for utility functions
36
+ - Cookbook recipes for join, ordinal, and template
37
+
5
38
  ## [2.1.2] - 2025-07-13
6
39
 
7
40
  ### Fixed
@@ -435,3 +468,35 @@
435
468
  - CI workflow (lint + type check + test on Python 3.10–3.13)
436
469
  - Release workflow (trusted publishing to PyPI)
437
470
  - 95% coverage requirement enforced in CI
471
+
472
+ [Unreleased]: https://github.com/MathiasPaulenko/pluralio/compare/v2.3.0...HEAD
473
+ [2.3.0]: https://github.com/MathiasPaulenko/pluralio/compare/v2.2.0...v2.3.0
474
+ [2.2.0]: https://github.com/MathiasPaulenko/pluralio/compare/v2.1.2...v2.2.0
475
+ [2.1.2]: https://github.com/MathiasPaulenko/pluralio/compare/v2.1.1...v2.1.2
476
+ [2.1.1]: https://github.com/MathiasPaulenko/pluralio/compare/v2.1.0...v2.1.1
477
+ [2.1.0]: https://github.com/MathiasPaulenko/pluralio/compare/v2.0.2...v2.1.0
478
+ [2.0.2]: https://github.com/MathiasPaulenko/pluralio/compare/v2.0.1...v2.0.2
479
+ [2.0.1]: https://github.com/MathiasPaulenko/pluralio/compare/v2.0.0...v2.0.1
480
+ [2.0.0]: https://github.com/MathiasPaulenko/pluralio/compare/v1.8.3...v2.0.0
481
+ [1.8.3]: https://github.com/MathiasPaulenko/pluralio/compare/v1.8.2...v1.8.3
482
+ [1.8.2]: https://github.com/MathiasPaulenko/pluralio/compare/v1.8.1...v1.8.2
483
+ [1.8.1]: https://github.com/MathiasPaulenko/pluralio/compare/v1.8.0...v1.8.1
484
+ [1.8.0]: https://github.com/MathiasPaulenko/pluralio/compare/v1.7.2...v1.8.0
485
+ [1.7.2]: https://github.com/MathiasPaulenko/pluralio/compare/v1.7.1...v1.7.2
486
+ [1.7.1]: https://github.com/MathiasPaulenko/pluralio/compare/v1.7.0...v1.7.1
487
+ [1.7.0]: https://github.com/MathiasPaulenko/pluralio/compare/v1.6.2...v1.7.0
488
+ [1.6.2]: https://github.com/MathiasPaulenko/pluralio/compare/v1.6.1...v1.6.2
489
+ [1.6.1]: https://github.com/MathiasPaulenko/pluralio/compare/v1.6.0...v1.6.1
490
+ [1.6.0]: https://github.com/MathiasPaulenko/pluralio/compare/v1.5.5...v1.6.0
491
+ [1.5.5]: https://github.com/MathiasPaulenko/pluralio/compare/v1.5.4...v1.5.5
492
+ [1.5.4]: https://github.com/MathiasPaulenko/pluralio/compare/v1.5.3...v1.5.4
493
+ [1.5.3]: https://github.com/MathiasPaulenko/pluralio/compare/v1.5.2...v1.5.3
494
+ [1.5.2]: https://github.com/MathiasPaulenko/pluralio/compare/v1.5.1...v1.5.2
495
+ [1.5.1]: https://github.com/MathiasPaulenko/pluralio/compare/v1.5.0...v1.5.1
496
+ [1.5.0]: https://github.com/MathiasPaulenko/pluralio/compare/v1.4.2...v1.5.0
497
+ [1.4.2]: https://github.com/MathiasPaulenko/pluralio/compare/v1.4.1...v1.4.2
498
+ [1.4.1]: https://github.com/MathiasPaulenko/pluralio/compare/v1.4.0...v1.4.1
499
+ [1.4.0]: https://github.com/MathiasPaulenko/pluralio/compare/v1.3.0...v1.4.0
500
+ [1.3.0]: https://github.com/MathiasPaulenko/pluralio/compare/v1.2.0...v1.3.0
501
+ [1.2.0]: https://github.com/MathiasPaulenko/pluralio/compare/v0.1.0...v1.2.0
502
+ [0.1.0]: https://github.com/MathiasPaulenko/pluralio/releases/tag/v0.1.0
@@ -35,9 +35,11 @@ pluralio/
35
35
  │ ├── __init__.py # Public API + extensibility functions
36
36
  │ ├── core.py # pluralize(), singularize(), _match_case(), hyphens
37
37
  │ ├── registry.py # LanguageRules dataclass, register(), get_rules()
38
+ │ ├── utils.py # join(), ordinal(), template()
38
39
  │ ├── rules/ # Language rule modules (subpackage)
39
40
  │ │ ├── __init__.py # Imports all modules to trigger registration
40
41
  │ │ ├── en.py # English rules
42
+ │ │ ├── eo.py # Esperanto rules
41
43
  │ │ ├── es.py # Spanish rules
42
44
  │ │ ├── fr.py # French rules
43
45
  │ │ ├── it.py # Italian rules
@@ -52,8 +54,12 @@ pluralio/
52
54
  │ ├── test_property.py
53
55
  │ ├── test_round_trip.py
54
56
  │ ├── test_inspect.py
57
+ │ ├── test_utils.py
58
+ │ ├── test_version.py
55
59
  │ ├── test_en_plurals.py
56
60
  │ ├── test_en_singles.py
61
+ │ ├── test_eo_plurals.py
62
+ │ ├── test_eo_singles.py
57
63
  │ ├── test_es_plurals.py
58
64
  │ ├── test_es_singles.py
59
65
  │ ├── test_fr_plurals.py
@@ -68,7 +74,7 @@ pluralio/
68
74
  │ ├── test_fr_edge_cases.py
69
75
  │ ├── test_it_edge_cases.py
70
76
  │ └── test_pt_edge_cases.py
71
- ├── ref/ # Design docs, rules reference, development plan
77
+ ├── docs/ # Sphinx documentation
72
78
  ├── .github/workflows/ # CI + release workflows
73
79
  ├── pyproject.toml
74
80
  ├── CHANGELOG.md
@@ -1,11 +1,12 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: pluralio
3
- Version: 2.1.2
4
- Summary: Pluralization and singularization for Python — EN/ES/PT/FR/IT/EO, zero deps, type-safe
3
+ Version: 2.3.0
4
+ Summary: Pluralization and singularization for Python — 6 languages (EN/ES/PT/FR/IT/EO), zero deps, type-safe, 100% test coverage
5
5
  Project-URL: Homepage, https://github.com/MathiasPaulenko/pluralio
6
6
  Project-URL: Repository, https://github.com/MathiasPaulenko/pluralio
7
7
  Project-URL: Bug Tracker, https://github.com/MathiasPaulenko/pluralio/issues
8
8
  Project-URL: Changelog, https://github.com/MathiasPaulenko/pluralio/blob/main/CHANGELOG.md
9
+ Project-URL: Documentation, https://mathiaspaulenko.github.io/pluralio/
9
10
  Author-email: Mathias Paulenko <mathias.paulenko@outlook.com>
10
11
  License: MIT
11
12
  License-File: LICENSE
@@ -18,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
18
19
  Classifier: Programming Language :: Python :: 3.11
19
20
  Classifier: Programming Language :: Python :: 3.12
20
21
  Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
21
23
  Classifier: Topic :: Software Development :: Libraries :: Python Modules
22
24
  Classifier: Typing :: Typed
23
25
  Requires-Python: >=3.10
@@ -28,6 +30,10 @@ Requires-Dist: mypy>=1.10; extra == 'dev'
28
30
  Requires-Dist: pytest-cov>=5.0; extra == 'dev'
29
31
  Requires-Dist: pytest>=8.0; extra == 'dev'
30
32
  Requires-Dist: ruff>=0.5; extra == 'dev'
33
+ Provides-Extra: docs
34
+ Requires-Dist: furo>=2024.0; extra == 'docs'
35
+ Requires-Dist: myst-parser>=3.0; extra == 'docs'
36
+ Requires-Dist: sphinx>=7.0; extra == 'docs'
31
37
  Description-Content-Type: text/markdown
32
38
 
33
39
  <div align="center">
@@ -36,16 +42,17 @@ Description-Content-Type: text/markdown
36
42
 
37
43
  **Pluralization and singularization for Python**
38
44
 
39
- English · Spanish · Portuguese · French · Italian · Esperanto · Zero dependencies · Type-safe · Extensible
45
+ 6 languages · 7,280 tests · Zero dependencies · Type-safe · Extensible at runtime
40
46
 
41
47
  [![PyPI version](https://img.shields.io/pypi/v/pluralio.svg?style=flat-square)](https://pypi.org/project/pluralio/)
42
48
  [![Python versions](https://img.shields.io/pypi/pyversions/pluralio.svg?style=flat-square)](https://pypi.org/project/pluralio/)
43
49
  [![CI](https://github.com/MathiasPaulenko/pluralio/actions/workflows/ci.yml/badge.svg?style=flat-square)](https://github.com/MathiasPaulenko/pluralio/actions/workflows/ci.yml)
44
- [![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen?style=flat-square)](https://github.com/MathiasPaulenko/pluralio)
50
+ [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square)](https://github.com/MathiasPaulenko/pluralio)
45
51
  [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
46
52
  [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-261230.svg?style=flat-square)](https://github.com/astral-sh/ruff)
47
53
  [![Type checker: mypy](https://img.shields.io/badge/type%20checker-mypy-blue.svg?style=flat-square)](https://github.com/python/mypy)
48
54
  [![Downloads](https://img.shields.io/pypi/dm/pluralio.svg?style=flat-square)](https://pypi.org/project/pluralio/)
55
+ [![Docs](https://img.shields.io/badge/docs-sphinx-blue.svg?style=flat-square)](https://mathiaspaulenko.github.io/pluralio/)
49
56
 
50
57
  </div>
51
58
 
@@ -55,11 +62,15 @@ English · Spanish · Portuguese · French · Italian · Esperanto · Zero depen
55
62
 
56
63
  - **Zero dependencies** — pure Python standard library, nothing else to install
57
64
  - **Type-safe** — full type hints, `py.typed` marker included (PEP 561)
58
- - **97% test coverage** — 7,066 tests, every line is verified
65
+ - **100% test coverage** — 7,280 tests, every line is verified
66
+ - **6 languages** — English, Spanish, Portuguese, French, Italian, Esperanto
59
67
  - **Extensible at runtime** — add irregulars, rules, uncountables, or entire languages without touching source code
68
+ - **Utility functions** — `join()`, `ordinal()`, `template()` for common UI tasks
60
69
  - **Case preservation** — `"Library"` → `"Libraries"`, `"BOX"` → `"BOXES"`
61
70
  - **Count-aware** — `pluralize("item", count=1)` → `"item"`
62
71
  - **Hyphenated words** — `"mother-in-law"` → `"mothers-in-law"`
72
+ - **Unicode normalization** — NFC/NFD inputs handled transparently
73
+ - **Sphinx documentation** — full API reference at [mathiaspaulenko.github.io/pluralio](https://mathiaspaulenko.github.io/pluralio/)
63
74
  - **Python 3.10+** — tested on 3.10, 3.11, 3.12, 3.13, and 3.14
64
75
 
65
76
  ## Table of contents
@@ -78,6 +89,7 @@ English · Spanish · Portuguese · French · Italian · Esperanto · Zero depen
78
89
  - [Performance](#performance)
79
90
  - [Supported languages](#supported-languages)
80
91
  - [Roadmap](#roadmap)
92
+ - [Changelog](#changelog)
81
93
  - [Contributing](#contributing)
82
94
  - [Security](#security)
83
95
  - [License](#license)
@@ -132,6 +144,18 @@ pluralio.pluralize("bijou", lang="fr") # "bijoux"
132
144
  pluralio.singularize("chevaux", lang="fr") # "cheval"
133
145
  pluralio.singularize("travaux", lang="fr") # "travail"
134
146
 
147
+ # ── Italian ────────────────────────────────────────────────────
148
+ pluralio.pluralize("gatto", lang="it") # "gatti"
149
+ pluralio.pluralize("amico", lang="it") # "amici"
150
+ pluralio.pluralize("libro", lang="it") # "libri"
151
+ pluralio.singularize("amici", lang="it") # "amico"
152
+ pluralio.singularize("libri", lang="it") # "libro"
153
+
154
+ # ── Esperanto ──────────────────────────────────────────────────
155
+ pluralio.pluralize("libro", lang="eo") # "libroj"
156
+ pluralio.pluralize("librojn", lang="eo") # "librojn" (already plural)
157
+ pluralio.singularize("libroj", lang="eo") # "libro"
158
+
135
159
  # ── Count-aware ────────────────────────────────────────────────
136
160
  pluralio.pluralize("item", count=1) # "item" (singular)
137
161
  pluralio.pluralize("item", count=0) # "items" (plural)
@@ -146,21 +170,36 @@ pluralio.singularize("Libraries") # "Library"
146
170
  pluralio.pluralize("mother-in-law") # "mothers-in-law"
147
171
  pluralio.singularize("mothers-in-law") # "mother-in-law"
148
172
 
149
- # ── Italian ────────────────────────────────────────────────────
150
- pluralio.pluralize("gatto", lang="it") # "gatti"
151
- pluralio.pluralize("amico", lang="it") # "amici"
152
- pluralio.pluralize("libro", lang="it") # "libri"
153
- pluralio.singularize("amici", lang="it") # "amico"
154
- pluralio.singularize("libri", lang="it") # "libro"
173
+ # ── Unicode normalization ─────────────────────────────────────
174
+ import unicodedata
175
+ nfd = unicodedata.normalize("NFD", "lápiz") # NFD form
176
+ pluralio.pluralize(nfd, lang="es") # "lápices" (NFC output)
155
177
 
156
178
  # ── List supported languages ──────────────────────────────────
157
- pluralio.supported_languages() # ["en", "es", "fr", "it", "pt"]
179
+ pluralio.supported_languages() # ["en", "eo", "es", "fr", "it", "pt"]
158
180
 
159
181
  # ── Inspect word form ─────────────────────────────────────────
160
182
  pluralio.is_plural("cats") # True
161
183
  pluralio.is_singular("cat") # True
162
184
  pluralio.is_plural("sheep") # True (uncountable — valid as both)
163
185
  pluralio.is_singular("sheep") # True (uncountable — valid as both)
186
+ pluralio.is_plural("gatos", lang="es") # True
187
+
188
+ # ── Join words into a list ────────────────────────────────────
189
+ pluralio.join(["apple", "banana", "carrot"]) # "apple, banana, and carrot"
190
+ pluralio.join(["apple", "banana", "carrot"], final_sep="") # "apple, banana and carrot"
191
+ pluralio.join(["apple", "banana", "carrot"], conjunction="or") # "apple, banana, or carrot"
192
+
193
+ # ── Ordinals ──────────────────────────────────────────────────
194
+ pluralio.ordinal(1) # "1st"
195
+ pluralio.ordinal(2) # "2nd"
196
+ pluralio.ordinal(11) # "11th"
197
+ pluralio.ordinal(21) # "21st"
198
+
199
+ # ── Template interpolation ────────────────────────────────────
200
+ pluralio.template("I have {count} {word:pluralize}", count=5, word="cat") # "I have 5 cats"
201
+ pluralio.template("I have {count} {word:pluralize}", count=1, word="cat") # "I have 1 cat"
202
+ pluralio.template("The {word:singularize} is here", word="mice") # "The mouse is here"
164
203
  ```
165
204
 
166
205
  ## How it works
@@ -212,6 +251,14 @@ Every word goes through a **three-step priority chain**:
212
251
  | `is_singular(word, lang="en")` | Check if a word is in singular form. |
213
252
  | `supported_languages()` | Return a sorted list of registered language codes. |
214
253
 
254
+ ### Utility functions
255
+
256
+ | Function | Description |
257
+ | --- | --- |
258
+ | `join(words, *, conjunction="and", final_sep=", ", sep=", ")` | Join words into a natural-language list. |
259
+ | `ordinal(number)` | Convert a number to its ordinal string (`1` → `"1st"`). |
260
+ | `template(text, **kwargs)` | Interpolate pluralize/singularize into string templates. |
261
+
215
262
  ### Extensibility functions
216
263
 
217
264
  | Function | Description |
@@ -231,6 +278,8 @@ Every word goes through a **three-step priority chain**:
231
278
  | `LanguageRules` | Dataclass holding all rules for a language. |
232
279
  | `register(rules)` | Register a `LanguageRules` instance. |
233
280
  | `get_rules(lang)` | Retrieve rules for a language (raises `ValueError` if not found). |
281
+ | `snapshot()` | Deep-copy the current registry state (test isolation). |
282
+ | `restore(state)` | Restore a registry state returned by `snapshot()`. |
234
283
 
235
284
  ## Extending rules
236
285
 
@@ -307,19 +356,34 @@ How does pluralio compare to other Python inflection libraries?
307
356
  | --- | --- | --- | --- | --- |
308
357
  | Spanish pluralization | ✅ 100% | ❌ 39% | ⚠️ 74% | ❌ 40% |
309
358
  | Spanish singularization | ✅ 100% | ❌ 29% | ⚠️ 87% | ❌ N/A |
359
+ | Portuguese pluralization | ✅ 100% | ❌ | ❌ | ❌ |
360
+ | French pluralization | ✅ 100% | ❌ | ❌ | ❌ |
361
+ | Italian pluralization | ✅ 100% | ❌ | ❌ | ❌ |
362
+ | Esperanto pluralization | ✅ 100% | ❌ | ❌ | ❌ |
310
363
  | Singularize | ✅ | ✅ | ✅ | ❌ |
311
364
  | Count-aware (`count=1`) | ✅ | ✅ | ❌ | ❌ |
312
365
  | Case preservation | ✅ | ❌ | ❌ | ✅ |
313
366
  | Hyphenated words | ✅ | ❌ | ❌ | ❌ |
367
+ | Unicode normalization (NFC/NFD) | ✅ | ❌ | ❌ | ❌ |
314
368
  | Idempotency (ES) | ✅ | ❌ | ❌ | ❌ |
315
- | Uncountables (ES) | ✅ ~87 | ❌ | ❌ | ❌ |
369
+ | Uncountables (ES) | ✅ ~92 | ❌ | ❌ | ❌ |
316
370
  | Accent restoration (ES) | ✅ | ❌ | ⚠️ Partial | ❌ |
317
371
  | Runtime extensibility | ✅ | ❌ | ❌ | ✅ |
318
372
  | Add custom languages | ✅ | ❌ | ✅ | ❌ |
319
373
  | Zero dependencies | ✅ | ❌ | ✅ | ✅ |
320
374
  | Type hints (`py.typed`) | ✅ | ✅ | ❌ | ❌ |
375
+ | Sphinx documentation | ✅ | ❌ | ❌ | ❌ |
321
376
  | Python 3.10+ | ✅ | ✅ | ✅ | ✅ |
322
- | Test coverage | 97% | ~95% | ~60% | ~70% |
377
+ | Test coverage | 100% | ~95% | ~60% | ~70% |
378
+ | Number to words | ❌ | ✅ | ❌ | ❌ |
379
+ | Ordinals (`1` → `1st`) | ✅ | ✅ | ❌ | ❌ |
380
+ | Indefinite articles (`a`/`an`) | ❌ | ✅ | ❌ | ❌ |
381
+ | Join words into a list | ✅ | ✅ | ❌ | ❌ |
382
+ | Present participle | ❌ | ✅ | ❌ | ❌ |
383
+ | Classical pluralization modes | ❌ | ✅ | ❌ | ❌ |
384
+ | Part-of-speech inflection | ❌ | ✅ | ❌ | ❌ |
385
+ | Template interpolation | ✅ | ✅ | ❌ | ❌ |
386
+ | English-only maturity | 6 languages | Deep EN | EN only | EN only |
323
387
 
324
388
  [inflect]: https://github.com/jazzband/inflect
325
389
  [pluralsingular]: https://pypi.org/project/pluralsingular/
@@ -341,35 +405,40 @@ Benchmark: 100,000 calls across 13 mixed-language words (English, Spanish, Portu
341
405
  | Language | Code | Regex rules | Irregulars | Uncountables | Status |
342
406
  | --- | --- | --- | --- | --- | --- |
343
407
  | English | `en` | 7 + 22 | 684 | 219 | ✅ Complete |
344
- | Spanish | `es` | 9 + 8 | 352 + 81 extra singles | 92 | ✅ Complete |
345
- | Portuguese | `pt` | 8 + 13 | 388 + 88 extra singles | 88 | ✅ Complete |
346
- | French | `fr` | 6 + 4 | 104 + 27 extra singles | 81 | ✅ Complete |
347
- | Italian | `it` | 19 + 12 | 239 + 0 extra singles | 144 | ✅ Complete |
348
- | Esperanto | `eo` | 2 + 2 | 0 | 33 | ✅ Complete |
408
+ | Spanish | `es` | 9 + 8 | 354 | 92 | ✅ Complete |
409
+ | Portuguese | `pt` | 9 + 13 | 393 | 88 | ✅ Complete |
410
+ | French | `fr` | 6 + 4 | 100 | 92 | ✅ Complete |
411
+ | Italian | `it` | 19 + 12 | 249 | 126 | ✅ Complete |
412
+ | Esperanto | `eo` | 4 + 2 | 0 | 39 | ✅ Complete |
349
413
 
350
414
  ## Roadmap
351
415
 
352
416
  | Version | Goal | Status |
353
417
  | --- | --- | --- |
354
418
  | `1.0.0` | English + Spanish, core engine, extensibility API | ✅ Released |
355
- | `1.1.0` | English classical plurals, uncountables, suffix rules | ✅ Released |
356
- | `1.2.0` | English -che words, compound prefixes, whitespace | ✅ Released |
357
- | `1.3.0` | English expansion (Latin/Greek, proper nouns, -o words) | ✅ Released |
358
- | `1.4.0` | Spanish expansion (loanwords, accent restoration, uncountables, idempotency fix) | ✅ Released |
359
419
  | `1.5.0` | Portuguese (`pt`) | ✅ Released |
360
420
  | `1.6.0` | French (`fr`) | ✅ Released |
361
421
  | `1.7.0` | Italian (`it`) | ✅ Released |
362
- | `1.8.3` | Robustness fixes, code quality improvements, expanded lint rules | ✅ Released |
363
422
  | `2.0.0` | Rules restructured into `pluralio/rules/` subpackage, performance optimization | ✅ Released |
364
- | `2.0.1` | CI fixes, hyphenated dedup, docs update, Python 3.14 support | ✅ Released |
365
- | `2.0.2` | Simplified is_plural/is_singular, README fixes, release.yml Python 3.14 | ✅ Released |
366
423
  | `2.1.0` | Esperanto (`eo`) — trivial `-j` plural | ✅ Released |
367
- | `2.1.1` | Bug fixes: Esperanto double-plural, register() cache, _match_case empty target | ✅ Released |
368
- | `2.1.2` | Bug fixes: restore() cache clearing, _match_case digit-only source, register_language redundant call | ✅ Released |
369
- | `2.2.0` | Catalan (`ca`) — Romance, natural fit | 🔜 Planned |
370
- | `2.3.0` | Dutch (`nl`) — Germanic, `-en` / `-s` patterns | 🔜 Planned |
424
+ | `2.2.0` | Utility functions: `join()`, `ordinal()`, `template()` | ✅ Released |
425
+ | `2.3.0` | Bug fixes: language-code normalization, rule corrections (FR/IT/PT), docs | ✅ Released |
426
+ | `2.4.0` | Catalan (`ca`) — Romance, natural fit | 🔜 Planned |
371
427
  | `3.0.0` | German (`de`) — umlauts + multiple plural patterns | 🔜 Planned |
372
428
 
429
+ ## Changelog
430
+
431
+ See [CHANGELOG.md](CHANGELOG.md) for the full history.
432
+
433
+ ### Recent releases
434
+
435
+ - **2.3.0** — Bug fixes: language-code normalization, rule corrections (FR/IT/PT), doctests
436
+ - **2.2.0** — Utility functions: `join()`, `ordinal()`, `template()`
437
+ - **2.1.2** — Bug fixes: `restore()` cache clearing, `_match_case` digit-only source, `register_language` redundant call
438
+ - **2.1.1** — Bug fixes: Esperanto double-plural, `register()` cache, `_match_case` empty target
439
+ - **2.1.0** — Esperanto (`eo`) support
440
+ - **2.0.0** — Rules restructured into `pluralio/rules/` subpackage, performance optimization
441
+
373
442
  ## Contributing
374
443
 
375
444
  Contributions are welcome! Whether it's a bug report, a new language, or a feature suggestion — please read our guides first:
@@ -390,6 +459,10 @@ pip install -e ".[dev]"
390
459
  ruff check pluralio/ tests/
391
460
  mypy pluralio/ tests/
392
461
  pytest
462
+
463
+ # Build docs locally
464
+ pip install -e ".[docs]"
465
+ python -m sphinx -b html docs docs/_build/html
393
466
  ```
394
467
 
395
468
  ## Security