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

stouputils/all_doctests.py

@@ -154,7 +154,7 @@ def launch_tests(root_dir: str, strict: bool = True, pattern: str = "*") -> int:
 	return total_failed
 
 
-def test_module_with_progress(module: ModuleType, separator: str) -> TestResults:
+def test_module_with_progress(module: "ModuleType", separator: str) -> "TestResults":
 	""" Test a module with testmod and measure the time taken with progress printing.
 
 	Args:
@@ -165,7 +165,7 @@ def test_module_with_progress(module: ModuleType, separator: str) -> TestResults
 	"""
 	from doctest import testmod
 	@measure_time(message=f"Testing module '{module.__name__}' {separator}took")
-	def internal() -> TestResults:
+	def internal() -> "TestResults":
 		return testmod(m=module)
 	return internal()
 

stouputils/applications/automatic_docs.py

@@ -141,10 +141,6 @@ def get_sphinx_conf_content(
 # Imports
 import sys
 from typing import Any
-import typing
-
-# Set TYPE_CHECKING to avoid import issues during documentation generation
-typing.TYPE_CHECKING = True
 
 # Add project_dir directory to Python path for module discovery
 sys.path.insert(0, "{parent_of_project_dir}")

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/image.py

@@ -28,7 +28,7 @@ PIL_Image_or_NDArray = TypeVar("PIL_Image_or_NDArray", bound="Image.Image | NDAr
 def image_resize[PIL_Image_or_NDArray](
 	image: PIL_Image_or_NDArray,
 	max_result_size: int,
-	resampling: Image.Resampling | None = None,
+	resampling: "Image.Resampling | None" = None,
 	min_or_max: Callable[[int, int], int] = max,
 	return_type: type[PIL_Image_or_NDArray] | str = "same",
 	keep_aspect_ratio: bool = True,
@@ -123,8 +123,8 @@ def image_resize[PIL_Image_or_NDArray](
 
 def auto_crop[PIL_Image_or_NDArray](
 	image: PIL_Image_or_NDArray,
-	mask: NDArray[np.bool_] | None = None,
-	threshold: int | float | Callable[[NDArray[np.number]], int | float] | None = None,
+	mask: "NDArray[np.bool_] | None" = None,
+	threshold: int | float | Callable[["NDArray[np.number]"], int | float] | None = None,
 	return_type: type[PIL_Image_or_NDArray] | str = "same",
 	contiguous: bool = True,
 ) -> Any:
@@ -207,7 +207,7 @@ def auto_crop[PIL_Image_or_NDArray](
 
 	# Convert to numpy array and store original type
 	original_was_pil: bool = isinstance(image, Image.Image)
-	image_array: NDArray[np.number] = np.array(image) if original_was_pil else image
+	image_array: NDArray[np.number] = np.array(image) if original_was_pil else image # type: ignore
 
 	# Create mask if not provided
 	if mask is None:
@@ -263,7 +263,7 @@ def auto_crop[PIL_Image_or_NDArray](
 
 def numpy_to_gif(
 	path: str,
-	array: NDArray[np.integer | np.floating | np.bool_],
+	array: "NDArray[np.integer | np.floating | np.bool_]",
 	duration: int = 100,
 	loop: int = 0,
 	mkdir: bool = True,
@@ -344,7 +344,7 @@ def numpy_to_gif(
 
 def numpy_to_obj(
 	path: str,
-	array: NDArray[np.integer | np.floating | np.bool_],
+	array: "NDArray[np.integer | np.floating | np.bool_]",
 	threshold: float = 0.5,
 	step_size: int = 1,
 	pad_array: bool = True,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stouputils
-Version: 1.16.1
+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.1.dist-info → stouputils-1.16.3.dist-info}/RECORD

@@ -3,11 +3,11 @@ stouputils/__init__.pyi,sha256=as5qRu9FfJdJwb_DheDTq6hA5y4UfIFgPwItNfPHMwU,374
 stouputils/__main__.py,sha256=MA3jjc1yL8_0Z9oB55BMqrFq1ot_-e5rNqSxFQGsMzs,2910
 stouputils/_deprecated.py,sha256=Bcq6YjdM9Rk9Vq-WMhc_tuEbPORX6U8HAJ9Vh-VIWTA,1478
 stouputils/_deprecated.pyi,sha256=6-8YsftJd2fRAdBLsysc6jf-uA8V2wiqkiFAbdfWfJQ,664
-stouputils/all_doctests.py,sha256=317v-B4kqf_8lkrw6ul1ZGBgZ75CYIqoDn7kG5k8qyc,6322
+stouputils/all_doctests.py,sha256=PPh081zySANsZme52Bg3DwMqVlQpjrdgO13GctsCtFo,6328
 stouputils/all_doctests.pyi,sha256=R3FRKaQv3sTZbxLvvsChHZZKygVMhmL6pqrYYLqvZCg,2017
 stouputils/applications/__init__.py,sha256=dbjwZt8PZF043KoJSItqCpH32FtRxN5sgV-8Q2b1l10,457
 stouputils/applications/__init__.pyi,sha256=DTYq2Uqq1uLzCMkFByjRqdtREA-9SaQnp4QpgmCEPFg,56
-stouputils/applications/automatic_docs.py,sha256=CG63RiPyHTqYCCcYJnOumVAOoATS0wAOblVmo5L2Ay4,20683
+stouputils/applications/automatic_docs.py,sha256=_6XbCuVi2EiSdkiPZ7XHr5mUGh2ZORev8Vd0tJDb0ug,20561
 stouputils/applications/automatic_docs.pyi,sha256=sfFXpVE5y5Z907HEjKzpZ_9zM34d-jKNDQCdMx7E-9s,6189
 stouputils/applications/upscaler/__init__.py,sha256=8vrca93OYu5GQJrZO1GvnAbptzyhu_L0DnP3M9unlA0,1142
 stouputils/applications/upscaler/__init__.pyi,sha256=VSp6Tq09ATCTdfnjhbDnu7lblaLLGbCNi-E22jYxa88,67
@@ -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
@@ -111,7 +111,7 @@ stouputils/data_science/scripts/routine.py,sha256=FkTLzmcdm_qUp69D-dPAKJm2RfXZZL
 stouputils/data_science/utils.py,sha256=HFXI2RQZ53RbBOn_4Act2bi0z4xQlTtsuR5Am80v9JU,11084
 stouputils/decorators.py,sha256=miZ8r2g8VhmQs2_knkKuUagdQabriZe7w0fCOEB69Nw,21838
 stouputils/decorators.pyi,sha256=vbPRsvox4dotqcln3StgE6iZ1cWCOeAn56M9zMpdw2U,10948
-stouputils/image.py,sha256=uGBweT-60JEn4SK5nVAxqiVI4Ijh4YyG_d5uXjXgtCY,16603
+stouputils/image.py,sha256=xojXhpXGee6SjvyJ77f7GBQiLskWAW6RQhB_ZhpVpAk,16628
 stouputils/image.pyi,sha256=B7aypF1kHsEHHzwTnbcINLam32H4iJJBRxsegwt2n78,8455
 stouputils/installer/__init__.py,sha256=DBwI9w3xvw0NR_jDMxmURwPi1F79kPLe7EuNjmrxW_U,502
 stouputils/installer/__init__.pyi,sha256=ZB-8frAUOW-0pCEJL-e2AdbFodivv46v3EBYwEXCxRo,117
@@ -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.1.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
-stouputils-1.16.1.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
-stouputils-1.16.1.dist-info/METADATA,sha256=v2w5_MQbls9c4YUR3tgoJgqCq1fUfCGg50gpG68JPqw,13890
-stouputils-1.16.1.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,,