stouputils 1.15.0__py3-none-any.whl → 1.16.0__py3-none-any.whl

stouputils/__init__.py

@@ -1,18 +1,7 @@
-""" A collection of utility modules designed to simplify and enhance the development process.
-
-This package provides various tools and utilities for common development tasks including:
-
-Key Features:
-- Continuous delivery utilities (GitHub, PyPI)
-- Display and logging utilities (print)
-- File and I/O management (io)
-- Decorators for common patterns
-- Context managers
-- Archive and backup tools
-- Parallel processing helpers
-- Collection utilities
-- Doctests utilities
+""" 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.
 
+Check the documentation for more details: https://stoupy51.github.io/stouputils/
 """
 # Version (handle case where the package is not installed)
 from importlib.metadata import PackageNotFoundError
@@ -31,6 +20,7 @@ from .image import *
 from .io import *
 from .parallel import *
 from .print import *
+from .typing import *
 from .version_pkg import *
 
 try:

stouputils/__init__.pyi

@@ -10,6 +10,7 @@ from .image import *
 from .io import *
 from .parallel import *
 from .print import *
+from .typing import *
 from .version_pkg import *
 
 __version__: str

stouputils/__main__.py

@@ -7,12 +7,7 @@ import sys
 
 import argcomplete
 
-from .all_doctests import launch_tests
-from .archive import archive_cli
-from .backup import backup_cli
 from .decorators import handle_error
-from .print import CYAN, GREEN, RESET
-from .version_pkg import show_version_cli
 
 # Argument Parser Setup for Auto-Completion
 parser = argparse.ArgumentParser(prog="stouputils", add_help=False)
@@ -29,22 +24,28 @@ def main() -> None:
 
 	# Print the version of stouputils and its dependencies
 	if second_arg in ("--version", "-v", "version", "show_version"):
+		from .version_pkg import show_version_cli
 		return show_version_cli()
 
 	# Handle "all_doctests" command
 	if second_arg == "all_doctests":
-		if launch_tests("." if len(sys.argv) == 2 else sys.argv[2]) > 0:
+		root_dir: str = "." if len(sys.argv) == 2 else sys.argv[2]
+		pattern: str = sys.argv[3] if len(sys.argv) >= 4 else "*"
+		from .all_doctests import launch_tests
+		if launch_tests(root_dir, pattern=pattern) > 0:
 			sys.exit(1)
 		return
 
 	# Handle "archive" command
 	if second_arg == "archive":
 		sys.argv.pop(1)  # Remove "archive" from argv so archive_cli gets clean arguments
+		from .archive import archive_cli
 		return archive_cli()
 
 	# Handle "backup" command
 	if second_arg == "backup":
 		sys.argv.pop(1)  # Remove "backup" from argv so backup_cli gets clean arguments
+		from .backup import backup_cli
 		return backup_cli()
 
 	# Handle "build" command
@@ -64,6 +65,7 @@ def main() -> None:
 		pkg_version = "unknown"
 
 	# Print help with nice formatting
+	from .print import CYAN, GREEN, RESET
 	separator: str = "─" * 60
 	print(f"""
 {CYAN}{separator}{RESET}
@@ -73,7 +75,7 @@ def main() -> None:
 
 {CYAN}Available commands:{RESET}
   {GREEN}--version, -v{RESET} [pkg] [-t <depth>]    Show version information (optionally for a specific package)
-  {GREEN}all_doctests{RESET} [dir]                  Run all doctests in the specified directory
+  {GREEN}all_doctests{RESET} [dir] [pattern]        Run all doctests in the specified directory (optionally filter by pattern)
   {GREEN}archive{RESET} --help                      Archive utilities (make, repair)
   {GREEN}backup{RESET} --help                       Backup utilities (delta, consolidate, limit)
   {GREEN}build{RESET} [--no_stubs] [<minor|major>]  Build and publish package to PyPI using 'uv' tool (complete routine)

stouputils/all_doctests.py

@@ -9,29 +9,26 @@ This module is used to run all the doctests for all the modules in a given direc
 """
 
 # Imports
-import importlib
-import os
-import pkgutil
-import sys
-from types import ModuleType
 from typing import TYPE_CHECKING
 
 from . import decorators
 from .decorators import measure_time
 from .io import clean_path, relative_path
-from .print import error, info, progress, warning
+from .print import error, info, warning
 
 if TYPE_CHECKING:
 	from doctest import TestResults
+	from types import ModuleType
 
 
 # Main program
-def launch_tests(root_dir: str, strict: bool = True) -> int:
+def launch_tests(root_dir: str, strict: bool = True, pattern: str = "*") -> int:
 	""" Main function to launch tests for all modules in the given directory.
 
 	Args:
 		root_dir				(str):			Root directory to search for modules
 		strict					(bool):			Modify the force_raise_exception variable to True in the decorators module
+		pattern					(str):			Pattern to filter module names (fnmatch style, e.g., '*typ*', 'io', etc.)
 
 	Returns:
 		int: The number of failed tests
