pluralio 2.2.0__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.2.0 → pluralio-2.3.0}/.github/ISSUE_TEMPLATE/bug_report.md +1 -1
  2. {pluralio-2.2.0 → pluralio-2.3.0}/CHANGELOG.md +53 -0
  3. {pluralio-2.2.0 → pluralio-2.3.0}/CONTRIBUTING.md +7 -1
  4. {pluralio-2.2.0 → pluralio-2.3.0}/PKG-INFO +18 -13
  5. {pluralio-2.2.0 → pluralio-2.3.0}/README.md +14 -10
  6. {pluralio-2.2.0 → pluralio-2.3.0}/SECURITY.md +2 -2
  7. {pluralio-2.2.0 → pluralio-2.3.0}/docs/conf.py +16 -2
  8. {pluralio-2.2.0 → pluralio-2.3.0}/docs/cookbook.rst +8 -8
  9. {pluralio-2.2.0 → pluralio-2.3.0}/docs/index.rst +4 -3
  10. {pluralio-2.2.0 → pluralio-2.3.0}/docs/languages.rst +22 -22
  11. {pluralio-2.2.0 → pluralio-2.3.0}/docs/usage.rst +6 -2
  12. {pluralio-2.2.0 → pluralio-2.3.0}/pluralio/__init__.py +12 -7
  13. {pluralio-2.2.0 → pluralio-2.3.0}/pluralio/core.py +11 -7
  14. pluralio-2.3.0/pluralio/py.typed +0 -0
  15. {pluralio-2.2.0 → pluralio-2.3.0}/pluralio/registry.py +38 -24
  16. {pluralio-2.2.0 → pluralio-2.3.0}/pluralio/rules/__init__.py +1 -1
  17. {pluralio-2.2.0 → pluralio-2.3.0}/pluralio/rules/en.py +0 -2
  18. {pluralio-2.2.0 → pluralio-2.3.0}/pluralio/rules/es.py +1 -2
  19. {pluralio-2.2.0 → pluralio-2.3.0}/pluralio/rules/fr.py +26 -8
  20. {pluralio-2.2.0 → pluralio-2.3.0}/pluralio/rules/it.py +25 -15
  21. {pluralio-2.2.0 → pluralio-2.3.0}/pluralio/rules/pt.py +12 -3
  22. {pluralio-2.2.0 → pluralio-2.3.0}/pluralio/utils.py +6 -1
  23. {pluralio-2.2.0 → pluralio-2.3.0}/pyproject.toml +3 -2
  24. pluralio-2.3.0/tests/__init__.py +0 -0
  25. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_core.py +18 -0
  26. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_cross_edge_cases.py +2 -2
  27. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_fr_edge_cases.py +3 -0
  28. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_fr_plurals.py +10 -0
  29. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_it_plurals.py +33 -6
  30. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_pt_plurals.py +6 -0
  31. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_pt_singles.py +3 -0
  32. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_registry.py +9 -0
  33. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_utils.py +7 -0
  34. {pluralio-2.2.0 → pluralio-2.3.0}/.github/ISSUE_TEMPLATE/feature_request.md +0 -0
  35. {pluralio-2.2.0 → pluralio-2.3.0}/.github/pull_request_template.md +0 -0
  36. {pluralio-2.2.0 → pluralio-2.3.0}/.github/workflows/ci.yml +0 -0
  37. {pluralio-2.2.0 → pluralio-2.3.0}/.github/workflows/docs.yml +0 -0
  38. {pluralio-2.2.0 → pluralio-2.3.0}/.github/workflows/release.yml +0 -0
  39. {pluralio-2.2.0 → pluralio-2.3.0}/.gitignore +0 -0
  40. {pluralio-2.2.0 → pluralio-2.3.0}/CODE_OF_CONDUCT.md +0 -0
  41. {pluralio-2.2.0 → pluralio-2.3.0}/LICENSE +0 -0
  42. /pluralio-2.2.0/pluralio/py.typed → /pluralio-2.3.0/docs/_static/.gitkeep +0 -0
  43. /pluralio-2.2.0/tests/__init__.py → /pluralio-2.3.0/docs/_templates/.gitkeep +0 -0
  44. {pluralio-2.2.0 → pluralio-2.3.0}/docs/api/core.rst +0 -0
  45. {pluralio-2.2.0 → pluralio-2.3.0}/docs/api/en.rst +0 -0
  46. {pluralio-2.2.0 → pluralio-2.3.0}/docs/api/eo.rst +0 -0
  47. {pluralio-2.2.0 → pluralio-2.3.0}/docs/api/es.rst +0 -0
  48. {pluralio-2.2.0 → pluralio-2.3.0}/docs/api/extensibility.rst +0 -0
  49. {pluralio-2.2.0 → pluralio-2.3.0}/docs/api/fr.rst +0 -0
  50. {pluralio-2.2.0 → pluralio-2.3.0}/docs/api/it.rst +0 -0
  51. {pluralio-2.2.0 → pluralio-2.3.0}/docs/api/pt.rst +0 -0
  52. {pluralio-2.2.0 → pluralio-2.3.0}/docs/api/registry.rst +0 -0
  53. {pluralio-2.2.0 → pluralio-2.3.0}/docs/api/rules.rst +0 -0
  54. {pluralio-2.2.0 → pluralio-2.3.0}/docs/api/utils.rst +0 -0
  55. {pluralio-2.2.0 → pluralio-2.3.0}/docs/changelog.rst +0 -0
  56. {pluralio-2.2.0 → pluralio-2.3.0}/pluralio/rules/eo.py +0 -0
  57. {pluralio-2.2.0 → pluralio-2.3.0}/tests/conftest.py +0 -0
  58. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_en_edge_cases.py +0 -0
  59. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_en_plurals.py +0 -0
  60. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_en_singles.py +0 -0
  61. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_eo_plurals.py +0 -0
  62. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_eo_singles.py +0 -0
  63. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_es_edge_cases.py +0 -0
  64. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_es_plurals.py +0 -0
  65. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_es_singles.py +0 -0
  66. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_fr_singles.py +0 -0
  67. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_inspect.py +0 -0
  68. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_it_edge_cases.py +0 -0
  69. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_it_singles.py +0 -0
  70. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_property.py +0 -0
  71. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_pt_edge_cases.py +0 -0
  72. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_registry_isolation.py +0 -0
  73. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_round_trip.py +0 -0
  74. {pluralio-2.2.0 → pluralio-2.3.0}/tests/test_version.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
 
