stouputils 1.16.2__tar.gz → 1.16.3__tar.gz

{stouputils-1.16.2 → stouputils-1.16.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stouputils
-Version: 1.16.2
+Version: 1.16.3
 Summary: Stouputils is a collection of utility modules designed to simplify and enhance the development process. It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers, and many more.
 Keywords: utilities,tools,helpers,development,python
 Author: Stoupy51
@@ -93,7 +93,7 @@ Start now by installing the package: `pip install stouputils`.<br>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.io.html">io.py</a>            <span class="comment"># 💾 Utilities for file management <span class="paren">(json_dump, json_load, csv_dump, csv_load, read_file, super_copy, super_open, clean_path, ...)</span></span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.parallel.html">parallel.py</a>      <span class="comment"># 🔀 Utility functions for parallel processing <span class="paren">(multiprocessing, multithreading, run_in_subprocess)</span></span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.image.html">image.py</a>         <span class="comment"># 🖼️ Little utilities for image processing <span class="paren">(image_resize, auto_crop, numpy_to_gif, numpy_to_obj)</span></span>
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.collections.html">collections.py</a>   <span class="comment"># 🧰 Utilities for collection manipulation <span class="paren">(unique_list, sort_dict_keys, upsert_in_dataframe, array_to_disk)</span></span>
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.collections.html">collections.py</a>   <span class="comment"># 🧰 Utilities for collection manipulation <span class="paren">(unique_list, at_least_n, sort_dict_keys, upsert_in_dataframe, array_to_disk)</span></span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.typing.html">typing.py</a>        <span class="comment"># 📝 Utilities for typing enhancements <span class="paren">(IterAny, JsonDict, JsonList, ..., convert_to_serializable)</span></span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.all_doctests.html">all_doctests.py</a>  <span class="comment"># ✅ Run all doctests for all modules in a given directory <span class="paren">(launch_tests, test_module_with_progress)</span></span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.backup.html">backup.py</a>        <span class="comment"># 💾 Utilities for backup management <span class="paren">(delta backup, consolidate)</span></span>

{stouputils-1.16.2 → stouputils-1.16.3}/README.md

@@ -51,7 +51,7 @@ Start now by installing the package: `pip install stouputils`.<br>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.io.html">io.py</a>            <span class="comment"># 💾 Utilities for file management <span class="paren">(json_dump, json_load, csv_dump, csv_load, read_file, super_copy, super_open, clean_path, ...)</span></span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.parallel.html">parallel.py</a>      <span class="comment"># 🔀 Utility functions for parallel processing <span class="paren">(multiprocessing, multithreading, run_in_subprocess)</span></span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.image.html">image.py</a>         <span class="comment"># 🖼️ Little utilities for image processing <span class="paren">(image_resize, auto_crop, numpy_to_gif, numpy_to_obj)</span></span>
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.collections.html">collections.py</a>   <span class="comment"># 🧰 Utilities for collection manipulation <span class="paren">(unique_list, sort_dict_keys, upsert_in_dataframe, array_to_disk)</span></span>
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.collections.html">collections.py</a>   <span class="comment"># 🧰 Utilities for collection manipulation <span class="paren">(unique_list, at_least_n, sort_dict_keys, upsert_in_dataframe, array_to_disk)</span></span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.typing.html">typing.py</a>        <span class="comment"># 📝 Utilities for typing enhancements <span class="paren">(IterAny, JsonDict, JsonList, ..., convert_to_serializable)</span></span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.all_doctests.html">all_doctests.py</a>  <span class="comment"># ✅ Run all doctests for all modules in a given directory <span class="paren">(launch_tests, test_module_with_progress)</span></span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.backup.html">backup.py</a>        <span class="comment"># 💾 Utilities for backup management <span class="paren">(delta backup, consolidate)</span></span>

{stouputils-1.16.2 → stouputils-1.16.3}/pyproject.toml

@@ -8,7 +8,7 @@ module-root = ""
 
 [project]
 name = "stouputils"
-version = "1.16.2"
+version = "1.16.3"
 description = "Stouputils is a collection of utility modules designed to simplify and enhance the development process. It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers, and many more."
 readme = "README.md"
 keywords = ["utilities", "tools", "helpers", "development", "python"]

{stouputils-1.16.2 → stouputils-1.16.3}/stouputils/collections.py

@@ -2,6 +2,7 @@
 This module provides utilities for collection manipulation:
 
 - unique_list: Remove duplicates from a list while preserving order using object id, hash or str
+- at_least_n: Check if at least n elements in an iterable satisfy a given predicate
 - sort_dict_keys: Sort dictionary keys using a given order list (ascending or descending)
 - upsert_in_dataframe: Insert or update a row in a Polars DataFrame based on primary keys
 - array_to_disk: Easily handle large numpy arrays on disk using zarr for efficient storage and access.
@@ -15,7 +16,7 @@ import atexit
 import os
 import shutil
 import tempfile
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
 from typing import TYPE_CHECKING, Any, Literal, TypeVar
 
 # Lazy imports for typing
@@ -77,6 +78,38 @@ def unique_list[T](list_to_clean: Iterable[T], method: Literal["id", "hash", "st
 	# Return the cleaned list
 	return result
 
+
+def at_least_n(iterable: Iterable[T], predicate: Callable[[T], bool], n: int) -> bool:
+	""" Return True if at least n elements in iterable satisfy predicate.
+	It's like the built-in any() but for at least n matches.
+
+	Stops iterating as soon as n matches are found (short-circuit evaluation).
+
+	Args:
+		iterable	(Iterable[T]):			The iterable to check.
+		predicate	(Callable[[T], bool]):	The predicate to apply to items.
+		n			(int):					Minimum number of matches required.
+
+	Returns:
+		bool: True if at least n elements satisfy predicate, otherwise False.
+
+	Examples:
+		>>> at_least_n([1, 2, 3, 4, *[i for i in range(5, int(1e5))]], lambda x: x % 2 == 0, 2)
+		True
+		>>> at_least_n([1, 3, 5, 7], lambda x: x % 2 == 0, 1)
+		False
+	"""
+	if n <= 0:
+		return True
+	count: int = 0
+	for item in iterable:
+		if predicate(item):
+			count += 1
+			if count >= n:
+				return True
+	return False
+
+
 def sort_dict_keys[T](dictionary: dict[T, Any], order: list[T], reverse: bool = False) -> dict[T, Any]:
 	""" Sort dictionary keys using a given order list (reverse optional)
 

{stouputils-1.16.2 → stouputils-1.16.3}/stouputils/collections.pyi

@@ -1,6 +1,6 @@
 import polars as pl
 import zarr
-from collections.abc import Iterable
+from collections.abc import Callable as Callable, Iterable
 from numpy.typing import NDArray as NDArray
 from typing import Any, Literal, TypeVar
 
@@ -31,6 +31,26 @@ def unique_list[T](list_to_clean: Iterable[T], method: Literal['id', 'hash', 'st
 \t\t>>> unique_list([s1, s2, s1, s1, s3, s2, s3], method="str")
 \t\t[{1, 2, 3}, {2, 3, 4}]
 \t'''
+def at_least_n(iterable: Iterable[T], predicate: Callable[[T], bool], n: int) -> bool:
+    """ Return True if at least n elements in iterable satisfy predicate.
+\tIt's like the built-in any() but for at least n matches.
+
+\tStops iterating as soon as n matches are found (short-circuit evaluation).
+
+\tArgs:
+\t\titerable\t(Iterable[T]):\t\t\tThe iterable to check.
+\t\tpredicate\t(Callable[[T], bool]):\tThe predicate to apply to items.
+\t\tn\t\t\t(int):\t\t\t\t\tMinimum number of matches required.
+
+\tReturns:
+\t\tbool: True if at least n elements satisfy predicate, otherwise False.
+
+\tExamples:
+\t\t>>> at_least_n([1, 2, 3, 4, *[i for i in range(5, int(1e5))]], lambda x: x % 2 == 0, 2)
+\t\tTrue
+\t\t>>> at_least_n([1, 3, 5, 7], lambda x: x % 2 == 0, 1)
+\t\tFalse
+\t"""
 def sort_dict_keys[T](dictionary: dict[T, Any], order: list[T], reverse: bool = False) -> dict[T, Any]:
     ''' Sort dictionary keys using a given order list (reverse optional)