@@ -62,11 +59,14 @@ def launch_tests(root_dir: str, strict: bool = True) -> int:
 		strict = old_value
 
 	# Get the path of the directory to check modules from
+	import os
 	working_dir: str = clean_path(os.getcwd())
 	root_dir = clean_path(os.path.abspath(root_dir))
 	dir_to_check: str = os.path.dirname(root_dir) if working_dir != root_dir else root_dir
 
 	# Get all modules from folder
+	import pkgutil
+	import sys
 	sys.path.insert(0, dir_to_check)
 	modules_file_paths: list[str] = []
 	for directory_path, _, _ in os.walk(root_dir):
@@ -94,10 +94,21 @@ def launch_tests(root_dir: str, strict: bool = True) -> int:
 	if not modules_file_paths:
 		raise ValueError(f"No modules found in '{relative_path(root_dir)}'")
 
+	# Filter modules based on pattern
+	if pattern != "*":
+		import fnmatch
+		modules_file_paths = [
+			path for path in modules_file_paths
+			if fnmatch.fnmatch(path.split(".")[-1], pattern)
+		]
+		if not modules_file_paths:
+			raise ValueError(f"No modules matching pattern '{pattern}' found in '{relative_path(root_dir)}'")
+
 	# Find longest module path for alignment
 	max_length: int = max(len(path) for path in modules_file_paths)
 
 	# Dynamically import all modules from iacob package recursively using pkgutil and importlib
+	import importlib
 	modules: list[ModuleType] = []
 	separators: list[str] = []
 	for module_path in modules_file_paths:
@@ -143,7 +154,7 @@ def launch_tests(root_dir: str, strict: bool = True) -> 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:
@@ -152,7 +163,7 @@ def test_module_with_progress(module: ModuleType, separator: str) -> "TestResult
 	Returns:
 		TestResults: The results of the tests
 	"""
-	from doctest import TestResults, testmod
+	from doctest import testmod
 	@measure_time(message=f"Testing module '{module.__name__}' {separator}took")
 	def internal() -> TestResults:
 		return testmod(m=module)

stouputils/all_doctests.pyi

@@ -1,16 +1,17 @@
 from . import decorators as decorators
 from .decorators import measure_time as measure_time
 from .io import clean_path as clean_path, relative_path as relative_path
-from .print import error as error, info as info, progress as progress, warning as warning
+from .print import error as error, info as info, warning as warning
 from doctest import TestResults as TestResults
 from types import ModuleType
 
-def launch_tests(root_dir: str, strict: bool = True) -> int:
+def launch_tests(root_dir: str, strict: bool = True, pattern: str = '*') -> int:
     ''' Main function to launch tests for all modules in the given directory.
 
 \tArgs:
 \t\troot_dir\t\t\t\t(str):\t\t\tRoot directory to search for modules
 \t\tstrict\t\t\t\t\t(bool):\t\t\tModify the force_raise_exception variable to True in the decorators module
+\t\tpattern\t\t\t\t\t(str):\t\t\tPattern to filter module names (fnmatch style, e.g., \'*typ*\', \'io\', etc.)
 
 \tReturns:
 \t\tint: The number of failed tests

stouputils/collections.py

@@ -30,7 +30,7 @@ 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 (default) or hash or str
+	""" Remove duplicates from the list while keeping the order using ids, hash, or str
 
 	Args:
 		list_to_clean	(Iterable[T]):					The list to clean

stouputils/collections.pyi

@@ -7,7 +7,7 @@ from typing import Any, Literal, TypeVar
 T = TypeVar('T')
 
 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 (default) or hash or str
