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.
- pluralio-2.2.0/.github/workflows/docs.yml +46 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/.gitignore +2 -1
- {pluralio-2.1.2 → pluralio-2.2.0}/CHANGELOG.md +12 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/PKG-INFO +90 -22
- {pluralio-2.1.2 → pluralio-2.2.0}/README.md +84 -21
- pluralio-2.2.0/docs/api/core.rst +15 -0
- pluralio-2.2.0/docs/api/en.rst +6 -0
- pluralio-2.2.0/docs/api/eo.rst +6 -0
- pluralio-2.2.0/docs/api/es.rst +6 -0
- pluralio-2.2.0/docs/api/extensibility.rst +85 -0
- pluralio-2.2.0/docs/api/fr.rst +6 -0
- pluralio-2.2.0/docs/api/it.rst +6 -0
- pluralio-2.2.0/docs/api/pt.rst +6 -0
- pluralio-2.2.0/docs/api/registry.rst +6 -0
- pluralio-2.2.0/docs/api/rules.rst +20 -0
- pluralio-2.2.0/docs/api/utils.rst +7 -0
- pluralio-2.2.0/docs/changelog.rst +5 -0
- pluralio-2.2.0/docs/conf.py +60 -0
- pluralio-2.2.0/docs/cookbook.rst +199 -0
- pluralio-2.2.0/docs/index.rst +83 -0
- pluralio-2.2.0/docs/languages.rst +125 -0
- pluralio-2.2.0/docs/usage.rst +95 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/__init__.py +7 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/core.py +11 -10
- {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/registry.py +10 -0
- pluralio-2.2.0/pluralio/utils.py +167 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/pyproject.toml +11 -1
- pluralio-2.2.0/tests/test_utils.py +362 -0
- pluralio-2.2.0/tests/test_version.py +44 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/.github/ISSUE_TEMPLATE/bug_report.md +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/.github/ISSUE_TEMPLATE/feature_request.md +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/.github/pull_request_template.md +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/.github/workflows/ci.yml +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/.github/workflows/release.yml +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/CODE_OF_CONDUCT.md +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/CONTRIBUTING.md +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/LICENSE +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/SECURITY.md +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/py.typed +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/__init__.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/en.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/eo.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/es.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/fr.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/it.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/pluralio/rules/pt.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/__init__.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/conftest.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_core.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_cross_edge_cases.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_en_edge_cases.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_en_plurals.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_en_singles.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_eo_plurals.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_eo_singles.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_es_edge_cases.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_es_plurals.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_es_singles.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_fr_edge_cases.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_fr_plurals.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_fr_singles.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_inspect.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_it_edge_cases.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_it_plurals.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_it_singles.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_property.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_pt_edge_cases.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_pt_plurals.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_pt_singles.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_registry.py +0 -0
- {pluralio-2.1.2 → pluralio-2.2.0}/tests/test_registry_isolation.py +0 -0
- {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
|
|
@@ -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.
|
|
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
|
[](https://pypi.org/project/pluralio/)
|
|
42
47
|
[](https://pypi.org/project/pluralio/)
|
|
43
48
|
[](https://github.com/MathiasPaulenko/pluralio/actions/workflows/ci.yml)
|
|
44
|
-
[](https://github.com/MathiasPaulenko/pluralio)
|
|
45
50
|
[](LICENSE)
|
|
46
51
|
[](https://github.com/astral-sh/ruff)
|
|
47
52
|
[](https://github.com/python/mypy)
|
|
48
53
|
[](https://pypi.org/project/pluralio/)
|
|
54
|
+
[](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
|
-
- **
|
|
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
|
-
# ──
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
pluralio.pluralize(
|
|
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 |
|
|
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.
|
|
368
|
-
| `2.
|
|
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
|
[](https://pypi.org/project/pluralio/)
|
|
10
10
|
[](https://pypi.org/project/pluralio/)
|
|
11
11
|
[](https://github.com/MathiasPaulenko/pluralio/actions/workflows/ci.yml)
|
|
12
|
-
[](https://github.com/MathiasPaulenko/pluralio)
|
|
13
13
|
[](LICENSE)
|
|
14
14
|
[](https://github.com/astral-sh/ruff)
|
|
15
15
|
[](https://github.com/python/mypy)
|
|
16
16
|
[](https://pypi.org/project/pluralio/)
|
|
17
|
+
[](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
|
-
- **
|
|
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
|
-
# ──
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
pluralio.pluralize(
|
|
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 |
|
|
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.
|
|
336
|
-
| `2.
|
|
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,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
|