Added new functions for returning the "natural" min and max values from an iterable.

Author: domdfcoding

domdf_python_tools/iterative.py

@@ -25,14 +25,18 @@
 #  MA 02110-1301, USA.
 #
 #  chunks from https://stackoverflow.com/a/312464/3092681
-# 		Copyright © 2008 Ned Batchelder
-# 		Licensed under CC-BY-SA
+#  Copyright © 2008 Ned Batchelder
+#  Licensed under CC-BY-SA
 #
 
 # stdlib
 import itertools
 import textwrap
-from typing import Any, Generator, Iterable, Iterator, List, Sequence, Tuple, Type, Union
+from collections import Callable
+from typing import Any, Generator, Iterable, Iterator, List, Optional, Sequence, Tuple, Type, Union
+
+# 3rd party
+from natsort import natsorted, ns
 
 __all__ = [
 		"chunks",
@@ -42,6 +46,8 @@
 		"double_chain",
 		"flatten",
 		"make_tree",
+		"natmin",
+		"natmax",
 		]
 
 
@@ -211,3 +217,37 @@ def make_tree(tree: Branch) -> Iterator[str]:
 		elif isinstance(tree[-1], Iterable):
 			for line in make_tree(tree[-1]):
 				yield textwrap.indent(line, "    ")
+
+
+def natmin(seq: Iterable, key: Optional[Callable] = None, alg: int = ns.DEFAULT):
+	"""
+	Returns the minimum value from ``seq`` when sorted naturally.
+
+	:param seq:
+	:param key: A key used to determine how to sort each element of the iterable.
+		It is **not** applied recursively.
+		The callable should accept a single argument and return a single value.
+	:param alg: This option is used to control which algorithm :mod:`natsort` uses when sorting.
+		For details into these options, please see the :class:`ns` class documentation.
+
+	.. versionadded:: 1.8.0
+	"""
+
+	return natsorted(seq, key=key, alg=alg)[0]
+
+
+def natmax(seq: Iterable, key: Optional[Callable] = None, alg: int = ns.DEFAULT):
+	"""
+	Returns the maximum value from ``seq`` when sorted naturally.
+
+	:param seq:
+	:param key: A key used to determine how to sort each element of the iterable.
+		It is **not** applied recursively.
+		The callable should accept a single argument and return a single value.
+	:param alg: This option is used to control which algorithm :mod:`natsort` uses when sorting.
+		For details into these options, please see the :class:`ns` class documentation.
+
+	.. versionadded:: 1.8.0
+	"""
+
+	return natsorted(seq, key=key, alg=alg)[-1]

domdf_python_tools/paths.py

@@ -782,7 +782,7 @@ def traverse_to_file(base_directory: _P, *filename: PathLike, height: int = -1)
 	:param \*filename: The filename(s) to search for
 	:param height: The maximum height to traverse to.
 
-	.. versionadded:: 1.6.0
+	.. versionadded:: 1.7.0
 	"""
 
 	if not filename:

requirements.txt

@@ -2,6 +2,7 @@ colorama>=0.4.3
 deprecation>=2.1.0
 importlib-metadata>=1.5.0; python_version < "3.8"
 importlib-resources>=3.0.0; python_version < "3.7"
+natsort>=7.1.0
 packaging>=20.4
 pydash>=4.7.4
 typing-extensions>=3.7.4.3

tests/test_iterative.py

@@ -7,6 +7,7 @@
 """
 
 # stdlib
+from random import shuffle
 from types import GeneratorType
 
 # 3rd party
@@ -15,7 +16,17 @@
 from pytest_regressions.file_regression import FileRegressionFixture
 
 # this package
-from domdf_python_tools.iterative import Len, chunks, double_chain, flatten, make_tree, permutations, split_len
+from domdf_python_tools.iterative import (
+		Len,
+		chunks,
+		double_chain,
+		flatten,
+		make_tree,
+		natmax,
+		natmin,
+		permutations,
+		split_len
+		)
 from domdf_python_tools.testing import check_file_regression
 
 
@@ -147,3 +158,37 @@ def test_make_tree(file_regression: FileRegressionFixture):
 		)
 def test_flatten(data, data_regression: DataRegressionFixture):
 	data_regression.check(list(flatten(data)))
+
+
+@pytest.mark.parametrize(
+		"data",
+		[
+				pytest.param([1, 3, 5, 7, 9], id="integers"),
+				pytest.param([1.2, 3.4, 5.6, 7.8, 9.0], id="floats"),
+				pytest.param(['1', '3', '5', '7', '9'], id="numerical_strings"),
+				pytest.param(["1.2", "3.4", "5.6", "7.8", "9.0"], id="float strings"),
+				pytest.param(["0.9", "0.12.4", '1', "2.5"], id="versions"),
+				]
+		)
+def test_natmin(data):
+	orig_data = data[:]
+	for _ in range(5):
+		shuffle(data)
+		assert natmin(data) == orig_data[0]
+
+
+@pytest.mark.parametrize(
+		"data",
+		[
+				pytest.param([1, 3, 5, 7, 9], id="integers"),
+				pytest.param([1.2, 3.4, 5.6, 7.8, 9.0], id="floats"),
+				pytest.param(['1', '3', '5', '7', '9'], id="numerical_strings"),
+				pytest.param(["1.2", "3.4", "5.6", "7.8", "9.0"], id="float strings"),
+				pytest.param(["0.9", "0.12.4", '1', "2.5"], id="versions"),
+				]
+		)
+def test_natmax(data):
+	orig_data = data[:]
+	for _ in range(5):
+		shuffle(data)
+		assert natmax(data) == orig_data[-1]