+    ''' Remove duplicates from the list while keeping the order using ids, hash, or str
 
 \tArgs:
 \t\tlist_to_clean\t(Iterable[T]):\t\t\t\t\tThe list to clean

stouputils/continuous_delivery/pypi.py

@@ -10,6 +10,7 @@
 
 # Imports
 import os
+import subprocess
 import sys
 from collections.abc import Callable
 from typing import Any
@@ -22,17 +23,17 @@ def update_pip_and_required_packages() -> int:
 	""" Update pip and required packages.
 
 	Returns:
-		int: Return code of the os.system call.
+		int: Return code of the subprocess.run call.
 	"""
-	return os.system(f"{sys.executable} -m pip install --upgrade pip setuptools build twine pkginfo packaging")
+	return subprocess.run(f"{sys.executable} -m pip install --upgrade pip setuptools build twine pkginfo packaging", shell=True).returncode
 
 def build_package() -> int:
 	""" Build the package.
 
 	Returns:
-		int: Return code of the os.system call.
+		int: Return code of the subprocess.run call.
 	"""
-	return os.system(f"{sys.executable} -m build")
+	return subprocess.run(f"{sys.executable} -m build", shell=True).returncode
 
 def upload_package(repository: str, filepath: str) -> int:
 	""" Upload the package to PyPI.
@@ -42,9 +43,9 @@ def upload_package(repository: str, filepath: str) -> int:
 		filepath    (str): Path to the file to upload.
 
 	Returns:
-		int: Return code of the os.system call.
+		int: Return code of the subprocess.run call.
 	"""
-	return os.system(f"{sys.executable} -m twine upload --verbose -r {repository} {filepath}")
+	return subprocess.run(f"{sys.executable} -m twine upload --verbose -r {repository} {filepath}", shell=True).returncode
 
 @handle_error(message="Error while doing the pypi full routine", error_log=LogLevels.ERROR_TRACEBACK)
 def pypi_full_routine(
@@ -115,16 +116,16 @@ def pypi_full_routine_using_uv() -> None:
 	# Increment version in pyproject.toml
 	if "--no-bump" not in sys.argv and "--no_bump" not in sys.argv:
 		increment: str = "patch" if sys.argv[-1] not in ("minor", "major") else sys.argv[-1]
-		if os.system(f"uv version --bump {increment} --frozen") != 0:
+		if subprocess.run(f"uv version --bump {increment} --frozen", shell=True).returncode != 0:
 			raise Exception("Error while incrementing version using 'uv version'")
 
 	# Build the package using 'uv build'
 	import shutil
 	shutil.rmtree("dist", ignore_errors=True)
-	if os.system(f"{sys.executable} -m uv build") != 0:
+	if subprocess.run(f"{sys.executable} -m uv build", shell=True).returncode != 0:
 		raise Exception("Error while building the package using 'uv build'")
 
 	# Upload the most recent file to PyPI using 'uv publish'
-	if os.system(f"{sys.executable} -m uv publish") != 0:
+	if subprocess.run(f"{sys.executable} -m uv publish", shell=True).returncode != 0:
 		raise Exception("Error while publishing the package using 'uv publish'")
 

stouputils/continuous_delivery/pypi.pyi

@@ -6,13 +6,13 @@ def update_pip_and_required_packages() -> int:
     """ Update pip and required packages.
 
 \tReturns:
-\t\tint: Return code of the os.system call.
+\t\tint: Return code of the subprocess.run call.
 \t"""
 def build_package() -> int:
     """ Build the package.
 
 \tReturns:
-\t\tint: Return code of the os.system call.
+\t\tint: Return code of the subprocess.run call.
 \t"""
 def upload_package(repository: str, filepath: str) -> int:
     """ Upload the package to PyPI.
@@ -22,7 +22,7 @@ def upload_package(repository: str, filepath: str) -> int:
 \t\tfilepath    (str): Path to the file to upload.
 
 \tReturns:
-\t\tint: Return code of the os.system call.
+\t\tint: Return code of the subprocess.run call.
 \t"""
 def pypi_full_routine(repository: str, dist_directory: str, last_files: int = 1, endswith: str = '.tar.gz', update_all_function: Callable[[], int] = ..., build_package_function: Callable[[], int] = ..., upload_package_function: Callable[[str, str], int] = ...) -> None:
     ''' Upload the most recent file(s) to PyPI after updating pip and required packages and building the package.

stouputils/continuous_delivery/stubs.py

