feat: add conjunction parameter to natural_list

Author: SAY-5

src/humanize/lists.py

@@ -9,10 +9,11 @@
 __all__ = ["natural_list"]
 
 
-def natural_list(items: list[Any]) -> str:
+def natural_list(items: list[Any], *, conjunction: str = "and") -> str:
     """Natural list.
 
-    Convert a list of items into a human-readable string with commas and 'and'.
+    Convert a list of items into a human-readable string with commas and a
+    conjunction.
 
     Examples:
         >>> natural_list(["one", "two", "three"])
@@ -21,16 +22,22 @@ def natural_list(items: list[Any]) -> str:
         'one and two'
         >>> natural_list(["one"])
         'one'
+        >>> natural_list(["one", "two", "three"], conjunction="or")
+        'one, two or three'
 
     Args:
         items (list): An iterable of items.
+        conjunction (str): The word used to join the last item, defaults to 'and'.
 
     Returns:
-        str: A string with commas and 'and' in the right places.
+        str: A string with commas and the conjunction in the right places.
     """
     if len(items) == 1:
         return str(items[0])
     elif len(items) == 2:
-        return f"{str(items[0])} and {str(items[1])}"
+        return f"{str(items[0])} {conjunction} {str(items[1])}"
     else:
-        return ", ".join([str(item) for item in items[:-1]]) + f" and {str(items[-1])}"
+        return (
+            ", ".join([str(item) for item in items[:-1]])
+            + f" {conjunction} {str(items[-1])}"
+        )

tests/test_lists.py

@@ -21,3 +21,19 @@ def test_natural_list(
     test_args: list[str] | list[int] | list[str | int], expected: str
 ) -> None:
     assert humanize.natural_list(*test_args) == expected
+
+
+@pytest.mark.parametrize(
+    "items, conjunction, expected",
+    [
+        (["one", "two", "three"], "or", "one, two or three"),
+        (["one", "two"], "or", "one or two"),
+        (["one"], "or", "one"),
+        (["one", "two", "three"], "and also", "one, two and also three"),
+        (["one", "two", "three"], "and", "one, two and three"),
+    ],
+)
+def test_natural_list_conjunction(
+    items: list[str], conjunction: str, expected: str
+) -> None:
+    assert humanize.natural_list(items, conjunction=conjunction) == expected