Add class for phrases containing multiple linked plurals.

Author: domdfcoding

doc-source/api/words.rst

@@ -107,11 +107,22 @@ Functions
 	:html: 31/100
 
 .. automodulesumm:: domdf_python_tools.words
-	:autosummary-members: alpha_sort,get_words_list,get_random_word,as_text,word_join,Plural
+	:autosummary-members: alpha_sort,get_words_list,get_random_word,as_text,word_join
 
 .. autofunction:: domdf_python_tools.words.alpha_sort
 .. autofunction:: domdf_python_tools.words.as_text
 .. autofunction:: domdf_python_tools.words.get_words_list
 .. autofunction:: domdf_python_tools.words.get_random_word
 .. autofunction:: domdf_python_tools.words.word_join
+
+Classes
+-------------
+
+.. autosummary-widths:: 8/16
+	:html: 31/100
+
+.. automodulesumm:: domdf_python_tools.words
+	:autosummary-members: Plural,PluralPhrase
+
 .. autoclass:: domdf_python_tools.words.Plural
+.. autonamedtuple:: domdf_python_tools.words.PluralPhrase

domdf_python_tools/words.py

@@ -43,7 +43,7 @@
 from gettext import ngettext
 from reprlib import recursive_repr
 from string import ascii_lowercase, ascii_uppercase
-from typing import Any, Dict, Iterable, List, Optional
+from typing import Any, Dict, Iterable, List, NamedTuple, Optional, Tuple
 
 # this package
 import domdf_python_tools
@@ -75,6 +75,7 @@
 		"CR",
 		"LF",
 		"Plural",
+		"PluralPhrase",
 		]
 
 ascii_digits = "0123456789"
@@ -615,3 +616,72 @@ def __repr__(self):
 		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)})"
+
+
+@prettify_docstrings
+class PluralPhrase(NamedTuple):
+	"""
+	Represents a phrase which varies depending on a numerical count.
+
+	.. versionadded:: 3.3.0
+
+	:param template: The phrase template.
+	:param words: The words to insert into the template.
+
+	For example, consider the phase::
+
+		The proposed changes are to ...
+
+	The "phrase template" would be:
+
+	.. code-block:: python
+
+		"The proposed {} {} to ..."
+
+	and the two words to insert are:
+
+	.. code-block:: python
+
+		Plural("change", "changes")
+		Plural("is", "are")
+
+	The phrase is constructed as follows:
+
+	.. code-block:: python
+
+		>>> phrase = PluralPhrase(
+		...     "The proposed {} {} to ...",
+		...     (Plural("change", "changes"), Plural("is", "are"))
+		... )
+		>>> phrase(1)
+		'The proposed change is to ...'
+		>>> phrase(2)
+		'The proposed changes are to ...'
+
+	The phrase template can use any `valid syntax`_ for :meth:`str.format`,
+	except for keyword arguments. The exception if the keyword ``n``,
+	which is replaced with the count (e.g. ``2``) passed in when the phrase is constructed.
+	For example:
+
+	.. code-block:: python
+
+		>>> phrase2 = PluralPhrase("The farmer has {n} {0}.", (Plural("cow", "cows"), ))
+		>>> phrase2(2)
+		'The farmer has 2 cows.'
+
+	.. _valid syntax: https://docs.python.org/3/library/string.html#formatstrings
+
+	"""
+
+	template: str
+	words: Tuple[Plural, ...]
+
+	def __call__(self, n: int) -> str:  # noqa: TYP004  # TODO
+		"""
+		Construct the phrase based on the value of ``n``.
+
+		:param n:
+		"""
+
+		plural_words = [x(n) for x in self.words]
+		return self.template.format(*plural_words, n=n)

tests/test_words.py

@@ -12,7 +12,14 @@
 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, Plural, alpha_sort, get_random_word, get_words_list
+from domdf_python_tools.words import (
+		DOUBLESTRUCK_LETTERS,
+		Plural,
+		PluralPhrase,
+		alpha_sort,
+		get_random_word,
+		get_words_list
+		)
 
 
 @pytest.mark.parametrize(
@@ -167,3 +174,37 @@ def test_plural():
 
 	assert repr(cow) == "Plural('cow', 'cows')"
 	assert repr(glass) == "Plural('glass', 'glasses')"
+
+
+def test_pluralphrase():
+	phrase1 = PluralPhrase("The proposed {} {} to ...", (Plural("change", "changes"), Plural("is", "are")))
+	phrase2 = PluralPhrase("The farmer has {n} {0}.", (Plural("cow", "cows"), ))
+	phrase3 = PluralPhrase("The proposed {1} {0} to ...", (Plural("is", "are"), Plural("change", "changes")))
+	phrase4 = PluralPhrase(
+			"The farmer has {n} {0}. The {0} {1} brown.", (Plural("cow", "cows"), Plural("is", "are"))
+			)
+	n = 1
+	assert phrase1(n) == "The proposed change is to ..."
+	assert phrase2(n) == "The farmer has 1 cow."
+	assert phrase3(n) == "The proposed change is to ..."
+	assert phrase4(n) == "The farmer has 1 cow. The cow is brown."
+
+	n = 2
+	assert phrase1(n) == "The proposed changes are to ..."
+	assert phrase2(n) == "The farmer has 2 cows."
+	assert phrase3(n) == "The proposed changes are to ..."
+	assert phrase4(n) == "The farmer has 2 cows. The cows are brown."
+
+	n = 3
+	assert phrase1(n) == "The proposed changes are to ..."
+	assert phrase2(n) == "The farmer has 3 cows."
+	assert phrase3(n) == "The proposed changes are to ..."
+	assert phrase4(n) == "The farmer has 3 cows. The cows are brown."
+
+	phrase1_repr = "PluralPhrase(template='The proposed {} {} to ...', words=(Plural('change', 'changes'), Plural('is', 'are')))"
+	assert repr(phrase1) == phrase1_repr
+	assert repr(phrase2) == "PluralPhrase(template='The farmer has {n} {0}.', words=(Plural('cow', 'cows'),))"
+	phrase3_repr = "PluralPhrase(template='The proposed {1} {0} to ...', words=(Plural('is', 'are'), Plural('change', 'changes')))"
+	assert repr(phrase3) == phrase3_repr
+	phrase4_repr = "PluralPhrase(template='The farmer has {n} {0}. The {0} {1} brown.', words=(Plural('cow', 'cows'), Plural('is', 'are')))"
+	assert repr(phrase4) == phrase4_repr