@@ -24,7 +24,7 @@ def generate_stubs(
 		package_name  (str): Name of the package to generate stubs for.
 		extra_args    (str): Extra arguments to pass to stubgen. Defaults to "--include-docstrings --include-private".
 	Returns:
-		int: Return code of the os.system call.
+		int: 0 if successful, non-zero otherwise.
 	"""
 	try:
 		from mypy.stubgen import main as stubgen_main

stouputils/continuous_delivery/stubs.pyi

@@ -10,7 +10,7 @@ def generate_stubs(package_name: str, extra_args: str = '--include-docstrings --
 \t\tpackage_name  (str): Name of the package to generate stubs for.
 \t\textra_args    (str): Extra arguments to pass to stubgen. Defaults to "--include-docstrings --include-private".
 \tReturns:
-\t\tint: Return code of the os.system call.
+\t\tint: 0 if successful, non-zero otherwise.
 \t'''
 def clean_stubs_directory(output_directory: str, package_name: str) -> None:
     """ Clean the stubs directory by deleting all .pyi files.

stouputils/data_science/scripts/exhaustive_process.py

@@ -2,11 +2,12 @@
 # Imports
 import argparse
 import os
+import subprocess
 import sys
 
 from ...decorators import handle_error, measure_time
-from ...print import info
 from ...parallel import multithreading
+from ...print import info
 from ..config.get import DataScienceConfig
 from ..dataset import LOWER_GS
 from ..models.all import ALL_MODELS, CLASS_MAP
@@ -122,7 +123,7 @@ def exhaustive_process(
 		info(f"Executing command: '{cmd}'")
 		sys.stdout.flush()
 		sys.stderr.flush()
-		os.system(cmd)
+		subprocess.run(cmd, shell=True)
 	multithreading(
 		runner,
 		commands,

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,
@@ -37,7 +37,7 @@ def image_resize[PIL_Image_or_NDArray](
 	Scales the image so that its largest dimension equals max_result_size.
 
 	Args:
-		image             (Image.Image | np.ndarray): The image to resize.
+		image             (Image.Image | NDArray):    The image to resize.
 		max_result_size   (int):                      Maximum size for the largest dimension.
 		resampling        (Image.Resampling | None):  PIL resampling filter to use (default: Image.Resampling.LANCZOS).
 		min_or_max        (Callable):                 Function to use to get the minimum or maximum of the two ratios.
@@ -84,7 +84,7 @@ def image_resize[PIL_Image_or_NDArray](
 
 	# Convert numpy array to PIL Image if needed
 	if not original_was_pil:
-		image = Image.fromarray(image)
+		image = Image.fromarray(image) # type: ignore
 
 	if keep_aspect_ratio:
 
@@ -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:
@@ -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,
@@ -372,7 +372,6 @@ def numpy_to_obj(
 	"""
 	# Imports
 	import numpy as np
-	from numpy.typing import NDArray
 	from skimage import measure
 
 	# Assertions

stouputils/image.pyi

@@ -13,7 +13,7 @@ def image_resize[PIL_Image_or_NDArray](image: PIL_Image_or_NDArray, max_result_s
 \tScales the image so that its largest dimension equals max_result_size.
 
 \tArgs:
-\t\timage             (Image.Image | np.ndarray): The image to resize.
+\t\timage             (Image.Image | NDArray):    The image to resize.
 \t\tmax_result_size   (int):                      Maximum size for the largest dimension.
 \t\tresampling        (Image.Resampling | None):  PIL resampling filter to use (default: Image.Resampling.LANCZOS).
 \t\tmin_or_max        (Callable):                 Function to use to get the minimum or maximum of the two ratios.

stouputils/parallel.py

@@ -7,6 +7,16 @@ This module provides utility functions for parallel processing, such as:
 
 I highly encourage you to read the function docstrings to understand when to use each method.
 
+Priority (nice) mapping for multiprocessing():
+
+- Unix-style values from -20 (highest priority) to 19 (lowest priority)
+- Windows automatic mapping:
+  * -20 to -10: HIGH_PRIORITY_CLASS
+  * -9 to -1: ABOVE_NORMAL_PRIORITY_CLASS
+  * 0: NORMAL_PRIORITY_CLASS
+  * 1 to 9: BELOW_NORMAL_PRIORITY_CLASS
+  * 10 to 19: IDLE_PRIORITY_CLASS
+
 .. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/parallel_module.gif
   :alt: stouputils parallel examples
 """
@@ -42,6 +52,7 @@ def multiprocessing[T, R](
 	desc: str = "",
 	max_workers: int | float = CPU_COUNT,
 	delay_first_calls: float = 0,
+	nice: int | None = None,
 	color: str = MAGENTA,
 	bar_format: str = BAR_FORMAT,
 	ascii: bool = False,
@@ -69,6 +80,11 @@ def multiprocessing[T, R](
 		delay_first_calls	(float):			Apply i*delay_first_calls seconds delay to the first "max_workers" calls.
 			For instance, the first process will be delayed by 0 seconds, the second by 1 second, etc.
 			(Defaults to 0): This can be useful to avoid functions being called in the same second.
+		nice				(int | None):		Adjust the priority of worker processes (Defaults to None).
+			Use Unix-style values: -20 (highest priority) to 19 (lowest priority).
+			Positive values reduce priority, negative values increase it.
+			Automatically converted to appropriate priority class on Windows.
+			If None, no priority adjustment is made.
 		color				(str):				Color of the progress bar (Defaults to MAGENTA)
 		bar_format			(str):				Format of the progress bar (Defaults to BAR_FORMAT)
 		ascii				(bool):				Whether to use ASCII or Unicode characters for the progress bar
@@ -140,13 +156,21 @@ def multiprocessing[T, R](
 	# Do multiprocessing only if there is more than 1 argument and more than 1 CPU
 	if max_workers > 1 and len(args) > 1:
 		def process() -> list[Any]:
+			# Wrap function with nice if specified
+			if nice is not None:
+				wrapped_args = [(nice, func, arg) for arg in args]
+				wrapped_func = _nice_wrapper
+			else:
+				wrapped_args = args
+				wrapped_func = func
+
 			if verbose:
 				return list(process_map(
-					func, args, max_workers=max_workers, chunksize=chunksize, desc=desc, bar_format=bar_format, ascii=ascii, **tqdm_kwargs
+					wrapped_func, wrapped_args, max_workers=max_workers, chunksize=chunksize, desc=desc, bar_format=bar_format, ascii=ascii, **tqdm_kwargs
 				)) # type: ignore
 			else:
 				with Pool(max_workers) as pool:
-					return list(pool.map(func, args, chunksize=chunksize))	# type: ignore
+					return list(pool.map(wrapped_func, wrapped_args, chunksize=chunksize))	# type: ignore
 		try:
 			return process()
 		except RuntimeError as e:
@@ -382,6 +406,53 @@ def run_in_subprocess[R](
 		raise RuntimeError("Subprocess did not return any result") from e
 
 
+# "Private" function to wrap function execution with nice priority (must be at module level for pickling)
+def _nice_wrapper[T, R](args: tuple[int, Callable[[T], R], T]) -> R:
+	""" Wrapper that applies nice priority then executes the function.
+
+	Args:
+		args (tuple): Tuple containing (nice_value, func, arg)
+
+	Returns:
+		R: Result of the function execution
+	"""
+	nice_value, func, arg = args
+	_set_process_priority(nice_value)
+	return func(arg)
+
+# "Private" function to set process priority (must be at module level for pickling on Windows)
+def _set_process_priority(nice_value: int) -> None:
+	""" Set the priority of the current process.
+
+	Args:
+		nice_value (int): Unix-style priority value (-20 to 19)
+	"""
+	try:
+		import sys
+		if sys.platform == "win32":
+			# Map Unix nice values to Windows priority classes
+			# -20 to -10: HIGH, -9 to -1: ABOVE_NORMAL, 0: NORMAL, 1-9: BELOW_NORMAL, 10-19: IDLE
+			import ctypes
+			# Windows priority class constants
+			if nice_value <= -10:
+				priority = 0x00000080  # HIGH_PRIORITY_CLASS
+			elif nice_value < 0:
+				priority = 0x00008000  # ABOVE_NORMAL_PRIORITY_CLASS
+			elif nice_value == 0:
+				priority = 0x00000020  # NORMAL_PRIORITY_CLASS
+			elif nice_value < 10:
+				priority = 0x00004000  # BELOW_NORMAL_PRIORITY_CLASS
+			else:
+				priority = 0x00000040  # IDLE_PRIORITY_CLASS
+			kernel32 = ctypes.windll.kernel32
+			handle = kernel32.GetCurrentProcess()
+			kernel32.SetPriorityClass(handle, priority)
+		else:
+			# Unix-like systems
+			os.nice(nice_value)
+	except Exception:
+		pass  # Silently ignore if we can't set priority
+
 # "Private" function for subprocess wrapper (must be at module level for pickling on Windows)
 def _subprocess_wrapper[R](
 	result_queue: Any,

stouputils/parallel.pyi

@@ -10,7 +10,7 @@ CPU_COUNT: int
 T = TypeVar('T')
 R = TypeVar('R')
 
-def multiprocessing[T, R](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, smooth_tqdm: bool = True, **tqdm_kwargs: Any) -> list[R]:
+def multiprocessing[T, R](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, nice: int | None = None, color: str = ..., bar_format: str = ..., ascii: bool = False, smooth_tqdm: bool = True, **tqdm_kwargs: Any) -> 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.
@@ -32,6 +32,11 @@ def multiprocessing[T, R](func: Callable[..., R] | list[Callable[..., R]], args:
 \t\tdelay_first_calls\t(float):\t\t\tApply i*delay_first_calls seconds delay to the first "max_workers" calls.
 \t\t\tFor instance, the first process will be delayed by 0 seconds, the second by 1 second, etc.
 \t\t\t(Defaults to 0): This can be useful to avoid functions being called in the same second.
+\t\tnice\t\t\t\t(int | None):\t\tAdjust the priority of worker processes (Defaults to None).
+\t\t\tUse Unix-style values: -20 (highest priority) to 19 (lowest priority).
+\t\t\tPositive values reduce priority, negative values increase it.
+\t\t\tAutomatically converted to appropriate priority class on Windows.
+\t\t\tIf None, no priority adjustment is made.
 \t\tcolor\t\t\t\t(str):\t\t\t\tColor of the progress bar (Defaults to MAGENTA)
 \t\tbar_format\t\t\t(str):\t\t\t\tFormat of the progress bar (Defaults to BAR_FORMAT)
 \t\tascii\t\t\t\t(bool):\t\t\t\tWhether to use ASCII or Unicode characters for the progress bar
@@ -169,6 +174,21 @@ def run_in_subprocess[R](func: Callable[..., R], *args: Any, timeout: float | No
 \t\t\t> # With timeout to prevent hanging
 \t\t\t> run_in_subprocess(some_gpu_func, data, timeout=300.0)
 \t'''
+def _nice_wrapper[T, R](args: tuple[int, Callable[[T], R], T]) -> R:
+    """ Wrapper that applies nice priority then executes the function.
+
+\tArgs:
+\t\targs (tuple): Tuple containing (nice_value, func, arg)
+
+\tReturns:
+\t\tR: Result of the function execution
+\t"""
+def _set_process_priority(nice_value: int) -> None:
+    """ Set the priority of the current process.
+
+\tArgs:
+\t\tnice_value (int): Unix-style priority value (-20 to 19)
+\t"""
 def _subprocess_wrapper[R](result_queue: Any, func: Callable[..., R], args: tuple[Any, ...], kwargs: dict[str, Any]) -> None:
     """ Wrapper function to execute the target function and store the result in the queue.
 

stouputils/print.py

@@ -36,7 +36,8 @@ T = TypeVar("T")
 
 # Enable colors on Windows 10 terminal if applicable
 if os.name == "nt":
-	os.system("color")
+	import subprocess
+	subprocess.run("color", shell=True)
 
 # Print functions
 previous_args_kwards: tuple[Any, Any] = ((), {})

stouputils/typing.py

@@ -0,0 +1,71 @@
+"""
+This module provides utilities for typing enhancements such as JSON type aliases:
+- JsonDict
+- JsonList
+- JsonMap
+- MutJsonMap
+- IterAny
+"""
+
+# Imports
+from collections.abc import Iterable, Mapping, MutableMapping
+from dataclasses import asdict, is_dataclass
+from typing import Any, cast
+
+# Typing aliases
+JsonDict = dict[str, Any]
+""" A type alias for JSON dictionaries """
+JsonList = list[Any]
+""" A type alias for JSON lists """
+JsonMap = Mapping[str, Any]
+""" A type alias for JSON mapping """
+MutJsonMap = MutableMapping[str, Any]
+""" A type alias for mutable JSON mapping """
+IterAny = Iterable[Any]
+""" A type alias for iterable of any type """
+
+
+## Utility functions
+def convert_to_serializable(obj: Any) -> Any:
+	""" Recursively convert objects to JSON-serializable forms.
+
+	Objects with a `to_dict()` or `asdict()` method are converted to their dictionary representation.
+	Dictionaries and lists are recursively processed.
+
+	Can also be used to convert nested structures containing custom objects,
+	such as defaultdict, dataclasses, or other user-defined types.
+
+	Args:
+		obj (Any): The object to convert
+	Returns:
+		Any: The JSON-serializable version of the object
+	Examples:
+		>>> from typing import defaultdict
+		>>> my_dict = defaultdict(lambda: defaultdict(int))
+		>>> my_dict['a']['b'] += 6
+		>>> my_dict['c']['d'] = 4
+		>>> my_dict['a']
+		defaultdict(<class 'int'>, {'b': 6})
+		>>> my_dict['c']
+		defaultdict(<class 'int'>, {'d': 4})
+		>>> convert_to_serializable(my_dict)
+		{'a': {'b': 6}, 'c': {'d': 4}}
+
+		>>> from dataclasses import dataclass
+		>>> @dataclass
+		... class Point:
+		...     x: int
+		...     y: int
+		>>> convert_to_serializable(Point(3, 4))
+		{'x': 3, 'y': 4}
+	"""
+	if hasattr(obj, "to_dict"):
+		return obj.to_dict()
+	elif is_dataclass(obj):
+		return asdict(obj) # pyright: ignore[reportArgumentType]
+	elif isinstance(obj, dict | Mapping | MutableMapping):
+		return {k: convert_to_serializable(v) for k, v in cast(JsonDict, obj).items()}
+	elif isinstance(obj, Iterable) and not isinstance(obj, (str, bytes)):
+		return [convert_to_serializable(item) for item in cast(IterAny, obj)]
+	return obj
+

stouputils/typing.pyi

@@ -0,0 +1,42 @@
+from collections.abc import Iterable, Mapping, MutableMapping
+from typing import Any
+
+JsonDict = dict[str, Any]
+JsonList = list[Any]
+JsonMap = Mapping[str, Any]
+MutJsonMap = MutableMapping[str, Any]
+IterAny = Iterable[Any]
+
+def convert_to_serializable(obj: Any) -> Any:
+    """ Recursively convert objects to JSON-serializable forms.
+
+\tObjects with a `to_dict()` or `asdict()` method are converted to their dictionary representation.
+\tDictionaries and lists are recursively processed.
+
+\tCan also be used to convert nested structures containing custom objects,
+\tsuch as defaultdict, dataclasses, or other user-defined types.
+
+\tArgs:
+\t\tobj (Any): The object to convert
+\tReturns:
+\t\tAny: The JSON-serializable version of the object
+\tExamples:
+\t\t>>> from typing import defaultdict
+\t\t>>> my_dict = defaultdict(lambda: defaultdict(int))
+\t\t>>> my_dict['a']['b'] += 6
+\t\t>>> my_dict['c']['d'] = 4
+\t\t>>> my_dict['a']
+\t\tdefaultdict(<class 'int'>, {'b': 6})
+\t\t>>> my_dict['c']
+\t\tdefaultdict(<class 'int'>, {'d': 4})
+\t\t>>> convert_to_serializable(my_dict)
+\t\t{'a': {'b': 6}, 'c': {'d': 4}}
+
+\t\t>>> from dataclasses import dataclass
+\t\t>>> @dataclass
+\t\t... class Point:
+\t\t...     x: int
+\t\t...     y: int
+\t\t>>> convert_to_serializable(Point(3, 4))
+\t\t{'x': 3, 'y': 4}
+\t"""

{stouputils-1.15.0.dist-info → stouputils-1.16.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stouputils
-Version: 1.15.0
+Version: 1.16.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
@@ -94,6 +94,7 @@ Start now by installing the package: `pip install stouputils`.<br>
 ├── <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.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>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.archive.html">archive.py</a>       <span class="comment"># 📦 Functions for creating and managing archives</span>

{stouputils-1.15.0.dist-info → stouputils-1.16.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
-stouputils/__init__.py,sha256=KMJoy8FCiiiXJ53QfgU3rz7AY7AJ_j5kP3j24JuznC0,1136
-stouputils/__init__.pyi,sha256=J8LeijIkWrTdGlevNR8dlGlgYg-Dh_MvGjp2EsPZ8UM,351
-stouputils/__main__.py,sha256=sJSncuTWua7jA9pTw4BUoDzNUUExZKeyATbmY4lhl0E,2764
+stouputils/__init__.py,sha256=w3WHJy3nt28l6WAtlZz6WRiyHhKy9mw66L6SJJXikW8,996
+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=1bGGUg80nvLBY3wrPkFrkcuQRjFTWmTpHZtai9X-vnY,5891
-stouputils/all_doctests.pyi,sha256=8JD8qn7neYuR0PolabWxX6id1dNEvQDrvOhMS2aYhTM,1907
+stouputils/all_doctests.py,sha256=317v-B4kqf_8lkrw6ul1ZGBgZ75CYIqoDn7kG5k8qyc,6322
+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=_6XbCuVi2EiSdkiPZ7XHr5mUGh2ZORev8Vd0tJDb0ug,20561
@@ -21,20 +21,20 @@ 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=5u904s_osO03-drmqPXtFZUlcweDatEQmY-dLUrnNX0,8849
-stouputils/collections.pyi,sha256=mKIBV4K7mm-PTvtoYi_cVOAGjW7bo3iIASqosSXFUzE,3519
+stouputils/collections.py,sha256=Zi2OmlPmUPx-isZZpF9xYWU52OtzNqvSHGYM5use0AA,8838
+stouputils/collections.pyi,sha256=J6Sb-8oSVeD1K-j5zNBZo_cP5Bi5NDh2qN4n4QBJIZE,3508
 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
 stouputils/continuous_delivery/cd_utils.pyi,sha256=nxTLQydVOSVIix88dRtBXjMrUPpI5ftiQYbLI_nMByQ,4848
 stouputils/continuous_delivery/github.py,sha256=Iva2XNm60Th78P_evnhCJHn0Q9-06udPlOZAxtZB5vw,19464
 stouputils/continuous_delivery/github.pyi,sha256=RHRsSroEsT0I1qeuq-Wg0JLdEEDttLrzgHZPVRtLZ0Q,6641
-stouputils/continuous_delivery/pypi.py,sha256=v7EVkF36mi1VtGiSRd-H4k9DQsdMmOnRYDgjdnCezOU,5322
-stouputils/continuous_delivery/pypi.pyi,sha256=fRAu8ocLNpEN6dhUTMuFxlmRgt3-LRjKPOJjFlUPrJ4,2463
+stouputils/continuous_delivery/pypi.py,sha256=H19RwvJN6QS-qcqvjtIaSLfZTA398jXu-SgSkvkaj0g,5524
+stouputils/continuous_delivery/pypi.pyi,sha256=3zFRz3L_gF_JuSe1J3RZAKTVsFMFiqEdCJbwHRYBj7g,2478
 stouputils/continuous_delivery/pyproject.py,sha256=olD3QqzLfCLnTBw8IkSKSLBPWyeMv6uS7A0yGdFuIvQ,4802
 stouputils/continuous_delivery/pyproject.pyi,sha256=bMWwqyG0Auo46dt-dWGePQ9yJ8rSrgb7mnJTfbiS3TQ,2053
-stouputils/continuous_delivery/stubs.py,sha256=xUAcP21Y03PLEr7X6LrIBMvPeLI8Rp-EyaTLxocA0C4,3512
-stouputils/continuous_delivery/stubs.pyi,sha256=sLZypdz1oGoymQIRPez50rnH8TQhvEIx6A7xUdGtnys,2390
+stouputils/continuous_delivery/stubs.py,sha256=N0qPBORNYmGIhoY0h40JVvNIS9CS_ixHlxNWQN1bPRE,3514
+stouputils/continuous_delivery/stubs.pyi,sha256=UrL2dowLC6hsiKe-gfWeVCudz7tKmt4rsiCL9gsBLv4,2392
 stouputils/ctx.py,sha256=KVVDmL3pAPX2WM_QzjsmctbG-YfjJ-4aWBSoI7eU_ws,15586
 stouputils/ctx.pyi,sha256=-7AJwD9bKzKBFsYlgyULPznstq3LvXRXe2r_2at72FI,9799
 stouputils/data_science/config/get.py,sha256=smdWcu5bBlY38WGtC3GzIF2el-gpvSlDMRNsypmr0JM,1773
@@ -105,14 +105,14 @@ stouputils/data_science/models/model_interface.py,sha256=om1hnEYHTILfLJRcoTDhR7R
 stouputils/data_science/models/sandbox.py,sha256=ZeuoXNHnVvMlm6umCgTl2Ss0zyQSlxFEV9xJb3ET1Qw,4269
 stouputils/data_science/range_tuple.py,sha256=5f5PQcwENZEMV0O6U5IpZ2_ylNMB_graDyv-wxrDUhk,6908
 stouputils/data_science/scripts/augment_dataset.py,sha256=zGcQ2uSn_DO570NIFEs2DUc_d5uvWxLfY-RavjdO3aU,3469
-stouputils/data_science/scripts/exhaustive_process.py,sha256=Ty2lHBZBweWxH6smpjoUEqpGz6JmMUO_oaNZO7d-gtQ,5483
+stouputils/data_science/scripts/exhaustive_process.py,sha256=Dc5gceIlIiP8U0m1qt3zpJEZAwQ7617JBAYWitdhjJI,5519
 stouputils/data_science/scripts/preprocess_dataset.py,sha256=OLC2KjEtSMeyHHPpNOATfNDuq0lZ09utKhsuzBA4MN4,2929
 stouputils/data_science/scripts/routine.py,sha256=FkTLzmcdm_qUp69D-dPAKJm2RfXZZLtPgje6lEopu2I,7662
 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=NtduEVzgbCuZhDRpDZHGTW7-wTs7MqoxUwSQcipvb08,16633
-stouputils/image.pyi,sha256=Dkf64KmXJTAEcbtYDHFZ1kqEHqOf2FgJ2Z2BlJgp4fU,8455
+stouputils/image.py,sha256=uGBweT-60JEn4SK5nVAxqiVI4Ijh4YyG_d5uXjXgtCY,16603
+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
 stouputils/installer/common.py,sha256=UJr5u02h4LQZQdkmVOkJ3vvW_0-ROGgVMMh0PNoVS1A,2209
@@ -127,14 +127,16 @@ stouputils/installer/windows.py,sha256=r2AIuoyAmtMEuoCtQBH9GWQWI-JUT2J9zoH28j9ru
 stouputils/installer/windows.pyi,sha256=tHogIFhPVDQS0I10liLkAxnpaFFAvmFtEVMpPIae5LU,1616
 stouputils/io.py,sha256=XG2cReP8wzmoe0LyMtUqvEqixiHehPvXW23h5hBf_Pw,17202
 stouputils/io.pyi,sha256=TCBTVEWUkI3dO_jWI9oPMF9SbnT1yLzFChE551JPbSY,9076
-stouputils/parallel.py,sha256=_o96klxFYgDPyxCeqFp5qNOtJhhXHQYmFIfqbJYnxko,19061
-stouputils/parallel.pyi,sha256=ug9I-Ni2q9cwwByXERQuxW-UM3rqw3dCiurnJjOWUpI,11576
-stouputils/print.py,sha256=crcvgJO-NCbQ6-C3Prsxvsn8E9mPKI186t_xcQ6O2Uo,24527
+stouputils/parallel.py,sha256=CJUhoB270QT6XXpg0fHOlJdwbvoFd6qFQhCAZDFZng4,21648
+stouputils/parallel.pyi,sha256=BTAtl4TFr71LgV3nVBY-yjpxUxlt9m6O2q82tNFHlbE,12420
+stouputils/print.py,sha256=q-qSkUGeyn-lBMU5GU36ccm_dTmWS2i_RMxMYUhncfY,24564
 stouputils/print.pyi,sha256=SRAAdObriW_LPcqvDGrCpjfGLrswRhIyJmCvC9_3OpM,10232
 stouputils/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+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.15.0.dist-info/WHEEL,sha256=XjEbIc5-wIORjWaafhI6vBtlxDBp7S9KiujWF1EM7Ak,79
-stouputils-1.15.0.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
-stouputils-1.15.0.dist-info/METADATA,sha256=1FFyPDRUgvHlhXrDArmApMkI6nwy3rDZbqWWKWlPQ1Q,13615
-stouputils-1.15.0.dist-info/RECORD,,
+stouputils-1.16.0.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
+stouputils-1.16.0.dist-info/entry_points.txt,sha256=tx0z9VOnE-sfkmbFbA93zaBMzV3XSsKEJa_BWIqUzxw,57
+stouputils-1.16.0.dist-info/METADATA,sha256=cSM0j3GOs_HHAfqbLFyDyRo8khriZLWyL__71W7JFZE,13890
+stouputils-1.16.0.dist-info/RECORD,,

{stouputils-1.15.0.dist-info → stouputils-1.16.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.25
+Generator: uv 0.9.26
 Root-Is-Purelib: true
-Tag: py3-none-any
+Tag: py3-none-any