Added new Plural class.

Author: domdfcoding

doc-source/api/words.rst

@@ -65,3 +65,5 @@
 .. autofunction:: domdf_python_tools.words.as_text
 
 .. autofunction:: domdf_python_tools.words.word_join
+
+.. autoclass:: domdf_python_tools.words.Plural

domdf_python_tools/words.py

@@ -35,8 +35,11 @@
 
 # stdlib
 import functools
+import platform
 import random
 import re
+from gettext import ngettext
+from reprlib import recursive_repr
 from string import ascii_lowercase, ascii_uppercase
 from typing import Any, Dict, Iterable, List, Optional
 
@@ -68,8 +71,12 @@
 		"TAB",
 		"CR",
 		"LF",
+		"Plural",
 		]
 
+# this package
+from domdf_python_tools.doctools import prettify_docstrings
+
 ascii_digits = "0123456789"
 """
 ASCII numbers.
@@ -560,3 +567,59 @@ def word_join(
 
 .. versionadded:: 1.3.0
 """
+
+_docs = domdf_python_tools.__docs
+
+
+@prettify_docstrings
+class Plural(functools.partial):
+	"""
+	Represents a word as its singular and plural.
+
+	.. versionadded:: 2.0.0
+
+	:param singular: The singular form of the word.
+	:param plural: The plural form of the word.
+
+	.. code-block:: python
+
+		>>> cow = Plural("cow", "cows")
+		>>> n = 1
+		>>> print(f"The farmer has {n} {cow(n)}.")
+		The farmer has 1 cow.
+		>>> n = 2
+		>>> print(f"The farmer has {n} {cow(n)}.")
+		The farmer has 2 cows.
+		>>> n = 3
+		>>> print(f"The farmer has {n} {cow(n)}.")
+		The farmer has 3 cows.
+	"""
+
+	if _docs:  # pragma: no cover
+
+		def __init__(self, singular: str, plural: str):
+			pass
+
+		def __call__(self, n: int) -> str:
+			"""
+			Returns either the singular or plural form of the word depending on the value of ``n``.
+
+			:param n:
+			"""
+
+	if platform.python_implementation() == "PyPy":
+
+		def __init__(self, singular: str, plural: str):
+			super().__init__(ngettext, singular, plural)
+	else:
+
+		def __new__(cls, singular: str, plural: str):
+			return super().__new__(cls, ngettext, singular, plural)
+
+	@recursive_repr()
+	def __repr__(self):
+		qualname = type(self).__qualname__
+		args = []
+		args.extend(repr(x) for x in self.args)
+		args.extend(f"{k}={v!r}" for (k, v) in self.keywords.items())
+		return f"{qualname}({', '.join(args)})"

tests/test_words.py

@@ -11,7 +11,7 @@
 from domdf_python_tools import words
 from domdf_python_tools.paths import PathPlus
 from domdf_python_tools.stringlist import StringList
-from domdf_python_tools.words import DOUBLESTRUCK_LETTERS, alpha_sort, get_random_word, get_words_list
+from domdf_python_tools.words import DOUBLESTRUCK_LETTERS, Plural, alpha_sort, get_random_word, get_words_list
 
 
 @pytest.mark.parametrize(
@@ -145,3 +145,23 @@ def test_as_text(value, expects):
 		)
 def test_word_join(args, kwargs, expects):
 	assert words.word_join(*args, **kwargs) == expects
+
+
+def test_plural():
+	cow = Plural("cow", "cows")
+	glass = Plural("glass", "glasses")
+
+	n = 1
+	assert f"The farmer has {n} {cow(n)}." == "The farmer has 1 cow."
+	assert f"The bar has {n} {glass(n)}." == "The bar has 1 glass."
+
+	n = 2
+	assert f"The farmer has {n} {cow(n)}." == "The farmer has 2 cows."
+	assert f"The bar has {n} {glass(n)}." == "The bar has 2 glasses."
+
+	n = 3
+	assert f"The farmer has {n} {cow(n)}." == "The farmer has 3 cows."
+	assert f"The bar has {n} {glass(n)}." == "The bar has 3 glasses."
+
+	assert repr(cow) == "Plural('cow', 'cows')"
+	assert repr(glass) == "Plural('glass', 'glasses')"