stouputils 1.16.2__tar.gz → 1.17.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stouputils
-Version: 1.16.2
+Version: 1.17.0
 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
@@ -32,12 +32,14 @@ Requires-Dist: sphinx-design ; extra == 'docs'
 Requires-Dist: sphinx-treeview ; extra == 'docs'
 Requires-Dist: sphinx-breeze-theme ; extra == 'docs'
 Requires-Dist: pydata-sphinx-theme ; extra == 'docs'
+Requires-Dist: redis[hiredis] ; extra == 'redis'
 Requires-Python: >=3.12
 Project-URL: Homepage, https://stoupy51.github.io/stouputils
 Project-URL: Issues, https://github.com/Stoupy51/stouputils/issues
 Project-URL: Source, https://github.com/Stoupy51/stouputils
 Provides-Extra: data-science
 Provides-Extra: docs
+Provides-Extra: redis
 Description-Content-Type: text/markdown
 
 
@@ -93,7 +95,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.17.0}/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.17.0}/pyproject.toml

@@ -8,7 +8,7 @@ module-root = ""
 
 [project]
 name = "stouputils"
-version = "1.16.2"
+version = "1.17.0"
 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"]
@@ -53,6 +53,9 @@ data_science = [
     "scikit-learn",
     "PyWavelets",
 ]
+redis = [
+    "redis[hiredis]",
+]
 
 [project.urls]
 Homepage = "https://stoupy51.github.io/stouputils"

{stouputils-1.16.2 → stouputils-1.17.0}/stouputils/__init__.py

@@ -18,6 +18,7 @@ from .ctx import *
 from .decorators import *
 from .image import *
 from .io import *
+from .lock import *
 from .parallel import *
 from .print import *
 from .typing import *

{stouputils-1.16.2 → stouputils-1.17.0}/stouputils/__init__.pyi

@@ -8,6 +8,7 @@ from .ctx import *
 from .decorators import *
 from .image import *
 from .io import *
+from .lock import *
 from .parallel import *
 from .print import *
 from .typing import *

{stouputils-1.16.2 → stouputils-1.17.0}/stouputils/all_doctests.py

@@ -99,7 +99,7 @@ def launch_tests(root_dir: str, strict: bool = True, pattern: str = "*") -> int:
 		import fnmatch
 		modules_file_paths = [
 			path for path in modules_file_paths
-			if fnmatch.fnmatch(path.split(".")[-1], pattern)
+			if fnmatch.fnmatch(path, pattern)
 		]
 		if not modules_file_paths:
 			raise ValueError(f"No modules matching pattern '{pattern}' found in '{relative_path(root_dir)}'")

{stouputils-1.16.2 → stouputils-1.17.0}/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.17.0}/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 → stouputils-1.17.0}/stouputils/decorators.py

@@ -211,7 +211,7 @@ def timeout(
 	def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
 		# Check if we can use signal-based timeout (Unix only)
 		import os
-		use_signal: bool = os.name != 'nt'  # Not Windows
+		use_signal: bool = os.name != "nt"  # Not Windows
 
 		if use_signal:
 			try:

{stouputils-1.16.2 → stouputils-1.17.0}/stouputils/image.py

@@ -401,7 +401,7 @@ def numpy_to_obj(
 
 	# Apply marching cubes algorithm to extract mesh
 	verts, faces, _, _ = cast(
-        tuple[NDArray[np.floating], NDArray[np.integer], NDArray[np.floating], NDArray[np.floating]],
+        "tuple[NDArray[np.floating], NDArray[np.integer], NDArray[np.floating], NDArray[np.floating]]",
 		measure.marching_cubes(volume, level=threshold, step_size=step_size, allow_degenerate=False) # type: ignore
 	)
 

{stouputils-1.16.2 → stouputils-1.17.0}/stouputils/image.pyi

@@ -3,7 +3,7 @@ from .io import super_open as super_open
 from .print import debug as debug, info as info
 from PIL import Image
 from collections.abc import Callable
-from numpy.typing import NDArray
+from numpy.typing import NDArray as NDArray
 from typing import Any, TypeVar
 
 PIL_Image_or_NDArray = TypeVar('PIL_Image_or_NDArray', bound='Image.Image | NDArray[np.number]')

{stouputils-1.16.2 → stouputils-1.17.0}/stouputils/io.py

@@ -338,7 +338,7 @@ def super_copy(src: str, dst: str, create_dir: bool = True, symlink: bool = Fals
 		src         (str):  The source path
 		dst         (str):  The destination path
 		create_dir  (bool): Whether to create the directory if it doesn't exist (default: True)
-		symlink     (bool): Whether to create a symlink instead of copying (Linux only, default: True)
+		symlink     (bool): Whether to create a symlink instead of copying (Linux only)
 	Returns:
 		str: The destination path
 	"""

{stouputils-1.16.2 → stouputils-1.17.0}/stouputils/io.pyi

@@ -144,7 +144,7 @@ def super_copy(src: str, dst: str, create_dir: bool = True, symlink: bool = Fals
 \t\tsrc         (str):  The source path
 \t\tdst         (str):  The destination path
 \t\tcreate_dir  (bool): Whether to create the directory if it doesn't exist (default: True)
-\t\tsymlink     (bool): Whether to create a symlink instead of copying (Linux only, default: True)
+\t\tsymlink     (bool): Whether to create a symlink instead of copying (Linux only)
 \tReturns:
 \t\tstr: The destination path
 \t"""

stouputils-1.17.0/stouputils/lock/__init__.py

@@ -0,0 +1,36 @@
+""" Inter-process locks implementing First-In-First-Out (FIFO).
+
+Source:
+- https://en.wikipedia.org/wiki/File_locking
+- https://en.wikipedia.org/wiki/Starvation_%28computer_science%29
+- https://en.wikipedia.org/wiki/FIFO_and_LIFO_accounting
+
+Provides three classes:
+
+- LockFifo: basic cross-process lock using filesystem (POSIX via fcntl, Windows via msvcrt).
+- RLockFifo: reentrant per-(process,thread) lock built on top of LockFifo.
+- RedisLockFifo: distributed lock using redis (optional dependency).
+
+Usage
+-----
+>>> import stouputils as stp
+>>> with stp.LockFifo("some_directory/my.lock", timeout=5):
+...     pass
+
+>>> with stp.RLockFifo("some_directory/my_r.lock", timeout=5):
+...     pass
+
+>>> def _redis_example():
+...     with stp.RedisLockFifo("my_redis_lock", timeout=5):
+...         pass
+>>> import os
+>>> if os.name != "nt":
+...     _redis_example()
+"""
+# Imports
+from .base import *
+from .queue import *
+from .re_entrant import *
+from .redis_fifo import *
+from .shared import *
+

stouputils-1.17.0/stouputils/lock/__init__.pyi

@@ -0,0 +1,5 @@
+from .base import *
+from .queue import *
+from .re_entrant import *
+from .redis_fifo import *
+from .shared import *