stouputils 1.16.2__py3-none-any.whl → 1.16.3__py3-none-any.whl

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/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)
 

{stouputils-1.16.2.dist-info → stouputils-1.16.3.dist-info}/METADATA

@@ -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.dist-info → stouputils-1.16.3.dist-info}/RECORD

@@ -21,8 +21,8 @@ stouputils/archive.py,sha256=uDrPFxbY_C8SwUZRH4FWnYSoJKkFWynCx751zP9AHaY,12144
 stouputils/archive.pyi,sha256=Z2BbQAiErRYntv53QC9uf_XPw3tx3Oy73wB0Bbil11c,3246
 stouputils/backup.py,sha256=AE5WKMLiyk0VkRUfhmNfO2EUeUbZY5GTFVIuI5z7axA,20947
 stouputils/backup.pyi,sha256=-SLVykkR5U8479T84zjNPVBNnV193s0zyWjathY2DDA,4923
-stouputils/collections.py,sha256=Zi2OmlPmUPx-isZZpF9xYWU52OtzNqvSHGYM5use0AA,8838
-stouputils/collections.pyi,sha256=J6Sb-8oSVeD1K-j5zNBZo_cP5Bi5NDh2qN4n4QBJIZE,3508
+stouputils/collections.py,sha256=rAIz4acCxGjZkuvUrb3u5laD130TaNKbng3AITMWffY,9851
+stouputils/collections.pyi,sha256=g29fctQAjoJmx-CKh4S6buLSwH2SmivrTGYwc92KqxE,4323
 stouputils/continuous_delivery/__init__.py,sha256=JqPww29xZ-pp6OJDGhUj2dxyV9rgTTMUz0YDDVr9RaA,731
 stouputils/continuous_delivery/__init__.pyi,sha256=_Sz2D10n1CDEyY8qDFwXNKdr01HVxanY4qdq9aN19cc,117
 stouputils/continuous_delivery/cd_utils.py,sha256=fkaHk2V3j66uFAUsM2c_UddNhXW2KAQcrh7jVsH79pU,8594
@@ -136,7 +136,7 @@ stouputils/typing.py,sha256=TwvxrvxhBRkyHkoOpfyXebN13M3xJb8MAjKXiNIWjew,2205
 stouputils/typing.pyi,sha256=U2UmFZausMYpnsUQROQE2JOwHcjx2hKV0rJuOdR57Ew,1341
 stouputils/version_pkg.py,sha256=Jsp-s03L14DkiZ94vQgrlQmaxApfn9DC8M_nzT1SJLk,7014
 stouputils/version_pkg.pyi,sha256=QPvqp1U3QA-9C_CC1dT9Vahv1hXEhstbM7x5uzMZSsQ,755
-stouputils-1.16.2.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
-stouputils-1.16.2.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
-stouputils-1.16.2.dist-info/METADATA,sha256=DllR0l0Z_lBuMSwdvIKSQnoBMp8Yw2yzKbPPMPhzuv0,13890
-stouputils-1.16.2.dist-info/RECORD,,
+stouputils-1.16.3.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
+stouputils-1.16.3.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
+stouputils-1.16.3.dist-info/METADATA,sha256=vrF8jqYs56Ql7uRR7qcSCr17ehLFOwlL9PDL0rwH2VA,13902
+stouputils-1.16.3.dist-info/RECORD,,