@@ -2,6 +2,27 @@
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
+
5
26
  ## [2.2.0] - 2025-07-13
6
27
 
7
28
  ### Added
@@ -447,3 +468,35 @@
447
468
  - CI workflow (lint + type check + test on Python 3.10–3.13)
448
469
  - Release workflow (trusted publishing to PyPI)
449
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,7 +1,7 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: pluralio
3
- Version: 2.2.0
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
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
19
19
  Classifier: Programming Language :: Python :: 3.11
20
20
  Classifier: Programming Language :: Python :: 3.12
21
21
  Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
22
23
  Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
24
  Classifier: Typing :: Typed
24
25
  Requires-Python: >=3.10
@@ -41,7 +42,7 @@ Description-Content-Type: text/markdown
41
42
 
42
43
  **Pluralization and singularization for Python**
43
44
 
44
- English · Spanish · Portuguese · French · Italian · Esperanto · Zero dependencies · Type-safe · Extensible
45
+ 6 languages · 7,280 tests · Zero dependencies · Type-safe · Extensible at runtime
45
46
 
46
47
  [![PyPI version](https://img.shields.io/pypi/v/pluralio.svg?style=flat-square)](https://pypi.org/project/pluralio/)
47
48
  [![Python versions](https://img.shields.io/pypi/pyversions/pluralio.svg?style=flat-square)](https://pypi.org/project/pluralio/)
@@ -61,7 +62,7 @@ English · Spanish · Portuguese · French · Italian · Esperanto · Zero depen
61
62
 
62
63
  - **Zero dependencies** — pure Python standard library, nothing else to install
63
64
  - **Type-safe** — full type hints, `py.typed` marker included (PEP 561)
64
- - **100% test coverage** — 7,233 tests, every line is verified
65
+ - **100% test coverage** — 7,280 tests, every line is verified
65
66
  - **6 languages** — English, Spanish, Portuguese, French, Italian, Esperanto
66
67
  - **Extensible at runtime** — add irregulars, rules, uncountables, or entire languages without touching source code
67
68
  - **Utility functions** — `join()`, `ordinal()`, `template()` for common UI tasks
@@ -277,6 +278,8 @@ Every word goes through a **three-step priority chain**:
277
278
  | `LanguageRules` | Dataclass holding all rules for a language. |
278
279
  | `register(rules)` | Register a `LanguageRules` instance. |
279
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()`. |
280
283
 
281
284
  ## Extending rules
282
285
 
@@ -363,7 +366,7 @@ How does pluralio compare to other Python inflection libraries?
363
366
  | Hyphenated words | ✅ | ❌ | ❌ | ❌ |
364
367
  | Unicode normalization (NFC/NFD) | ✅ | ❌ | ❌ | ❌ |
365
368
  | Idempotency (ES) | ✅ | ❌ | ❌ | ❌ |
366
- | Uncountables (ES) | ✅ ~87 | ❌ | ❌ | ❌ |
369
+ | Uncountables (ES) | ✅ ~92 | ❌ | ❌ | ❌ |
367
370
  | Accent restoration (ES) | ✅ | ❌ | ⚠️ Partial | ❌ |
368
371
  | Runtime extensibility | ✅ | ❌ | ❌ | ✅ |
369
372
  | Add custom languages | ✅ | ❌ | ✅ | ❌ |
@@ -373,7 +376,7 @@ How does pluralio compare to other Python inflection libraries?
373
376
  | Python 3.10+ | ✅ | ✅ | ✅ | ✅ |
374
377
  | Test coverage | 100% | ~95% | ~60% | ~70% |
375
378
  | Number to words | ❌ | ✅ | ❌ | ❌ |
376
- | Ordinals (`1` → `1st`) | ❌ | ✅ | ❌ | ❌ |
379
+ | Ordinals (`1` → `1st`) | ✅ | ✅ | ❌ | ❌ |
377
380
  | Indefinite articles (`a`/`an`) | ❌ | ✅ | ❌ | ❌ |
378
381
  | Join words into a list | ✅ | ✅ | ❌ | ❌ |
379
382
  | Present participle | ❌ | ✅ | ❌ | ❌ |
@@ -402,11 +405,11 @@ Benchmark: 100,000 calls across 13 mixed-language words (English, Spanish, Portu
402
405
  | Language | Code | Regex rules | Irregulars | Uncountables | Status |
403
406
  | --- | --- | --- | --- | --- | --- |
404
407
  | English | `en` | 7 + 22 | 684 | 219 | ✅ Complete |
405
- | Spanish | `es` | 9 + 8 | 352 + 81 extra singles | 92 | ✅ Complete |
406
- | Portuguese | `pt` | 8 + 13 | 388 + 88 extra singles | 88 | ✅ Complete |
407
- | French | `fr` | 6 + 4 | 104 + 27 extra singles | 81 | ✅ Complete |
408
- | Italian | `it` | 19 + 12 | 239 + 0 extra singles | 144 | ✅ Complete |
409
- | 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 |
410
413
 
411
414
  ## Roadmap
412
415
 
@@ -419,7 +422,8 @@ Benchmark: 100,000 calls across 13 mixed-language words (English, Spanish, Portu
419
422
  | `2.0.0` | Rules restructured into `pluralio/rules/` subpackage, performance optimization | ✅ Released |
420
423
  | `2.1.0` | Esperanto (`eo`) — trivial `-j` plural | ✅ Released |
421
424
  | `2.2.0` | Utility functions: `join()`, `ordinal()`, `template()` | ✅ Released |
422
- | `2.3.0` | Catalan (`ca`) — Romance, natural fit | 🔜 Planned |
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 |
423
427
  | `3.0.0` | German (`de`) — umlauts + multiple plural patterns | 🔜 Planned |
424
428
 
425
429
  ## Changelog
@@ -428,6 +432,7 @@ See [CHANGELOG.md](CHANGELOG.md) for the full history.
428
432
 
429
433
  ### Recent releases
430
434
 
435
+ - **2.3.0** — Bug fixes: language-code normalization, rule corrections (FR/IT/PT), doctests
431
436
  - **2.2.0** — Utility functions: `join()`, `ordinal()`, `template()`
432
437
  - **2.1.2** — Bug fixes: `restore()` cache clearing, `_match_case` digit-only source, `register_language` redundant call
433
438
  - **2.1.1** — Bug fixes: Esperanto double-plural, `register()` cache, `_match_case` empty target
@@ -4,7 +4,7 @@
4
4
 
5
5
  **Pluralization and singularization for Python**
6
6
 
7
- English · Spanish · Portuguese · French · Italian · Esperanto · Zero dependencies · Type-safe · Extensible
7
+ 6 languages · 7,280 tests · Zero dependencies · Type-safe · Extensible at runtime
8
8
 
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/)
@@ -24,7 +24,7 @@ English · Spanish · Portuguese · French · Italian · Esperanto · Zero depen
24
24
 
25
25
  - **Zero dependencies** — pure Python standard library, nothing else to install
26
26
  - **Type-safe** — full type hints, `py.typed` marker included (PEP 561)
27
- - **100% test coverage** — 7,233 tests, every line is verified
27
+ - **100% test coverage** — 7,280 tests, every line is verified
28
28
  - **6 languages** — English, Spanish, Portuguese, French, Italian, Esperanto
29
29
  - **Extensible at runtime** — add irregulars, rules, uncountables, or entire languages without touching source code
30
30
  - **Utility functions** — `join()`, `ordinal()`, `template()` for common UI tasks
@@ -240,6 +240,8 @@ Every word goes through a **three-step priority chain**:
240
240
  | `LanguageRules` | Dataclass holding all rules for a language. |
241
241
  | `register(rules)` | Register a `LanguageRules` instance. |
242
242
  | `get_rules(lang)` | Retrieve rules for a language (raises `ValueError` if not found). |
243
+ | `snapshot()` | Deep-copy the current registry state (test isolation). |
244
+ | `restore(state)` | Restore a registry state returned by `snapshot()`. |
243
245
 
244
246
  ## Extending rules
245
247
 
@@ -326,7 +328,7 @@ How does pluralio compare to other Python inflection libraries?
326
328
  | Hyphenated words | ✅ | ❌ | ❌ | ❌ |
327
329
  | Unicode normalization (NFC/NFD) | ✅ | ❌ | ❌ | ❌ |
328
330
  | Idempotency (ES) | ✅ | ❌ | ❌ | ❌ |
329
- | Uncountables (ES) | ✅ ~87 | ❌ | ❌ | ❌ |
331
+ | Uncountables (ES) | ✅ ~92 | ❌ | ❌ | ❌ |
330
332
  | Accent restoration (ES) | ✅ | ❌ | ⚠️ Partial | ❌ |
331
333
  | Runtime extensibility | ✅ | ❌ | ❌ | ✅ |
332
334
  | Add custom languages | ✅ | ❌ | ✅ | ❌ |
@@ -336,7 +338,7 @@ How does pluralio compare to other Python inflection libraries?
336
338
  | Python 3.10+ | ✅ | ✅ | ✅ | ✅ |
337
339
  | Test coverage | 100% | ~95% | ~60% | ~70% |
338
340
  | Number to words | ❌ | ✅ | ❌ | ❌ |
339
- | Ordinals (`1` → `1st`) | ❌ | ✅ | ❌ | ❌ |
341
+ | Ordinals (`1` → `1st`) | ✅ | ✅ | ❌ | ❌ |
340
342
  | Indefinite articles (`a`/`an`) | ❌ | ✅ | ❌ | ❌ |
341
343
  | Join words into a list | ✅ | ✅ | ❌ | ❌ |
342
344
  | Present participle | ❌ | ✅ | ❌ | ❌ |
@@ -365,11 +367,11 @@ Benchmark: 100,000 calls across 13 mixed-language words (English, Spanish, Portu
365
367
  | Language | Code | Regex rules | Irregulars | Uncountables | Status |
366
368
  | --- | --- | --- | --- | --- | --- |
367
369
  | English | `en` | 7 + 22 | 684 | 219 | ✅ Complete |
368
- | Spanish | `es` | 9 + 8 | 352 + 81 extra singles | 92 | ✅ Complete |
369
- | Portuguese | `pt` | 8 + 13 | 388 + 88 extra singles | 88 | ✅ Complete |
370
- | French | `fr` | 6 + 4 | 104 + 27 extra singles | 81 | ✅ Complete |
371
- | Italian | `it` | 19 + 12 | 239 + 0 extra singles | 144 | ✅ Complete |
372
- | Esperanto | `eo` | 2 + 2 | 0 | 33 | ✅ Complete |
370
+ | Spanish | `es` | 9 + 8 | 354 | 92 | ✅ Complete |
371
+ | Portuguese | `pt` | 9 + 13 | 393 | 88 | ✅ Complete |
372
+ | French | `fr` | 6 + 4 | 100 | 92 | ✅ Complete |
373
+ | Italian | `it` | 19 + 12 | 249 | 126 | ✅ Complete |
374
+ | Esperanto | `eo` | 4 + 2 | 0 | 39 | ✅ Complete |
373
375
 
374
376
  ## Roadmap
375
377
 
@@ -382,7 +384,8 @@ Benchmark: 100,000 calls across 13 mixed-language words (English, Spanish, Portu
382
384
  | `2.0.0` | Rules restructured into `pluralio/rules/` subpackage, performance optimization | ✅ Released |
383
385
  | `2.1.0` | Esperanto (`eo`) — trivial `-j` plural | ✅ Released |
384
386
  | `2.2.0` | Utility functions: `join()`, `ordinal()`, `template()` | ✅ Released |
385
- | `2.3.0` | Catalan (`ca`) — Romance, natural fit | 🔜 Planned |
387
+ | `2.3.0` | Bug fixes: language-code normalization, rule corrections (FR/IT/PT), docs | ✅ Released |
388
+ | `2.4.0` | Catalan (`ca`) — Romance, natural fit | 🔜 Planned |
386
389
  | `3.0.0` | German (`de`) — umlauts + multiple plural patterns | 🔜 Planned |
387
390
 
388
391
  ## Changelog
@@ -391,6 +394,7 @@ See [CHANGELOG.md](CHANGELOG.md) for the full history.
391
394
 
392
395
  ### Recent releases
393
396
 
397
+ - **2.3.0** — Bug fixes: language-code normalization, rule corrections (FR/IT/PT), doctests
394
398
  - **2.2.0** — Utility functions: `join()`, `ordinal()`, `template()`
395
399
  - **2.1.2** — Bug fixes: `restore()` cache clearing, `_match_case` digit-only source, `register_language` redundant call
396
400
  - **2.1.1** — Bug fixes: Esperanto double-plural, `register()` cache, `_match_case` empty target
@@ -4,8 +4,8 @@
4
4
 
5
5
  | Version | Supported |
6
6
  | --- | --- |
7
- | 0.1.x | Yes |
8
- | < 0.1 | No |
7
+ | 2.x | Yes |
8
+ | < 2.0 | No |
9
9
 
10
10
  ## Reporting a vulnerability
11
11
 
@@ -7,9 +7,11 @@ from pathlib import Path
7
7
 
8
8
  sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
9
9
 
10
+ import pluralio # noqa: E402
11
+
10
12
  project = "pluralio"
11
13
  author = "Mathias Paulenko"
12
- release = "2.2.0"
14
+ release = pluralio.__version__
13
15
 
14
16
  extensions = [
15
17
  "sphinx.ext.autodoc",
@@ -56,5 +58,17 @@ intersphinx_mapping = {
56
58
  }
57
59
 
58
60
  doctest_global_setup = """
59
- import pluralio
61
+ from pluralio import (
62
+ add_irregular, add_plural, add_plural_rule, add_singular,
63
+ add_singular_rule, add_uncountable, get_rules, is_plural,
64
+ is_singular, join, ordinal, pluralize, register_language,
65
+ singularize, supported_languages, template,
66
+ )
67
+ from pluralio.core import _match_case
68
+ from pluralio.registry import LanguageRules, register, restore, snapshot
69
+
70
+ try:
71
+ restore(_PRISTINE_REGISTRY)
72
+ except NameError:
73
+ _PRISTINE_REGISTRY = snapshot()
60
74
  """
@@ -35,14 +35,14 @@ Multi-language support
35
35
 
36
36
  from pluralio import pluralize, supported_languages
37
37
 
38
- word = "libro"
38
+ word = "estudio"
39
39
  for lang in supported_languages():
40
40
  if lang in ("en", "eo", "es", "it"):
41
41
  print(f"{lang}: {pluralize(word, lang=lang)}")
42
- # en: libros
43
- # eo: libroj
44
- # es: libros
45
- # it: libri
42
+ # en: estudios
43
+ # eo: estudioj
44
+ # es: estudios
45
+ # it: estudi
46
46
 
47
47
  Adding domain-specific vocabulary
48
48
  ---------------------------------
@@ -67,7 +67,7 @@ Marking words as uncountable
67
67
  from pluralio import add_uncountable, pluralize, singularize
68
68
 
69
69
  # Domain-specific uncountables
70
- for word in ("feedback", "metadata", "metadata"):
70
+ for word in ("feedback", "metadata", "upstream"):
71
71
  add_uncountable(word)
72
72
 
73
73
  pluralize("feedback") # "feedback"
@@ -118,8 +118,8 @@ Test isolation with snapshot/restore
118
118
 
119
119
  state = snapshot()
120
120
  try:
121
- add_irregular("foo", "foos")
122
- assert pluralize("foo") == "foos"
121
+ add_irregular("foo", "fooos")
122
+ assert pluralize("foo") == "fooos"
123
123
  finally:
124
124
  restore(state)
125
125
  # After restore, "foo" is back to normal rules
@@ -1,10 +1,11 @@
1
1
  pluralio
2
2
  ========
3
3
 
4
- Pluralization and singularization for Python — zero dependencies, type-safe,
5
- extensible.
4
+ Pluralization and singularization for Python — 6 languages, zero dependencies,
5
+ type-safe, extensible.
6
6
 
7
- Supports English, Spanish, Portuguese, French, Italian, and Esperanto.
7
+ Supports English, Spanish, Portuguese, French, Italian, and Esperanto with
8
+ 100% test coverage across 7,280 tests.
8
9
 
9
10
  .. image:: https://img.shields.io/pypi/v/pluralio.svg
10
11
  :target: https://pypi.org/project/pluralio/
@@ -26,32 +26,32 @@ registered automatically when you ``import pluralio``.
26
26
  * - Spanish
27
27
  - ``es``
28
28
  - 9 + 8
29
- - 352 + 81
29
+ - 354
30
30
  - 92
31
31
  - Complete
32
32
  * - Portuguese
33
33
  - ``pt``
34
- - 8 + 13
35
- - 388 + 88
34
+ - 9 + 13
35
+ - 393
36
36
  - 88
37
37
  - Complete
38
38
  * - French
39
39
  - ``fr``
40
40
  - 6 + 4
41
- - 104 + 27
42
- - 81
41
+ - 100
42
+ - 92
43
43
  - Complete
44
44
  * - Italian
45
45
  - ``it``
46
46
  - 19 + 12
47
- - 239
48
- - 144
47
+ - 249
48
+ - 126
49
49
  - Complete
50
50
  * - Esperanto
51
51
  - ``eo``
52
52
  - 4 + 2
53
53
  - 0
54
- - 33
54
+ - 39
55
55
  - Complete
56
56
 
57
57
  Language-specific notes
@@ -60,10 +60,10 @@ Language-specific notes
60
60
  English (``en``)
61
61
  ~~~~~~~~~~~~~~~~
62
62
 
63
- - 684 irregulars covering Latin/Greek plurals, compound words, and
64
- special cases.
65
- - Regex rules handle ``-s``, ``-es``, ``-ies``, ``-ves``, ``-oes``,
66
- ``-oes``, and classical plurals (``-i``, ``-a``, ``-ae``, ``-ina``).
63
+ - 684 irregulars covering Latin/Greek plurals (``-i``, ``-a``,
64
+ ``-ae``, ``-ina``), compound words, and special cases.
65
+ - Regex rules handle ``-s``, ``-es``, ``-ies``, ``-ves``, and
66
+ ``-oes`` endings.
67
67
  - 219 uncountables including mass nouns, non-noun words, and
68
68
  invariable terms.
69
69
 
@@ -72,14 +72,11 @@ Spanish (``es``)
72
72
 
73
73
  - Accent restoration: singulars that lose an accent in the plural are
74
74
  handled via irregular mappings (e.g. ``joven`` → ``jóvenes``).
75
- - 81 extra singular-only entries for accent restoration that cannot
76
- be derived from regex rules.
77
75
  - 92 uncountables.
78
76
 
79
77
  Portuguese (``pt``)
80
78
  ~~~~~~~~~~~~~~~~~~~
81
79
 
82
- - 88 extra singular-only entries for accent restoration.
83
80
  - Hyphenated compound handling for verb+noun constructions
84
81
  (``quebra-mar`` → ``quebra-mares``).
85
82
 
@@ -87,8 +84,11 @@ French (``fr``)
87
84
  ~~~~~~~~~~~~~~~
88
85
 
89
86
  - Both segments of hyphenated compounds are pluralized, skipping
90
- function words (articles, prepositions).
91
- - ``-al`` → ``-aux``, ``-ail`` → ``-aux``, ``-euil`` → ``-euils``.
87
+ function words (articles, prepositions) and invariable compounds
88
+ (``porte-monnaie``).
89
+ - ``-al`` → ``-aux``, ``-au``/``-eau`` → ``-aux``/``-eaux``,
90
+ ``-eu`` → ``-eux``; the ``-als``/``-ails``/``-eus``/``-ous``
91
+ exceptions live in the irregular tables.
92
92
 
93
93
  Italian (``it``)
94
94
  ~~~~~~~~~~~~~~~~
@@ -103,7 +103,7 @@ Esperanto (``eo``)
103
103
  - Simplest pluralization system: ``-j`` suffix for nominative plural,
104
104
  ``-jn`` for accusative plural.
105
105
  - Zero irregulars — the language is perfectly regular by design.
106
- - 33 uncountables: pronouns, correlatives, and particles.
106
+ - 39 uncountables: pronouns, correlatives, and particles.
107
107
 
108
108
  Roadmap
109
109
  -------
@@ -114,11 +114,11 @@ Roadmap
114
114
  * - Version
115
115
  - Goal
116
116
  - Status
117
- * - ``2.2.0``
118
- - Catalan (``ca``)
119
- - Planned
120
117
  * - ``2.3.0``
121
- - Dutch (``nl``)
118
+ - Bug fixes and documentation corrections
119
+ - Released
120
+ * - ``2.4.0``
121
+ - Catalan (``ca``)
122
122
  - Planned
123
123
  * - ``3.0.0``
124
124
  - German (``de``)
@@ -51,14 +51,18 @@ The output mirrors the casing of the input:
51
51
  Hyphenated words
52
52
  ----------------
53
53
 
54
- Only the head noun is pluralized (first segment by default, last segment
55
- for known prefixes):
54
+ For English, Spanish, and Portuguese only the head noun is pluralized
55
+ (first segment by default, last segment for known prefixes like
56
+ ``forget-`` or ``quebra-``). French and Italian pluralize every noun
57
+ segment, skipping articles, prepositions, and invariable compounds:
56
58
 
57
59
  .. code-block:: python
58
60
 
59
61
  pluralize("mother-in-law") # "mothers-in-law"
60
62
  pluralize("forget-me-not") # "forget-me-nots"
63
+ pluralize("quebra-mar", lang="pt") # "quebra-mares"
61
64
  pluralize("café-théâtre", lang="fr") # "cafés-théâtres"
65
+ pluralize("porte-monnaie", lang="fr") # "porte-monnaie" (invariable)
62
66
 
63
67
  Whitespace preservation
64
68
  -----------------------
@@ -30,11 +30,12 @@ Supported languages (built-in):
30
30
 
31
31
  .. note::
32
32
  Language rules are registered as a side effect of importing this
33
- package. Always use ``import pluralio`` (or
34
- ``from pluralio import pluralize``) rather than importing from
35
- submodules directly, e.g. avoid ``from pluralio.core import pluralize``,
36
- because the latter bypasses registration and will raise
37
- ``ValueError`` for any non-default language.
33
+ package. Any normal import of a submodule (e.g.
34
+ ``from pluralio.core import pluralize``) also executes the package
35
+ ``__init__``, so registration always happens. Only file-level
36
+ loading outside the package (e.g. ``importlib`` on a bare path)
37
+ bypasses registration and would raise ``ValueError`` for any
38
+ non-default language.
38
39
 
39
40
  Example:
40
41
  >>> import pluralio
@@ -286,6 +287,7 @@ def register_language(
286
287
  uncountable: Set of invariable words. Normalized to lowercase.
287
288
 
288
289
  Example:
290
+ >>> state = snapshot()
289
291
  >>> register_language(
290
292
  ... "fr",
291
293
  ... plural_rules=[(r"$", "s")],
@@ -301,6 +303,7 @@ def register_language(
301
303
  'cheval'
302
304
  >>> pluralize("information", lang="fr")
303
305
  'information'
306
+ >>> restore(state)
304
307
  """
305
308
  plurals = {k.lower(): v.lower() for k, v in (irregular_plurals or {}).items()}
306
309
  singles = {k.lower(): v.lower() for k, v in (irregular_singles or {}).items()}
@@ -351,10 +354,11 @@ def is_plural(word: str, lang: str = "en") -> bool:
351
354
  """
352
355
  if not isinstance(word, str):
353
356
  raise TypeError(f"word must be str, got {type(word).__name__}")
357
+ rules = get_rules(lang)
354
358
  stripped = unicodedata.normalize("NFC", word.strip())
355
359
  if not stripped:
356
360
  return False
357
- if stripped.lower() in get_rules(lang).uncountable:
361
+ if stripped.lower() in rules.uncountable:
358
362
  return True
359
363
  return singularize(stripped, lang=lang).lower() != stripped.lower()
360
364
 
@@ -390,9 +394,10 @@ def is_singular(word: str, lang: str = "en") -> bool:
390
394
  """
391
395
  if not isinstance(word, str):
392
396
  raise TypeError(f"word must be str, got {type(word).__name__}")
397
+ rules = get_rules(lang)
393
398
  stripped = unicodedata.normalize("NFC", word.strip())
394
399
  if not stripped:
395
400
  return False
396
- if stripped.lower() in get_rules(lang).uncountable:
401
+ if stripped.lower() in rules.uncountable:
397
402
  return True
398
403
  return pluralize(stripped, lang=lang).lower() != stripped.lower()
@@ -158,7 +158,7 @@ def _apply_rules(
158
158
  The transformed word with original casing preserved.
159
159
  """
160
160
  result = _apply_regex_to_word(lower, rules.code, is_plural)
161
- if not result or result == lower:
161
+ if result == lower:
162
162
  return word
163
163
  return _match_case(word, result)
164
164
 
@@ -207,6 +207,8 @@ _FR_HYPHEN_SKIP: frozenset[str] = frozenset({
207
207
  "pour", "par", "sur", "sous", "avec", "sans", "dans",
208
208
  # Fixed parts in certain compounds
209
209
  "vie", "ciel",
210
+ # Invariable prefixes (vice-président → vice-présidents)
211
+ "vice",
210
212
  })
211
213
 
212
214
  # Italian compound words: both nouns are pluralized, but function words
@@ -348,14 +350,16 @@ def _transform(
348
350
  """
349
351
  if not isinstance(word, str):
350
352
  raise TypeError(f"word must be str, got {type(word).__name__}")
353
+ rules = get_rules(lang)
351
354
  leading, stripped, trailing = _split_whitespace(word)
352
355
  if not stripped:
353
356
  return word
354
357
  if not stripped.isascii():
355
358
  stripped = unicodedata.normalize("NFC", stripped)
356
- if is_plural and count is not None and count == 1:
359
+ if is_plural and count is not None and (
360
+ count == 1 or (isinstance(count, str) and count.strip() == "1")
361
+ ):
357
362
  return leading + stripped + trailing
358
- rules = get_rules(lang)
359
363
  lower = stripped if stripped.islower() else stripped.lower()
360
364
  if lower in rules.uncountable:
361
365
  return leading + stripped + trailing
@@ -391,10 +395,10 @@ def pluralize(word: str, lang: str = "en", count: int | None = None) -> str:
391
395
  Args:
392
396
  word: The singular word to pluralize.
393
397
  lang: ISO 639-1 language code. Defaults to ``"en"``.
394
- count: Optional integer count. When ``count == 1`` the word
395
- is returned unchanged (singular form). Any other value
396
- (including ``0``, negative numbers, and ``None``) produces
397
- the plural form.
398
+ count: Optional count. When ``count == 1`` (or the string
399
+ ``"1"``) the word is returned unchanged (singular form).
400
+ Any other value (including ``0``, negative numbers, and
401
+ ``None``) produces the plural form.
398
402
 
399
403
  Returns:
400
404
  The plural form of ``word``, with original casing preserved.
File without changes