stouputils 1.10.3__tar.gz → 1.10.4__tar.gz

{stouputils-1.10.3 → stouputils-1.10.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.10.3
+Version: 1.10.4
 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.
 Project-URL: Homepage, https://github.com/Stoupy51/stouputils
 Project-URL: Issues, https://github.com/Stoupy51/stouputils/issues

{stouputils-1.10.3 → stouputils-1.10.4}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stouputils"
-version = "1.10.3"
+version = "1.10.4"
 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"
 requires-python = ">=3.12"

{stouputils-1.10.3 → stouputils-1.10.4}/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, cast
+from typing import TYPE_CHECKING, Any, TypeVar, cast
 
 from .io import super_open
 from .print import debug, info
@@ -22,14 +22,15 @@ 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(
-	image: "Image.Image | NDArray[np.number]",
+	image: PIL_Image_or_NDArray,
 	max_result_size: int,
 	resampling: "Image.Resampling | None" = None,
 	min_or_max: Callable[[int, int], int] = max,
-	return_type: type["Image.Image | NDArray[np.number]"] | str = "same",
+	return_type: type[PIL_Image_or_NDArray] | str = "same",
 	keep_aspect_ratio: bool = True,
 ) -> Any:
 	""" Resize an image while preserving its aspect ratio by default.
@@ -114,17 +115,17 @@ def image_resize(
 			return new_image
 		else:
 			return np.array(new_image)
-	elif return_type == np.ndarray:
+	elif return_type != Image.Image:
 		return np.array(new_image)
 	else:
 		return new_image
 
 
 def auto_crop(
-	image: "Image.Image | NDArray[np.number]",
+	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["Image.Image | NDArray[np.number]"] | str = "same",
+	return_type: type[PIL_Image_or_NDArray] | str = "same",
 	contiguous: bool = True,
 ) -> Any:
 	""" Automatically crop an image to remove zero or uniform regions.
@@ -231,7 +232,7 @@ def auto_crop(
 
 	# Return original if no content found
 	if not (np.any(rows_with_content) and np.any(cols_with_content)):
-		return image_array if return_type == np.ndarray else (image if original_was_pil else Image.fromarray(image_array))
+		return image_array if return_type != Image.Image else (image if original_was_pil else Image.fromarray(image_array))
 
 	# Crop based on contiguous parameter
 	if contiguous:
@@ -257,7 +258,7 @@ def auto_crop(
 	# Return in requested format
 	if return_type == "same":
 		return Image.fromarray(cropped_array) if original_was_pil else cropped_array
-	return cropped_array if return_type == np.ndarray else Image.fromarray(cropped_array)
+	return cropped_array if return_type != Image.Image else Image.fromarray(cropped_array)
 
 
 def numpy_to_gif(
@@ -268,11 +269,13 @@ def numpy_to_gif(
 	mkdir: bool = True,
 	**kwargs: Any
 ) -> None:
-	""" Generate a '.gif' file from a numpy array for 3D visualization.
+	""" Generate a '.gif' file from a numpy array for 3D/4D visualization.
 
 	Args:
 		path     (str):     Path to the output .gif file.
-		array    (NDArray): Numpy array to be dumped (must be 3D with depth as first axis, e.g. 64x1024x1024).
+		array    (NDArray): Numpy array to be dumped (must be 3D or 4D).
+			3D: (depth, height, width) - e.g. (64, 1024, 1024)
+			4D: (depth, height, width, channels) - e.g. (50, 64, 1024, 3)
 		duration (int):     Duration between frames in milliseconds.
 		loop     (int):     Number of loops (0 = infinite).
 		mkdir    (bool):    Create the directory if it does not exist.
@@ -282,9 +285,14 @@ def numpy_to_gif(
 
 		.. code-block:: python
 
+			> # 3D array example
 			> array = np.random.randint(0, 256, (10, 100, 100), dtype=np.uint8)
 			> numpy_to_gif("output_10_frames_100x100.gif", array, duration=200, loop=0)
 
+			> # 4D array example (batch of 3D images)
+			> array_4d = np.random.randint(0, 256, (5, 10, 100, 3), dtype=np.uint8)
+			> numpy_to_gif("output_50_frames_100x100.gif", array_4d, duration=200)
+
 			> total_duration = 1000  # 1 second
 			> numpy_to_gif("output_1s.gif", array, duration=total_duration // len(array))
 	"""
@@ -293,11 +301,15 @@ def numpy_to_gif(
 	from PIL import Image
 
 	# Assertions
-	assert array.ndim == 3, f"The input array must be 3D, got shape {array.shape} instead."
+	assert array.ndim in (3, 4), f"The input array must be 3D or 4D, got shape {array.shape} instead."
+	if array.ndim == 4:
+		assert array.shape[-1] in (1, 3), f"For 4D arrays, the last dimension must be 1 or 3 (channels), got shape {array.shape} instead."
 
 	# Create directory if needed
 	if mkdir:
-		os.makedirs(os.path.dirname(path), exist_ok=True)
+		dirname: str = os.path.dirname(path)
+		if dirname != "":
+			os.makedirs(dirname, exist_ok=True)
 
 	# Normalize array if outside [0-255] range to [0-1]
 	array = array.astype(np.float32)
@@ -308,7 +320,10 @@ def numpy_to_gif(
 	# Scale to [0-255] if in [0-1] range
 	mini, maxi = np.min(array), np.max(array)
 	if mini >= 0.0 and maxi <= 1.0:
-		array = (array * 255).astype(np.uint8)
+		array = (array * 255)
+
+	# Ensure array is uint8 for PIL compatibility
+	array = array.astype(np.uint8)
 
 	# Convert each slice to PIL Image
 	pil_images: list[Image.Image] = [

{stouputils-1.10.3 → stouputils-1.10.4}/stouputils/image.pyi

@@ -4,9 +4,11 @@ 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
+from typing import Any, TypeVar
 
-def image_resize(image: Image.Image | NDArray[np.number], max_result_size: int, resampling: Image.Resampling | None = None, min_or_max: Callable[[int, int], int] = ..., return_type: type[Image.Image | NDArray[np.number]] | str = 'same', keep_aspect_ratio: bool = True) -> Any:
+PIL_Image_or_NDArray = TypeVar('PIL_Image_or_NDArray', bound='Image.Image | NDArray[np.number]')
+
+def image_resize(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:
     ''' Resize an image while preserving its aspect ratio by default.
 \tScales the image so that its largest dimension equals max_result_size.
 
@@ -45,7 +47,7 @@ def image_resize(image: Image.Image | NDArray[np.number], max_result_size: int,
 \t\t>>> image_resize(pil_image, 50, resampling=Image.Resampling.NEAREST).size
 \t\t(50, 25)
 \t'''
-def auto_crop(image: Image.Image | NDArray[np.number], mask: NDArray[np.bool_] | None = None, threshold: int | float | Callable[[NDArray[np.number]], int | float] | None = None, return_type: type[Image.Image | NDArray[np.number]] | str = 'same', contiguous: bool = True) -> Any:
+def auto_crop(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:
     ''' 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
@@ -120,11 +122,13 @@ def auto_crop(image: Image.Image | NDArray[np.number], mask: NDArray[np.bool_] |
 \t(30, 30, 6)
 \t'''
 def numpy_to_gif(path: str, array: NDArray[np.integer | np.floating | np.bool_], duration: int = 100, loop: int = 0, mkdir: bool = True, **kwargs: Any) -> None:
-    ''' Generate a \'.gif\' file from a numpy array for 3D visualization.
+    ''' Generate a \'.gif\' file from a numpy array for 3D/4D visualization.
 
 \tArgs:
 \t\tpath     (str):     Path to the output .gif file.
-\t\tarray    (NDArray): Numpy array to be dumped (must be 3D with depth as first axis, e.g. 64x1024x1024).
+\t\tarray    (NDArray): Numpy array to be dumped (must be 3D or 4D).
+\t\t\t3D: (depth, height, width) - e.g. (64, 1024, 1024)
+\t\t\t4D: (depth, height, width, channels) - e.g. (50, 64, 1024, 3)
 \t\tduration (int):     Duration between frames in milliseconds.
 \t\tloop     (int):     Number of loops (0 = infinite).
 \t\tmkdir    (bool):    Create the directory if it does not exist.
@@ -134,9 +138,14 @@ def numpy_to_gif(path: str, array: NDArray[np.integer | np.floating | np.bool_],
 
 \t\t.. code-block:: python
 
+\t\t\t> # 3D array example
 \t\t\t> array = np.random.randint(0, 256, (10, 100, 100), dtype=np.uint8)
 \t\t\t> numpy_to_gif("output_10_frames_100x100.gif", array, duration=200, loop=0)
 
+\t\t\t> # 4D array example (batch of 3D images)
+\t\t\t> array_4d = np.random.randint(0, 256, (5, 10, 100, 3), dtype=np.uint8)
+\t\t\t> numpy_to_gif("output_50_frames_100x100.gif", array_4d, duration=200)
+
 \t\t\t> total_duration = 1000  # 1 second
 \t\t\t> numpy_to_gif("output_1s.gif", array, duration=total_duration // len(array))
 \t'''

{stouputils-1.10.3 → stouputils-1.10.4}/stouputils/parallel.py

@@ -14,7 +14,7 @@ I highly encourage you to read the function docstrings to understand when to use
 # Imports
 import os
 import time
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 from typing import Any, TypeVar, cast
 
 from .ctx import SetMPStartMethod
@@ -36,7 +36,7 @@ R = TypeVar("R")
 # Functions
 def multiprocessing(
 	func: Callable[..., R] | list[Callable[..., R]],
-	args: list[T],
+	args: Iterable[T],
 	use_starmap: bool = False,
 	chunksize: int = 1,
 	desc: str = "",
@@ -54,7 +54,7 @@ def multiprocessing(
 
 	Args:
 		func				(Callable | list[Callable]):	Function to execute, or list of functions (one per argument)
-		args				(list):				List of arguments to pass to the function(s)
+		args				(Iterable):			Iterable of arguments to pass to the function(s)
 		use_starmap			(bool):				Whether to use starmap or not (Defaults to False):
 			True means the function will be called like func(\*args[i]) instead of func(args[i])
 		chunksize			(int):				Number of arguments to process at a time
@@ -109,6 +109,7 @@ def multiprocessing(
 	from tqdm.contrib.concurrent import process_map  # pyright: ignore[reportUnknownVariableType]
 
 	# Handle parameters
+	args = list(args)  # Ensure we have a list (not other iterable)
 	if max_workers == -1:
 		max_workers = CPU_COUNT
 	if isinstance(max_workers, float):
@@ -154,7 +155,7 @@ def multiprocessing(
 
 def multithreading(
 	func: Callable[..., R] | list[Callable[..., R]],
-	args: list[T],
+	args: Iterable[T],
 	use_starmap: bool = False,
 	desc: str = "",
 	max_workers: int | float = CPU_COUNT,
@@ -171,7 +172,7 @@ def multithreading(
 
 	Args:
 		func				(Callable | list[Callable]):	Function to execute, or list of functions (one per argument)
-		args				(list):				List of arguments to pass to the function(s)
+		args				(Iterable):			Iterable of arguments to pass to the function(s)
 		use_starmap			(bool):				Whether to use starmap or not (Defaults to False):
 			True means the function will be called like func(\*args[i]) instead of func(args[i])
 		desc				(str):				Description displayed in the progress bar
@@ -222,6 +223,7 @@ def multithreading(
 	from tqdm.auto import tqdm
 
 	# Handle parameters
+	args = list(args)  # Ensure we have a list (not other iterable)
 	if max_workers == -1:
 		max_workers = CPU_COUNT
 	if isinstance(max_workers, float):

{stouputils-1.10.3 → stouputils-1.10.4}/stouputils/parallel.pyi

@@ -1,6 +1,6 @@
 from .ctx import SetMPStartMethod as SetMPStartMethod
 from .print import BAR_FORMAT as BAR_FORMAT, MAGENTA as MAGENTA
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 from typing import Any, TypeVar
 
 def doctest_square(x: int) -> int: ...
@@ -10,7 +10,7 @@ CPU_COUNT: int
 T = TypeVar('T')
 R = TypeVar('R')
 
-def multiprocessing(func: Callable[..., R] | list[Callable[..., R]], args: list[T], use_starmap: bool = False, chunksize: int = 1, desc: str = '', max_workers: int | float = ..., delay_first_calls: float = 0, color: str = ..., bar_format: str = ..., ascii: bool = False) -> list[R]:
+def multiprocessing(func: Callable[..., R] | list[Callable[..., R]], args: Iterable[T], use_starmap: bool = False, chunksize: int = 1, desc: str = '', max_workers: int | float = ..., delay_first_calls: float = 0, color: str = ..., bar_format: str = ..., ascii: bool = False) -> list[R]:
     ''' Method to execute a function in parallel using multiprocessing
 
 \t- For CPU-bound operations where the GIL (Global Interpreter Lock) is a bottleneck.
@@ -19,7 +19,7 @@ def multiprocessing(func: Callable[..., R] | list[Callable[..., R]], args: list[
 
 \tArgs:
 \t\tfunc\t\t\t\t(Callable | list[Callable]):\tFunction to execute, or list of functions (one per argument)
-\t\targs\t\t\t\t(list):\t\t\t\tList of arguments to pass to the function(s)
+\t\targs\t\t\t\t(Iterable):\t\t\tIterable of arguments to pass to the function(s)
 \t\tuse_starmap\t\t\t(bool):\t\t\t\tWhether to use starmap or not (Defaults to False):
 \t\t\tTrue means the function will be called like func(\\*args[i]) instead of func(args[i])
 \t\tchunksize\t\t\t(int):\t\t\t\tNumber of arguments to process at a time
@@ -66,7 +66,7 @@ def multiprocessing(func: Callable[..., R] | list[Callable[..., R]], args: list[
 \t\t\t. )
 \t\t\t[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 \t'''
-def multithreading(func: Callable[..., R] | list[Callable[..., R]], args: list[T], use_starmap: bool = False, desc: str = '', max_workers: int | float = ..., delay_first_calls: float = 0, color: str = ..., bar_format: str = ..., ascii: bool = False) -> list[R]:
+def multithreading(func: Callable[..., R] | list[Callable[..., R]], args: Iterable[T], use_starmap: bool = False, desc: str = '', max_workers: int | float = ..., delay_first_calls: float = 0, color: str = ..., bar_format: str = ..., ascii: bool = False) -> list[R]:
     ''' Method to execute a function in parallel using multithreading, you should use it:
 
 \t- For I/O-bound operations where the GIL is not a bottleneck, such as network requests or disk operations.
@@ -75,7 +75,7 @@ def multithreading(func: Callable[..., R] | list[Callable[..., R]], args: list[T
 
 \tArgs:
 \t\tfunc\t\t\t\t(Callable | list[Callable]):\tFunction to execute, or list of functions (one per argument)
-\t\targs\t\t\t\t(list):\t\t\t\tList of arguments to pass to the function(s)
+\t\targs\t\t\t\t(Iterable):\t\t\tIterable of arguments to pass to the function(s)
 \t\tuse_starmap\t\t\t(bool):\t\t\t\tWhether to use starmap or not (Defaults to False):
 \t\t\tTrue means the function will be called like func(\\*args[i]) instead of func(args[i])
 \t\tdesc\t\t\t\t(str):\t\t\t\tDescription displayed in the progress bar

{stouputils-1.10.3 → stouputils-1.10.4}/stouputils/print.py

@@ -470,7 +470,8 @@ def show_version(main_package: str = "stouputils", primary_color: str = CYAN, se
 
 	# Get Python version
 	python_version: str = f" Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro} "
-	separator_length: int = longest_name_length + longest_version_length + 4
+	minimum_separator_length: int = len(python_version) + 10	# Always at least 5 dashes on each side
+	separator_length: int = max(minimum_separator_length, longest_name_length + longest_version_length + 4)
 	python_text_length: int = len(python_version)
 	left_dashes: int = (separator_length - python_text_length) // 2
 	right_dashes: int = separator_length - python_text_length - left_dashes