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

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/__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/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/collections.py

@@ -17,7 +17,7 @@ import os
 import shutil
 import tempfile
 from collections.abc import Callable, Iterable
-from typing import TYPE_CHECKING, Any, Literal, TypeVar
+from typing import TYPE_CHECKING, Any, Literal
 
 # Lazy imports for typing
 if TYPE_CHECKING:
@@ -26,9 +26,6 @@ if TYPE_CHECKING:
 	import zarr  # pyright: ignore[reportMissingTypeStubs]
 	from numpy.typing import NDArray
 
-# Typing
-T = TypeVar("T")
-
 # Functions
 def unique_list[T](list_to_clean: Iterable[T], method: Literal["id", "hash", "str"] = "str") -> list[T]:
 	""" Remove duplicates from the list while keeping the order using ids, hash, or str
@@ -79,7 +76,7 @@ def unique_list[T](list_to_clean: Iterable[T], method: Literal["id", "hash", "st
 	return result
 
 
-def at_least_n(iterable: Iterable[T], predicate: Callable[[T], bool], n: int) -> bool:
+def at_least_n[T](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.
 

stouputils/collections.pyi

@@ -2,9 +2,7 @@ import polars as pl
 import zarr
 from collections.abc import Callable as Callable, Iterable
 from numpy.typing import NDArray as NDArray
-from typing import Any, Literal, TypeVar
-
-T = TypeVar('T')
+from typing import Any, Literal
 
 def unique_list[T](list_to_clean: Iterable[T], method: Literal['id', 'hash', 'str'] = 'str') -> list[T]:
     ''' Remove duplicates from the list while keeping the order using ids, hash, or str
@@ -31,7 +29,7 @@ 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:
+def at_least_n[T](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.
 

stouputils/continuous_delivery/stubs.py

@@ -29,7 +29,7 @@ def generate_stubs(
 	try:
 		from mypy.stubgen import main as stubgen_main
 	except ImportError as e:
-		raise ImportError("mypy is required for array_to_disk function. Please install it via 'pip install mypy'.") from e
+		raise ImportError("mypy is required for generate_stubs function. Please install it via 'pip install mypy'.") from e
 	try:
 		stubgen_main(["-p", package_name, *extra_args.split()])
 		return 0

stouputils/ctx.py

@@ -20,13 +20,11 @@ import sys
 import time
 from collections.abc import Callable
 from contextlib import AbstractAsyncContextManager, AbstractContextManager
-from typing import IO, Any, TextIO, TypeVar
+from typing import IO, Any, TextIO
 
 from .io import super_open
 from .print import TeeMultiOutput, debug
 
-# Type variable for context managers
-T = TypeVar("T")
 
 # Abstract base class for context managers supporting both sync and async usage
 class AbstractBothContextManager[T](AbstractContextManager[T], AbstractAsyncContextManager[T]):

stouputils/ctx.pyi

@@ -3,9 +3,7 @@ from .io import super_open as super_open
 from .print import TeeMultiOutput as TeeMultiOutput, debug as debug
 from collections.abc import Callable as Callable
 from contextlib import AbstractAsyncContextManager, AbstractContextManager
-from typing import Any, IO, TextIO, TypeVar
-
-T = TypeVar('T')
+from typing import Any, IO, TextIO
 
 class AbstractBothContextManager[T](AbstractContextManager[T], AbstractAsyncContextManager[T], metaclass=abc.ABCMeta):
     """ Abstract base class for context managers that support both synchronous and asynchronous usage. """

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

@@ -12,7 +12,7 @@ See stouputils.data_science.data_processing for lots more image processing utili
 # Imports
 import os
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any, TypeVar, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from .io import super_open
 from .print import debug, info
@@ -22,15 +22,13 @@ if TYPE_CHECKING:
 	from numpy.typing import NDArray
 	from PIL import Image
 
-PIL_Image_or_NDArray = TypeVar("PIL_Image_or_NDArray", bound="Image.Image | NDArray[np.number]")
-
 # Functions
-def image_resize[PIL_Image_or_NDArray](
-	image: PIL_Image_or_NDArray,
+def image_resize[T: "Image.Image | NDArray[np.number]"](
+	image: T,
 	max_result_size: int,
 	resampling: "Image.Resampling | None" = None,
 	min_or_max: Callable[[int, int], int] = max,
-	return_type: type[PIL_Image_or_NDArray] | str = "same",
+	return_type: type[T] | str = "same",
 	keep_aspect_ratio: bool = True,
 ) -> Any:
 	""" Resize an image while preserving its aspect ratio by default.
@@ -121,11 +119,11 @@ def image_resize[PIL_Image_or_NDArray](
 		return new_image
 
 
-def auto_crop[PIL_Image_or_NDArray](
-	image: PIL_Image_or_NDArray,
+def auto_crop[T: "Image.Image | NDArray[np.number]"](
+	image: T,
 	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",
+	return_type: type[T] | str = "same",
 	contiguous: bool = True,
 ) -> Any:
 	""" Automatically crop an image to remove zero or uniform regions.
@@ -401,7 +399,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/image.pyi

@@ -3,12 +3,10 @@ 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 typing import Any, TypeVar
+from numpy.typing import NDArray as NDArray
+from typing import Any
 
-PIL_Image_or_NDArray = TypeVar('PIL_Image_or_NDArray', bound='Image.Image | NDArray[np.number]')
-
-def image_resize[PIL_Image_or_NDArray](image: PIL_Image_or_NDArray, max_result_size: int, resampling: Image.Resampling | None = None, min_or_max: Callable[[int, int], int] = ..., return_type: type[PIL_Image_or_NDArray] | str = 'same', keep_aspect_ratio: bool = True) -> Any:
+def image_resize[T: Image.Image | NDArray[np.number]](image: T, max_result_size: int, resampling: Image.Resampling | None = None, min_or_max: Callable[[int, int], int] = ..., return_type: type[T] | str = 'same', keep_aspect_ratio: bool = True) -> Any:
     ''' Resize an image while preserving its aspect ratio by default.
 \tScales the image so that its largest dimension equals max_result_size.
 
@@ -47,7 +45,7 @@ def image_resize[PIL_Image_or_NDArray](image: PIL_Image_or_NDArray, max_result_s
 \t\t>>> image_resize(pil_image, 50, resampling=Image.Resampling.NEAREST).size
 \t\t(50, 25)
 \t'''
-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, return_type: type[PIL_Image_or_NDArray] | str = 'same', contiguous: bool = True) -> Any:
+def auto_crop[T: Image.Image | NDArray[np.number]](image: T, mask: NDArray[np.bool_] | None = None, threshold: int | float | Callable[[NDArray[np.number]], int | float] | None = None, return_type: type[T] | str = 'same', contiguous: bool = True) -> Any:
     ''' Automatically crop an image to remove zero or uniform regions.
 
 \tThis function crops the image to keep only the region where pixels are non-zero

stouputils/io.py

@@ -11,6 +11,7 @@ This module provides utilities for file management.
 - super_open: Open a file with the given mode, creating the directory if it doesn't exist (only if writing)
 - replace_tilde: Replace the "~" by the user's home directory
 - clean_path: Clean the path by replacing backslashes with forward slashes and simplifying the path
+- safe_close: Safely close a file descriptor or file object after flushing, ignoring any exceptions
 
 .. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/io_module.gif
   :alt: stouputils io examples
@@ -338,7 +339,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
 	"""
@@ -491,3 +492,23 @@ def clean_path(file_path: str, trailing_slash: bool = True) -> str:
 	# Return the cleaned path
 	return file_path if file_path != "." else ""
 
+def safe_close(file: IO[Any] | int | None) -> None:
+	""" Safely close a file object (or file descriptor) after flushing, ignoring any exceptions.
+
+	Args:
+		file (IO[Any] | int | None): The file object or file descriptor to close
+	"""
+	if isinstance(file, int):
+		if file != -1:
+			for func in (os.fsync, os.close):
+				try:
+					func(file)
+				except Exception:
+					pass
+	elif file:
+		for func in (file.flush, file.close):
+			try:
+				func()
+			except Exception:
+				pass
+

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"""
@@ -211,3 +211,9 @@ def clean_path(file_path: str, trailing_slash: bool = True) -> str:
 \t\t>>> clean_path("C:/folder1\\\\folder2")
 \t\t\'C:/folder1/folder2\'
 \t'''
+def safe_close(file: IO[Any] | int | None) -> None:
+    """ Safely close a file object (or file descriptor) after flushing, ignoring any exceptions.
+
+\tArgs:
+\t\tfile (IO[Any] | int | None): The file object or file descriptor to close
+\t"""

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/lock/__init__.pyi

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