pluralio 2.1.2__tar.gz → 2.2.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 (72) hide show
  1. pluralio-2.2.0/.github/workflows/docs.yml +46 -0
  2. {pluralio-2.1.2 → pluralio-2.2.0}/.gitignore +2 -1
  3. {pluralio-2.1.2 → pluralio-2.2.0}/CHANGELOG.md +12 -0
  4. {pluralio-2.1.2 → pluralio-2.2.0}/PKG-INFO +90 -22
  5. {pluralio-2.1.2 → pluralio-2.2.0}/README.md +84 -21
  6. pluralio-2.2.0/docs/api/core.rst +15 -0
  7. pluralio-2.2.0/docs/api/en.rst +6 -0
  8. pluralio-2.2.0/docs/api/eo.rst +6 -0
  9. pluralio-2.2.0/docs/api/es.rst +6 -0
  10. pluralio-2.2.0/docs/api/extensibility.rst +85 -0
  11. pluralio-2.2.0/docs/api/fr.rst +6 -0
  12. pluralio-2.2.0/docs/api/it.rst +6 -0
  13. pluralio-2.2.0/docs/api/pt.rst +6 -0
  14. pluralio-2.2.0/docs/api/registry.rst +6 -0
  15. pluralio-2.2.0/docs/api/rules.rst +20 -0
  16. pluralio-2.2.0/docs/api/utils.rst +7 -0
  17. pluralio-2.2.0/docs/changelog.rst +5 -0
  18. pluralio-2.2.0/docs/conf.py +60 -0
  19. pluralio-2.2.0/docs/cookbook.rst +199 -0
  20. pluralio-2.2.0/docs/index.rst +83 -0
  21. pluralio-2.2.0/docs/languages.rst +125 -0
  22. pluralio-2.2.0/docs/usage.rst +95 -0
  23. {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/__init__.py +7 -0
  24. {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/core.py +11 -10
  25. {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/registry.py +10 -0
  26. pluralio-2.2.0/pluralio/utils.py +167 -0
  27. {pluralio-2.1.2 → pluralio-2.2.0}/pyproject.toml +11 -1
  28. pluralio-2.2.0/tests/test_utils.py +362 -0
  29. pluralio-2.2.0/tests/test_version.py +44 -0
  30. {pluralio-2.1.2 → pluralio-2.2.0}/.github/ISSUE_TEMPLATE/bug_report.md +0 -0
  31. {pluralio-2.1.2 → pluralio-2.2.0}/.github/ISSUE_TEMPLATE/feature_request.md +0 -0
  32. {pluralio-2.1.2 → pluralio-2.2.0}/.github/pull_request_template.md +0 -0
  33. {pluralio-2.1.2 → pluralio-2.2.0}/.github/workflows/ci.yml +0 -0
  34. {pluralio-2.1.2 → pluralio-2.2.0}/.github/workflows/release.yml +0 -0
  35. {pluralio-2.1.2 → pluralio-2.2.0}/CODE_OF_CONDUCT.md +0 -0
  36. {pluralio-2.1.2 → pluralio-2.2.0}/CONTRIBUTING.md +0 -0
  37. {pluralio-2.1.2 → pluralio-2.2.0}/LICENSE +0 -0
  38. {pluralio-2.1.2 → pluralio-2.2.0}/SECURITY.md +0 -0
  39. {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/py.typed +0 -0
  40. {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/__init__.py +0 -0
  41. {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/en.py +0 -0
  42. {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/eo.py +0 -0
  43. {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/es.py +0 -0
  44. {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/fr.py +0 -0
  45. {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/it.py +0 -0
  46. {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/pt.py +0 -0
  47. {pluralio-2.1.2 → pluralio-2.2.0}/tests/__init__.py +0 -0
  48. {pluralio-2.1.2 → pluralio-2.2.0}/tests/conftest.py +0 -0
  49. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_core.py +0 -0
  50. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_cross_edge_cases.py +0 -0
  51. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_en_edge_cases.py +0 -0
  52. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_en_plurals.py +0 -0
  53. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_en_singles.py +0 -0
  54. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_eo_plurals.py +0 -0
  55. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_eo_singles.py +0 -0
  56. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_es_edge_cases.py +0 -0
  57. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_es_plurals.py +0 -0
  58. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_es_singles.py +0 -0
  59. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_fr_edge_cases.py +0 -0
  60. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_fr_plurals.py +0 -0
  61. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_fr_singles.py +0 -0
  62. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_inspect.py +0 -0
  63. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_it_edge_cases.py +0 -0
  64. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_it_plurals.py +0 -0
  65. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_it_singles.py +0 -0
  66. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_property.py +0 -0
  67. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_pt_edge_cases.py +0 -0
  68. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_pt_plurals.py +0 -0
  69. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_pt_singles.py +0 -0
  70. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_registry.py +0 -0
  71. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_registry_isolation.py +0 -0
  72. {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_round_trip.py +0 -0
@@ -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,18 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [2.2.0] - 2025-07-13
6
+
7
+ ### Added
8
+
9
+ - `join()` — join words into a natural-language list with configurable conjunction and separators
10
+ - `ordinal()` — convert a number to its ordinal string representation (1 → "1st", 2 → "2nd", 11 → "11th")
11
+ - `template()` — interpolate pluralize/singularize into string templates with count-aware support
12
+ - `pluralio.utils` module with full docstrings and type hints
13
+ - 90 tests covering all utility functions, including property-based tests with hypothesis
14
+ - Sphinx documentation page for utility functions
15
+ - Cookbook recipes for join, ordinal, and template
16
+
5
17
  ## [2.1.2] - 2025-07-13
6
18
 
7
19
  ### Fixed
@@ -1,11 +1,12 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pluralio
3
- Version: 2.1.2
3
+ Version: 2.2.0
4
4
  Summary: Pluralization and singularization for Python — EN/ES/PT/FR/IT/EO, zero deps, type-safe
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
@@ -28,6 +29,10 @@ Requires-Dist: mypy>=1.10; extra == 'dev'
28
29
  Requires-Dist: pytest-cov>=5.0; extra == 'dev'
29
30
  Requires-Dist: pytest>=8.0; extra == 'dev'
30
31
  Requires-Dist: ruff>=0.5; extra == 'dev'
32
+ Provides-Extra: docs
33
+ Requires-Dist: furo>=2024.0; extra == 'docs'
34
+ Requires-Dist: myst-parser>=3.0; extra == 'docs'
35
+ Requires-Dist: sphinx>=7.0; extra == 'docs'
31
36
  Description-Content-Type: text/markdown
32
37
 
33
38
  <div align="center">
@@ -41,11 +46,12 @@ English · Spanish · Portuguese · French · Italian · Esperanto · Zero depen
41
46
  [![PyPI version](https://img.shields.io/pypi/v/pluralio.svg?style=flat-square)](https://pypi.org/project/pluralio/)
42
47
  [![Python versions](https://img.shields.io/pypi/pyversions/pluralio.svg?style=flat-square)](https://pypi.org/project/pluralio/)
43
48
  [![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)
49
+ [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square)](https://github.com/MathiasPaulenko/pluralio)
45
50
  [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
46
51
  [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-261230.svg?style=flat-square)](https://github.com/astral-sh/ruff)
47
52
  [![Type checker: mypy](https://img.shields.io/badge/type%20checker-mypy-blue.svg?style=flat-square)](https://github.com/python/mypy)
48
53
  [![Downloads](https://img.shields.io/pypi/dm/pluralio.svg?style=flat-square)](https://pypi.org/project/pluralio/)
54
+ [![Docs](https://img.shields.io/badge/docs-sphinx-blue.svg?style=flat-square)](https://mathiaspaulenko.github.io/pluralio/)
49
55
 
50
56
  </div>
51
57
 
@@ -55,11 +61,15 @@ English · Spanish · Portuguese · French · Italian · Esperanto · Zero depen
55
61
 
56
62
  - **Zero dependencies** — pure Python standard library, nothing else to install
57
63
  - **Type-safe** — full type hints, `py.typed` marker included (PEP 561)
58
- - **97% test coverage** — 7,066 tests, every line is verified
64
+ - **100% test coverage** — 7,233 tests, every line is verified
65
+ - **6 languages** — English, Spanish, Portuguese, French, Italian, Esperanto
59
66
  - **Extensible at runtime** — add irregulars, rules, uncountables, or entire languages without touching source code
67
+ - **Utility functions** — `join()`, `ordinal()`, `template()` for common UI tasks
60
68
  - **Case preservation** — `"Library"` → `"Libraries"`, `"BOX"` → `"BOXES"`
61
69
  - **Count-aware** — `pluralize("item", count=1)` → `"item"`
62
70
  - **Hyphenated words** — `"mother-in-law"` → `"mothers-in-law"`
71
+ - **Unicode normalization** — NFC/NFD inputs handled transparently
72
+ - **Sphinx documentation** — full API reference at [mathiaspaulenko.github.io/pluralio](https://mathiaspaulenko.github.io/pluralio/)
63
73
  - **Python 3.10+** — tested on 3.10, 3.11, 3.12, 3.13, and 3.14
64
74
 
65
75
  ## Table of contents
@@ -78,6 +88,7 @@ English · Spanish · Portuguese · French · Italian · Esperanto · Zero depen
78
88
  - [Performance](#performance)
79
89
  - [Supported languages](#supported-languages)
80
90
  - [Roadmap](#roadmap)
91
+ - [Changelog](#changelog)
81
92
  - [Contributing](#contributing)
82
93
  - [Security](#security)
83
94
  - [License](#license)
@@ -132,6 +143,18 @@ pluralio.pluralize("bijou", lang="fr") # "bijoux"
132
143
  pluralio.singularize("chevaux", lang="fr") # "cheval"
133
144
  pluralio.singularize("travaux", lang="fr") # "travail"
134
145
 
146
+ # ── Italian ────────────────────────────────────────────────────
147
+ pluralio.pluralize("gatto", lang="it") # "gatti"
148
+ pluralio.pluralize("amico", lang="it") # "amici"
149
+ pluralio.pluralize("libro", lang="it") # "libri"
150
+ pluralio.singularize("amici", lang="it") # "amico"
151
+ pluralio.singularize("libri", lang="it") # "libro"
152
+
153
+ # ── Esperanto ──────────────────────────────────────────────────
154
+ pluralio.pluralize("libro", lang="eo") # "libroj"
155
+ pluralio.pluralize("librojn", lang="eo") # "librojn" (already plural)
156
+ pluralio.singularize("libroj", lang="eo") # "libro"
157
+
135
158
  # ── Count-aware ────────────────────────────────────────────────
136
159
  pluralio.pluralize("item", count=1) # "item" (singular)
137
160
  pluralio.pluralize("item", count=0) # "items" (plural)
@@ -146,21 +169,36 @@ pluralio.singularize("Libraries") # "Library"
146
169
  pluralio.pluralize("mother-in-law") # "mothers-in-law"
147
170
  pluralio.singularize("mothers-in-law") # "mother-in-law"
148
171
 
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"
172
+ # ── Unicode normalization ─────────────────────────────────────
173
+ import unicodedata
174
+ nfd = unicodedata.normalize("NFD", "lápiz") # NFD form
175
+ pluralio.pluralize(nfd, lang="es") # "lápices" (NFC output)
155
176
 
156
177
  # ── List supported languages ──────────────────────────────────
157
- pluralio.supported_languages() # ["en", "es", "fr", "it", "pt"]
178
+ pluralio.supported_languages() # ["en", "eo", "es", "fr", "it", "pt"]
158
179
 
159
180
  # ── Inspect word form ─────────────────────────────────────────
160
181
  pluralio.is_plural("cats") # True
161
182
  pluralio.is_singular("cat") # True
162
183
  pluralio.is_plural("sheep") # True (uncountable — valid as both)
163
184
  pluralio.is_singular("sheep") # True (uncountable — valid as both)
185
+ pluralio.is_plural("gatos", lang="es") # True
186
+
187
+ # ── Join words into a list ────────────────────────────────────
188
+ pluralio.join(["apple", "banana", "carrot"]) # "apple, banana, and carrot"
189
+ pluralio.join(["apple", "banana", "carrot"], final_sep="") # "apple, banana and carrot"
190
+ pluralio.join(["apple", "banana", "carrot"], conjunction="or") # "apple, banana, or carrot"
191
+
192
+ # ── Ordinals ──────────────────────────────────────────────────
193
+ pluralio.ordinal(1) # "1st"
194
+ pluralio.ordinal(2) # "2nd"
195
+ pluralio.ordinal(11) # "11th"
196
+ pluralio.ordinal(21) # "21st"
197
+
198
+ # ── Template interpolation ────────────────────────────────────
199
+ pluralio.template("I have {count} {word:pluralize}", count=5, word="cat") # "I have 5 cats"
200
+ pluralio.template("I have {count} {word:pluralize}", count=1, word="cat") # "I have 1 cat"
201
+ pluralio.template("The {word:singularize} is here", word="mice") # "The mouse is here"
164
202
  ```
165
203
 
166
204
  ## How it works
@@ -212,6 +250,14 @@ Every word goes through a **three-step priority chain**:
212
250
  | `is_singular(word, lang="en")` | Check if a word is in singular form. |
213
251
  | `supported_languages()` | Return a sorted list of registered language codes. |
214
252
 
253
+ ### Utility functions
254
+
255
+ | Function | Description |
256
+ | --- | --- |
257
+ | `join(words, *, conjunction="and", final_sep=", ", sep=", ")` | Join words into a natural-language list. |
258
+ | `ordinal(number)` | Convert a number to its ordinal string (`1` → `"1st"`). |
259
+ | `template(text, **kwargs)` | Interpolate pluralize/singularize into string templates. |
260
+
215
261
  ### Extensibility functions
216
262
 
217
263
  | Function | Description |
@@ -307,10 +353,15 @@ How does pluralio compare to other Python inflection libraries?
307
353
  | --- | --- | --- | --- | --- |
308
354
  | Spanish pluralization | ✅ 100% | ❌ 39% | ⚠️ 74% | ❌ 40% |
309
355
  | Spanish singularization | ✅ 100% | ❌ 29% | ⚠️ 87% | ❌ N/A |
356
+ | Portuguese pluralization | ✅ 100% | ❌ | ❌ | ❌ |
357
+ | French pluralization | ✅ 100% | ❌ | ❌ | ❌ |
358
+ | Italian pluralization | ✅ 100% | ❌ | ❌ | ❌ |
359
+ | Esperanto pluralization | ✅ 100% | ❌ | ❌ | ❌ |
310
360
  | Singularize | ✅ | ✅ | ✅ | ❌ |
311
361
  | Count-aware (`count=1`) | ✅ | ✅ | ❌ | ❌ |
312
362
  | Case preservation | ✅ | ❌ | ❌ | ✅ |
313
363
  | Hyphenated words | ✅ | ❌ | ❌ | ❌ |
364
+ | Unicode normalization (NFC/NFD) | ✅ | ❌ | ❌ | ❌ |
314
365
  | Idempotency (ES) | ✅ | ❌ | ❌ | ❌ |
315
366
  | Uncountables (ES) | ✅ ~87 | ❌ | ❌ | ❌ |
316
367
  | Accent restoration (ES) | ✅ | ❌ | ⚠️ Partial | ❌ |
@@ -318,8 +369,18 @@ How does pluralio compare to other Python inflection libraries?
318
369
  | Add custom languages | ✅ | ❌ | ✅ | ❌ |
319
370
  | Zero dependencies | ✅ | ❌ | ✅ | ✅ |
320
371
  | Type hints (`py.typed`) | ✅ | ✅ | ❌ | ❌ |
372
+ | Sphinx documentation | ✅ | ❌ | ❌ | ❌ |
321
373
  | Python 3.10+ | ✅ | ✅ | ✅ | ✅ |
322
- | Test coverage | 97% | ~95% | ~60% | ~70% |
374
+ | Test coverage | 100% | ~95% | ~60% | ~70% |
375
+ | Number to words | ❌ | ✅ | ❌ | ❌ |
376
+ | Ordinals (`1` → `1st`) | ❌ | ✅ | ❌ | ❌ |
377
+ | Indefinite articles (`a`/`an`) | ❌ | ✅ | ❌ | ❌ |
378
+ | Join words into a list | ✅ | ✅ | ❌ | ❌ |
379
+ | Present participle | ❌ | ✅ | ❌ | ❌ |
380
+ | Classical pluralization modes | ❌ | ✅ | ❌ | ❌ |
381
+ | Part-of-speech inflection | ❌ | ✅ | ❌ | ❌ |
382
+ | Template interpolation | ✅ | ✅ | ❌ | ❌ |
383
+ | English-only maturity | 6 languages | Deep EN | EN only | EN only |
323
384
 
324
385
  [inflect]: https://github.com/jazzband/inflect
325
386
  [pluralsingular]: https://pypi.org/project/pluralsingular/
@@ -352,24 +413,27 @@ Benchmark: 100,000 calls across 13 mixed-language words (English, Spanish, Portu
352
413
  | Version | Goal | Status |
353
414
  | --- | --- | --- |
354
415
  | `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
416
  | `1.5.0` | Portuguese (`pt`) | ✅ Released |
360
417
  | `1.6.0` | French (`fr`) | ✅ Released |
361
418
  | `1.7.0` | Italian (`it`) | ✅ Released |
362
- | `1.8.3` | Robustness fixes, code quality improvements, expanded lint rules | ✅ Released |
363
419
  | `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
420
  | `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 |
421
+ | `2.2.0` | Utility functions: `join()`, `ordinal()`, `template()` | ✅ Released |
422
+ | `2.3.0` | Catalan (`ca`) — Romance, natural fit | 🔜 Planned |
371
423
  | `3.0.0` | German (`de`) — umlauts + multiple plural patterns | 🔜 Planned |
372
424
 
425
+ ## Changelog
426
+
427
+ See [CHANGELOG.md](CHANGELOG.md) for the full history.
428
+
429
+ ### Recent releases
430
+
431
+ - **2.2.0** — Utility functions: `join()`, `ordinal()`, `template()`
432
+ - **2.1.2** — Bug fixes: `restore()` cache clearing, `_match_case` digit-only source, `register_language` redundant call
433
+ - **2.1.1** — Bug fixes: Esperanto double-plural, `register()` cache, `_match_case` empty target
434
+ - **2.1.0** — Esperanto (`eo`) support
435
+ - **2.0.0** — Rules restructured into `pluralio/rules/` subpackage, performance optimization
436
+
373
437
  ## Contributing
374
438
 
375
439
  Contributions are welcome! Whether it's a bug report, a new language, or a feature suggestion — please read our guides first:
@@ -390,6 +454,10 @@ pip install -e ".[dev]"
390
454
  ruff check pluralio/ tests/
391
455
  mypy pluralio/ tests/
392
456
  pytest
457
+
458
+ # Build docs locally
459
+ pip install -e ".[docs]"
460
+ python -m sphinx -b html docs docs/_build/html
393
461
  ```
394
462
 
395
463
  ## Security
@@ -9,11 +9,12 @@ English · Spanish · Portuguese · French · Italian · Esperanto · Zero depen
9
9
  [![PyPI version](https://img.shields.io/pypi/v/pluralio.svg?style=flat-square)](https://pypi.org/project/pluralio/)
10
10
  [![Python versions](https://img.shields.io/pypi/pyversions/pluralio.svg?style=flat-square)](https://pypi.org/project/pluralio/)
11
11
  [![CI](https://github.com/MathiasPaulenko/pluralio/actions/workflows/ci.yml/badge.svg?style=flat-square)](https://github.com/MathiasPaulenko/pluralio/actions/workflows/ci.yml)
12
- [![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen?style=flat-square)](https://github.com/MathiasPaulenko/pluralio)
12
+ [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square)](https://github.com/MathiasPaulenko/pluralio)
13
13
  [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
14
14
  [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-261230.svg?style=flat-square)](https://github.com/astral-sh/ruff)
15
15
  [![Type checker: mypy](https://img.shields.io/badge/type%20checker-mypy-blue.svg?style=flat-square)](https://github.com/python/mypy)
16
16
  [![Downloads](https://img.shields.io/pypi/dm/pluralio.svg?style=flat-square)](https://pypi.org/project/pluralio/)
17
+ [![Docs](https://img.shields.io/badge/docs-sphinx-blue.svg?style=flat-square)](https://mathiaspaulenko.github.io/pluralio/)
17
18
 
18
19
  </div>
19
20
 
@@ -23,11 +24,15 @@ English · Spanish · Portuguese · French · Italian · Esperanto · Zero depen
23
24
 
24
25
  - **Zero dependencies** — pure Python standard library, nothing else to install
25
26
  - **Type-safe** — full type hints, `py.typed` marker included (PEP 561)
26
- - **97% test coverage** — 7,066 tests, every line is verified
27
+ - **100% test coverage** — 7,233 tests, every line is verified
28
+ - **6 languages** — English, Spanish, Portuguese, French, Italian, Esperanto
27
29
  - **Extensible at runtime** — add irregulars, rules, uncountables, or entire languages without touching source code
30
+ - **Utility functions** — `join()`, `ordinal()`, `template()` for common UI tasks
28
31
  - **Case preservation** — `"Library"` → `"Libraries"`, `"BOX"` → `"BOXES"`
29
32
  - **Count-aware** — `pluralize("item", count=1)` → `"item"`
30
33
  - **Hyphenated words** — `"mother-in-law"` → `"mothers-in-law"`
34
+ - **Unicode normalization** — NFC/NFD inputs handled transparently
35
+ - **Sphinx documentation** — full API reference at [mathiaspaulenko.github.io/pluralio](https://mathiaspaulenko.github.io/pluralio/)
31
36
  - **Python 3.10+** — tested on 3.10, 3.11, 3.12, 3.13, and 3.14
32
37
 
33
38
  ## Table of contents
@@ -46,6 +51,7 @@ English · Spanish · Portuguese · French · Italian · Esperanto · Zero depen
46
51
  - [Performance](#performance)
47
52
  - [Supported languages](#supported-languages)
48
53
  - [Roadmap](#roadmap)
54
+ - [Changelog](#changelog)
49
55
  - [Contributing](#contributing)
50
56
  - [Security](#security)
51
57
  - [License](#license)
@@ -100,6 +106,18 @@ pluralio.pluralize("bijou", lang="fr") # "bijoux"
100
106
  pluralio.singularize("chevaux", lang="fr") # "cheval"
101
107
  pluralio.singularize("travaux", lang="fr") # "travail"
102
108
 
109
+ # ── Italian ────────────────────────────────────────────────────
110
+ pluralio.pluralize("gatto", lang="it") # "gatti"
111
+ pluralio.pluralize("amico", lang="it") # "amici"
112
+ pluralio.pluralize("libro", lang="it") # "libri"
113
+ pluralio.singularize("amici", lang="it") # "amico"
114
+ pluralio.singularize("libri", lang="it") # "libro"
115
+
116
+ # ── Esperanto ──────────────────────────────────────────────────
117
+ pluralio.pluralize("libro", lang="eo") # "libroj"
118
+ pluralio.pluralize("librojn", lang="eo") # "librojn" (already plural)
119
+ pluralio.singularize("libroj", lang="eo") # "libro"
120
+
103
121
  # ── Count-aware ────────────────────────────────────────────────
104
122
  pluralio.pluralize("item", count=1) # "item" (singular)
105
123
  pluralio.pluralize("item", count=0) # "items" (plural)
@@ -114,21 +132,36 @@ pluralio.singularize("Libraries") # "Library"
114
132
  pluralio.pluralize("mother-in-law") # "mothers-in-law"
115
133
  pluralio.singularize("mothers-in-law") # "mother-in-law"
116
134
 
117
- # ── Italian ────────────────────────────────────────────────────
118
- pluralio.pluralize("gatto", lang="it") # "gatti"
119
- pluralio.pluralize("amico", lang="it") # "amici"
120
- pluralio.pluralize("libro", lang="it") # "libri"
121
- pluralio.singularize("amici", lang="it") # "amico"
122
- pluralio.singularize("libri", lang="it") # "libro"
135
+ # ── Unicode normalization ─────────────────────────────────────
136
+ import unicodedata
137
+ nfd = unicodedata.normalize("NFD", "lápiz") # NFD form
138
+ pluralio.pluralize(nfd, lang="es") # "lápices" (NFC output)
123
139
 
124
140
  # ── List supported languages ──────────────────────────────────
125
- pluralio.supported_languages() # ["en", "es", "fr", "it", "pt"]
141
+ pluralio.supported_languages() # ["en", "eo", "es", "fr", "it", "pt"]
126
142
 
127
143
  # ── Inspect word form ─────────────────────────────────────────
128
144
  pluralio.is_plural("cats") # True
129
145
  pluralio.is_singular("cat") # True
130
146
  pluralio.is_plural("sheep") # True (uncountable — valid as both)
131
147
  pluralio.is_singular("sheep") # True (uncountable — valid as both)
148
+ pluralio.is_plural("gatos", lang="es") # True
149
+
150
+ # ── Join words into a list ────────────────────────────────────
151
+ pluralio.join(["apple", "banana", "carrot"]) # "apple, banana, and carrot"
152
+ pluralio.join(["apple", "banana", "carrot"], final_sep="") # "apple, banana and carrot"
153
+ pluralio.join(["apple", "banana", "carrot"], conjunction="or") # "apple, banana, or carrot"
154
+
155
+ # ── Ordinals ──────────────────────────────────────────────────
156
+ pluralio.ordinal(1) # "1st"
157
+ pluralio.ordinal(2) # "2nd"
158
+ pluralio.ordinal(11) # "11th"
159
+ pluralio.ordinal(21) # "21st"
160
+
161
+ # ── Template interpolation ────────────────────────────────────
162
+ pluralio.template("I have {count} {word:pluralize}", count=5, word="cat") # "I have 5 cats"
163
+ pluralio.template("I have {count} {word:pluralize}", count=1, word="cat") # "I have 1 cat"
164
+ pluralio.template("The {word:singularize} is here", word="mice") # "The mouse is here"
132
165
  ```
133
166
 
134
167
  ## How it works
@@ -180,6 +213,14 @@ Every word goes through a **three-step priority chain**:
180
213
  | `is_singular(word, lang="en")` | Check if a word is in singular form. |
181
214
  | `supported_languages()` | Return a sorted list of registered language codes. |
182
215
 
216
+ ### Utility functions
217
+
218
+ | Function | Description |
219
+ | --- | --- |
220
+ | `join(words, *, conjunction="and", final_sep=", ", sep=", ")` | Join words into a natural-language list. |
221
+ | `ordinal(number)` | Convert a number to its ordinal string (`1` → `"1st"`). |
222
+ | `template(text, **kwargs)` | Interpolate pluralize/singularize into string templates. |
223
+
183
224
  ### Extensibility functions
184
225
 
185
226
  | Function | Description |
@@ -275,10 +316,15 @@ How does pluralio compare to other Python inflection libraries?
275
316
  | --- | --- | --- | --- | --- |
276
317
  | Spanish pluralization | ✅ 100% | ❌ 39% | ⚠️ 74% | ❌ 40% |
277
318
  | Spanish singularization | ✅ 100% | ❌ 29% | ⚠️ 87% | ❌ N/A |
319
+ | Portuguese pluralization | ✅ 100% | ❌ | ❌ | ❌ |
320
+ | French pluralization | ✅ 100% | ❌ | ❌ | ❌ |
321
+ | Italian pluralization | ✅ 100% | ❌ | ❌ | ❌ |
322
+ | Esperanto pluralization | ✅ 100% | ❌ | ❌ | ❌ |
278
323
  | Singularize | ✅ | ✅ | ✅ | ❌ |
279
324
  | Count-aware (`count=1`) | ✅ | ✅ | ❌ | ❌ |
280
325
  | Case preservation | ✅ | ❌ | ❌ | ✅ |
281
326
  | Hyphenated words | ✅ | ❌ | ❌ | ❌ |
327
+ | Unicode normalization (NFC/NFD) | ✅ | ❌ | ❌ | ❌ |
282
328
  | Idempotency (ES) | ✅ | ❌ | ❌ | ❌ |
283
329
  | Uncountables (ES) | ✅ ~87 | ❌ | ❌ | ❌ |
284
330
  | Accent restoration (ES) | ✅ | ❌ | ⚠️ Partial | ❌ |
@@ -286,8 +332,18 @@ How does pluralio compare to other Python inflection libraries?
286
332
  | Add custom languages | ✅ | ❌ | ✅ | ❌ |
287
333
  | Zero dependencies | ✅ | ❌ | ✅ | ✅ |
288
334
  | Type hints (`py.typed`) | ✅ | ✅ | ❌ | ❌ |
335
+ | Sphinx documentation | ✅ | ❌ | ❌ | ❌ |
289
336
  | Python 3.10+ | ✅ | ✅ | ✅ | ✅ |
290
- | Test coverage | 97% | ~95% | ~60% | ~70% |
337
+ | Test coverage | 100% | ~95% | ~60% | ~70% |
338
+ | Number to words | ❌ | ✅ | ❌ | ❌ |
339
+ | Ordinals (`1` → `1st`) | ❌ | ✅ | ❌ | ❌ |
340
+ | Indefinite articles (`a`/`an`) | ❌ | ✅ | ❌ | ❌ |
341
+ | Join words into a list | ✅ | ✅ | ❌ | ❌ |
342
+ | Present participle | ❌ | ✅ | ❌ | ❌ |
343
+ | Classical pluralization modes | ❌ | ✅ | ❌ | ❌ |
344
+ | Part-of-speech inflection | ❌ | ✅ | ❌ | ❌ |
345
+ | Template interpolation | ✅ | ✅ | ❌ | ❌ |
346
+ | English-only maturity | 6 languages | Deep EN | EN only | EN only |
291
347
 
292
348
  [inflect]: https://github.com/jazzband/inflect
293
349
  [pluralsingular]: https://pypi.org/project/pluralsingular/
@@ -320,24 +376,27 @@ Benchmark: 100,000 calls across 13 mixed-language words (English, Spanish, Portu
320
376
  | Version | Goal | Status |
321
377
  | --- | --- | --- |
322
378
  | `1.0.0` | English + Spanish, core engine, extensibility API | ✅ Released |
323
- | `1.1.0` | English classical plurals, uncountables, suffix rules | ✅ Released |
324
- | `1.2.0` | English -che words, compound prefixes, whitespace | ✅ Released |
325
- | `1.3.0` | English expansion (Latin/Greek, proper nouns, -o words) | ✅ Released |
326
- | `1.4.0` | Spanish expansion (loanwords, accent restoration, uncountables, idempotency fix) | ✅ Released |
327
379
  | `1.5.0` | Portuguese (`pt`) | ✅ Released |
328
380
  | `1.6.0` | French (`fr`) | ✅ Released |
329
381
  | `1.7.0` | Italian (`it`) | ✅ Released |
330
- | `1.8.3` | Robustness fixes, code quality improvements, expanded lint rules | ✅ Released |
331
382
  | `2.0.0` | Rules restructured into `pluralio/rules/` subpackage, performance optimization | ✅ Released |
332
- | `2.0.1` | CI fixes, hyphenated dedup, docs update, Python 3.14 support | ✅ Released |
333
- | `2.0.2` | Simplified is_plural/is_singular, README fixes, release.yml Python 3.14 | ✅ Released |
334
383
  | `2.1.0` | Esperanto (`eo`) — trivial `-j` plural | ✅ Released |
335
- | `2.1.1` | Bug fixes: Esperanto double-plural, register() cache, _match_case empty target | ✅ Released |
336
- | `2.1.2` | Bug fixes: restore() cache clearing, _match_case digit-only source, register_language redundant call | ✅ Released |
337
- | `2.2.0` | Catalan (`ca`) — Romance, natural fit | 🔜 Planned |
338
- | `2.3.0` | Dutch (`nl`) — Germanic, `-en` / `-s` patterns | 🔜 Planned |
384
+ | `2.2.0` | Utility functions: `join()`, `ordinal()`, `template()` | ✅ Released |
385
+ | `2.3.0` | Catalan (`ca`) — Romance, natural fit | 🔜 Planned |
339
386
  | `3.0.0` | German (`de`) — umlauts + multiple plural patterns | 🔜 Planned |
340
387
 
388
+ ## Changelog
389
+
390
+ See [CHANGELOG.md](CHANGELOG.md) for the full history.
391
+
392
+ ### Recent releases
393
+
394
+ - **2.2.0** — Utility functions: `join()`, `ordinal()`, `template()`
395
+ - **2.1.2** — Bug fixes: `restore()` cache clearing, `_match_case` digit-only source, `register_language` redundant call
396
+ - **2.1.1** — Bug fixes: Esperanto double-plural, `register()` cache, `_match_case` empty target
397
+ - **2.1.0** — Esperanto (`eo`) support
398
+ - **2.0.0** — Rules restructured into `pluralio/rules/` subpackage, performance optimization
399
+
341
400
  ## Contributing
342
401
 
343
402
  Contributions are welcome! Whether it's a bug report, a new language, or a feature suggestion — please read our guides first:
@@ -358,6 +417,10 @@ pip install -e ".[dev]"
358
417
  ruff check pluralio/ tests/
359
418
  mypy pluralio/ tests/
360
419
  pytest
420
+
421
+ # Build docs locally
422
+ pip install -e ".[docs]"
423
+ python -m sphinx -b html docs docs/_build/html
361
424
  ```
362
425
 
363
426
  ## Security
@@ -0,0 +1,15 @@
1
+ Core API
2
+ ========
3
+
4
+ .. automodule:: pluralio.core
5
+ :members: pluralize, singularize
6
+ :show-inheritance:
7
+
8
+ Internal functions
9
+ ------------------
10
+
11
+ .. autofunction:: pluralio.core._match_case
12
+
13
+ .. autofunction:: pluralio.core._apply_rules
14
+
15
+ .. autofunction:: pluralio.core._clear_regex_cache
@@ -0,0 +1,6 @@
1
+ English Rules
2
+ =============
3
+
4
+ .. automodule:: pluralio.rules.en
5
+ :members:
6
+ :show-inheritance:
@@ -0,0 +1,6 @@
1
+ Esperanto Rules
2
+ ===============
3
+
4
+ .. automodule:: pluralio.rules.eo
5
+ :members:
6
+ :show-inheritance:
@@ -0,0 +1,6 @@
1
+ Spanish Rules
2
+ =============
3
+
4
+ .. automodule:: pluralio.rules.es
5
+ :members:
6
+ :show-inheritance:
@@ -0,0 +1,85 @@
1
+ Extensibility API
2
+ =================
3
+
4
+ .. automodule:: pluralio
5
+ :members: add_irregular, add_plural, add_singular, add_uncountable, add_plural_rule, add_singular_rule, register_language, is_plural, is_singular, supported_languages, join, ordinal, template
6
+ :show-inheritance:
7
+ :no-index:
8
+
9
+ Examples
10
+ --------
11
+
12
+ Adding an irregular word pair:
13
+
14
+ .. code-block:: python
15
+
16
+ from pluralio import add_irregular, pluralize, singularize
17
+
18
+ add_irregular("person", "people")
19
+ pluralize("person") # "people"
20
+ singularize("people") # "person"
21
+
22
+ Adding a plural-only mapping:
23
+
24
+ .. code-block:: python
25
+
26
+ from pluralio import add_plural, pluralize
27
+
28
+ add_plural("joven", "jóvenes", lang="es")
29
+ pluralize("joven", lang="es") # "jóvenes"
30
+
31
+ Adding a singular-only mapping (accent restoration):
32
+
33
+ .. code-block:: python
34
+
35
+ from pluralio import add_singular, singularize
36
+
37
+ add_singular("alemanes", "alemán", lang="es")
38
+ singularize("alemanes", lang="es") # "alemán"
39
+
40
+ Marking a word as uncountable:
41
+
42
+ .. code-block:: python
43
+
44
+ from pluralio import add_uncountable, pluralize, singularize
45
+
46
+ add_uncountable("data")
47
+ pluralize("data") # "data"
48
+ singularize("data") # "data"
49
+
50
+ Adding a custom regex rule:
51
+
52
+ .. code-block:: python
53
+
54
+ from pluralio import add_plural_rule, pluralize
55
+
56
+ add_plural_rule(r"us$", "i")
57
+ pluralize("cactus") # "cacti"
58
+
59
+ Registering a new language:
60
+
61
+ .. code-block:: python
62
+
63
+ from pluralio import register_language, pluralize, singularize
64
+
65
+ register_language(
66
+ "xx",
67
+ plural_rules=[(r"$", "s")],
68
+ singular_rules=[(r"s$", "")],
69
+ irregular_plurals={"foo": "foos"},
70
+ uncountable={"bar"},
71
+ )
72
+ pluralize("word", lang="xx") # "words"
73
+ pluralize("foo", lang="xx") # "foos"
74
+ pluralize("bar", lang="xx") # "bar"
75
+
76
+ Checking plural / singular:
77
+
78
+ .. code-block:: python
79
+
80
+ from pluralio import is_plural, is_singular
81
+
82
+ is_plural("cats") # True
83
+ is_singular("cat") # True
84
+ is_plural("gatos", lang="es") # True
85
+ is_singular("gato", lang="es") # True
@@ -0,0 +1,6 @@
1
+ French Rules
2
+ ============
3
+
4
+ .. automodule:: pluralio.rules.fr
5
+ :members:
6
+ :show-inheritance:
@@ -0,0 +1,6 @@
1
+ Italian Rules
2
+ =============
3
+
4
+ .. automodule:: pluralio.rules.it
5
+ :members:
6
+ :show-inheritance:
@@ -0,0 +1,6 @@
1
+ Portuguese Rules
2
+ ================
3
+
4
+ .. automodule:: pluralio.rules.pt
5
+ :members:
6
+ :show-inheritance:
@@ -0,0 +1,6 @@
1
+ Registry API
2
+ ============
3
+
4
+ .. automodule:: pluralio.registry
5
+ :members:
6
+ :show-inheritance: