stouputils 1.13.1__tar.gz → 1.13.3__tar.gz

{stouputils-1.13.1 → stouputils-1.13.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: stouputils
-Version: 1.13.1
+Version: 1.13.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

{stouputils-1.13.1 → stouputils-1.13.3}/pyproject.toml

@@ -8,7 +8,7 @@ module-root = ""
 
 [project]
 name = "stouputils"
-version = "1.13.1"
+version = "1.13.3"
 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"]

{stouputils-1.13.1 → stouputils-1.13.3}/stouputils/continuous_delivery/pypi.py

@@ -108,14 +108,15 @@ def pypi_full_routine_using_uv() -> None:
 		package_dir = "src/" + package_name
 
 	# Generate stubs unless '--no-stubs' is passed
-	if "--no-stubs" not in sys.argv:
+	if "--no-stubs" not in sys.argv and "--no_stubs" not in sys.argv:
 		from .stubs import stubs_full_routine
 		stubs_full_routine(package_name, output_directory=package_dir, clean_before=True)
 
 	# Increment version in pyproject.toml
-	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:
-		raise Exception("Error while incrementing version using 'uv version'")
+	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:
+			raise Exception("Error while incrementing version using 'uv version'")
 
 	# Build the package using 'uv build'
 	import shutil

{stouputils-1.13.1 → stouputils-1.13.3}/stouputils/decorators.py

@@ -64,7 +64,7 @@ def measure_time(
 	"""
 	def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
 		# Set the message if not specified, else use the provided one
-		new_msg: str = message if message else f"Execution time of {_get_func_name(func)}"
+		new_msg: str = message if message else f"Execution time of {_get_func_name(func)}()"
 
 		if is_generator:
 			@wraps(func)
@@ -149,11 +149,11 @@ def handle_error(
 				return func(*args, **kwargs)
 			except exceptions as e:
 				if error_log == LogLevels.WARNING:
-					warning(f"{msg}Error during {_get_func_name(func)}: ({type(e).__name__}) {e}")
+					warning(f"{msg}Error during {_get_func_name(func)}(): ({type(e).__name__}) {e}")
 				elif error_log == LogLevels.WARNING_TRACEBACK:
-					warning(f"{msg}Error during {_get_func_name(func)}:\n{format_exc()}")
+					warning(f"{msg}Error during {_get_func_name(func)}():\n{format_exc()}")
 				elif error_log == LogLevels.ERROR_TRACEBACK:
-					error(f"{msg}Error during {_get_func_name(func)}:\n{format_exc()}", exit=True)
+					error(f"{msg}Error during {_get_func_name(func)}():\n{format_exc()}", exit=True)
 				elif error_log == LogLevels.RAISE_EXCEPTION:
 					raise e
 
@@ -212,7 +212,7 @@ def timeout(
 		@wraps(func)
 		def wrapper(*args: tuple[Any, ...], **kwargs: dict[str, Any]) -> Any:
 			# Build timeout message
-			msg: str = message if message else f"Function '{_get_func_name(func)}' timed out after {seconds} seconds"
+			msg: str = message if message else f"Function '{_get_func_name(func)}()' timed out after {seconds} seconds"
 
 			# Try to use signal-based timeout (Unix only, main thread only)
 			try:
@@ -332,7 +332,7 @@ def retry(
 					if message:
 						warning(f"{message}, retrying ({attempt + 1}/{max_attempts}): {e}")
 					else:
-						warning(f"{type(e).__name__} encountered while running {_get_func_name(func)}, retrying ({attempt + 1}/{max_attempts}): {e}")
+						warning(f"{type(e).__name__} encountered while running {_get_func_name(func)}(), retrying ({attempt + 1}/{max_attempts}): {e}")
 
 					# Wait before next attempt
 					time.sleep(current_delay)
@@ -375,10 +375,20 @@ def simple_cache(
 		3
 		>>> test2(3, 4)
 		7
+
+		>>> @simple_cache
+		... def factorial(n: int) -> int:
+		...     return n * factorial(n - 1) if n else 1
+		>>> factorial(10)   # no previously cached result, makes 11 recursive calls
+		3628800
+		>>> factorial(5)    # no new calls, just returns the cached result
+		120
+		>>> factorial(12)   # two new recursive calls, factorial(10) is cached
+		479001600
 	"""
 	def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
 		# Create the cache dict
-		cache_dict: dict[bytes, Any] = {}
+		cache_dict: dict[Any, Any] = {}
 
 		# Create the wrapper
 		@wraps(func)
@@ -386,9 +396,9 @@ def simple_cache(
 
 			# Get the hashed key
 			if method == "str":
-				hashed: bytes = str(args).encode() + str(kwargs).encode()
+				hashed = str(args) + str(kwargs)
 			elif method == "pickle":
-				hashed: bytes = pickle_dumps((args, kwargs))
+				hashed = pickle_dumps((args, kwargs))
 			else:
 				raise ValueError("Invalid caching method. Supported methods are 'str' and 'pickle'.")
 
@@ -447,7 +457,7 @@ def abstract(
 		NotImplementedError: Function 'method' is abstract and must be implemented by a subclass
 	"""
 	def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
-		message: str = f"Function '{_get_func_name(func)}' is abstract and must be implemented by a subclass"
+		message: str = f"Function '{_get_func_name(func)}()' is abstract and must be implemented by a subclass"
 		if not func.__doc__:
 			func.__doc__ = message
 

{stouputils-1.13.1 → stouputils-1.13.3}/stouputils/parallel.py

@@ -45,6 +45,8 @@ def multiprocessing[T, R](
 	color: str = MAGENTA,
 	bar_format: str = BAR_FORMAT,
 	ascii: bool = False,
+	smooth_tqdm: bool = True,
+	**tqdm_kwargs: Any
 ) -> list[R]:
 	r""" Method to execute a function in parallel using multiprocessing
 
@@ -70,6 +72,8 @@ def multiprocessing[T, R](
 		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
+		smooth_tqdm			(bool):				Whether to enable smooth progress bar updates by setting miniters and mininterval (Defaults to True)
+		**tqdm_kwargs		(Any):				Additional keyword arguments to pass to tqdm
 
 	Returns:
 		list[object]:	Results of the function execution
@@ -123,13 +127,22 @@ def multiprocessing[T, R](
 	desc, func, args = _handle_parameters(func, args, use_starmap, delay_first_calls, max_workers, desc, color)
 	if bar_format == BAR_FORMAT:
 		bar_format = bar_format.replace(MAGENTA, color)
+	if smooth_tqdm:
+		tqdm_kwargs.setdefault("mininterval", 0.0)
+		try:
+			total = len(args) # type: ignore
+			import shutil
+			width = shutil.get_terminal_size().columns
+			tqdm_kwargs.setdefault("miniters", max(1, total // width))
+		except (TypeError, OSError):
+			tqdm_kwargs.setdefault("miniters", 1)
 
 	# 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]:
 			if verbose:
 				return list(process_map(
-					func, args, max_workers=max_workers, chunksize=chunksize, desc=desc, bar_format=bar_format, ascii=ascii
+					func, 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:
@@ -148,7 +161,7 @@ def multiprocessing[T, R](
 	# Single process execution
 	else:
 		if verbose:
-			return [func(arg) for arg in tqdm(args, total=len(args), desc=desc, bar_format=bar_format, ascii=ascii)]
+			return [func(arg) for arg in tqdm(args, total=len(args), desc=desc, bar_format=bar_format, ascii=ascii, **tqdm_kwargs)]
 		else:
 			return [func(arg) for arg in args]
 
@@ -163,6 +176,8 @@ def multithreading[T, R](
 	color: str = MAGENTA,
 	bar_format: str = BAR_FORMAT,
 	ascii: bool = False,
+	smooth_tqdm: bool = True,
+	**tqdm_kwargs: Any
 	) -> list[R]:
 	r""" Method to execute a function in parallel using multithreading, you should use it:
 
@@ -186,6 +201,8 @@ def multithreading[T, R](
 		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
+		smooth_tqdm			(bool):				Whether to enable smooth progress bar updates by setting miniters and mininterval (Defaults to True)
+		**tqdm_kwargs		(Any):				Additional keyword arguments to pass to tqdm
 
 	Returns:
 		list[object]:	Results of the function execution
@@ -237,12 +254,21 @@ def multithreading[T, R](
 	desc, func, args = _handle_parameters(func, args, use_starmap, delay_first_calls, max_workers, desc, color)
 	if bar_format == BAR_FORMAT:
 		bar_format = bar_format.replace(MAGENTA, color)
+	if smooth_tqdm:
+		tqdm_kwargs.setdefault("mininterval", 0.0)
+		try:
+			total = len(args) # type: ignore
+			import shutil
+			width = shutil.get_terminal_size().columns
+			tqdm_kwargs.setdefault("miniters", max(1, total // width))
+		except (TypeError, OSError):
+			tqdm_kwargs.setdefault("miniters", 1)
 
 	# Do multithreading only if there is more than 1 argument and more than 1 CPU
 	if max_workers > 1 and len(args) > 1:
 		if verbose:
 			with ThreadPoolExecutor(max_workers) as executor:
-				return list(tqdm(executor.map(func, args), total=len(args), desc=desc, bar_format=bar_format, ascii=ascii))
+				return list(tqdm(executor.map(func, args), total=len(args), desc=desc, bar_format=bar_format, ascii=ascii, **tqdm_kwargs))
 		else:
 			with ThreadPoolExecutor(max_workers) as executor:
 				return list(executor.map(func, args))
@@ -250,7 +276,7 @@ def multithreading[T, R](
 	# Single process execution
 	else:
 		if verbose:
-			return [func(arg) for arg in tqdm(args, total=len(args), desc=desc, bar_format=bar_format, ascii=ascii)]
+			return [func(arg) for arg in tqdm(args, total=len(args), desc=desc, bar_format=bar_format, ascii=ascii, **tqdm_kwargs)]
 		else:
 			return [func(arg) for arg in args]
 
@@ -259,6 +285,7 @@ def run_in_subprocess[R](
 	func: Callable[..., R],
 	*args: Any,
 	timeout: float | None = None,
+	no_join: bool = False,
 	**kwargs: Any
 ) -> R:
 	""" Execute a function in a subprocess with positional and keyword arguments.
@@ -273,6 +300,7 @@ def run_in_subprocess[R](
 		*args        (Any):          Positional arguments to pass to the function.
 		timeout      (float | None): Maximum time in seconds to wait for the subprocess.
 			If None, wait indefinitely. If the subprocess exceeds this time, it will be terminated.
+		no_join      (bool):         If True, do not wait for the subprocess to finish (fire-and-forget).
 		**kwargs     (Any):          Keyword arguments to pass to the function.
 
 	Returns:
@@ -318,6 +346,8 @@ def run_in_subprocess[R](
 	process.start()
 
 	# Join with timeout to prevent indefinite hanging
+	if no_join:
+		return None  # type: ignore
 	process.join(timeout=timeout)
 
 	# Check if process is still alive (timed out)

{stouputils-1.13.1 → stouputils-1.13.3}/stouputils/print.py

@@ -45,6 +45,7 @@ def colored_for_loop[T](
 	color: str = MAGENTA,
 	bar_format: str = BAR_FORMAT,
 	ascii: bool = False,
+	smooth_tqdm: bool = True,
 	**kwargs: Any
 ) -> Iterator[T]:
 	""" Function to iterate over a list with a colored TQDM progress bar like the other functions in this module.
@@ -55,7 +56,7 @@ def colored_for_loop[T](
 		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 (Defaults to False)
-		verbose		(int):				Level of verbosity, decrease by 1 for each depth (Defaults to 1)
+		smooth_tqdm	(bool):				Whether to enable smooth progress bar updates by setting miniters=1 and mininterval=0.0 (Defaults to True)
 		**kwargs:						Additional arguments to pass to the TQDM progress bar
 
 	Yields:
@@ -70,6 +71,16 @@ def colored_for_loop[T](
 		bar_format = bar_format.replace(MAGENTA, color)
 	desc = color + desc
 
+	if smooth_tqdm:
+		kwargs.setdefault("mininterval", 0.0)
+		try:
+			total = len(iterable) # type: ignore
+			import shutil
+			width = shutil.get_terminal_size().columns
+			kwargs.setdefault("miniters", max(1, total // width))
+		except (TypeError, OSError):
+			kwargs.setdefault("miniters", 1)
+
 	from tqdm.auto import tqdm
 	yield from tqdm(iterable, desc=desc, bar_format=bar_format, ascii=ascii, **kwargs)
 
@@ -224,8 +235,10 @@ def whatisit(
 		try:
 			if not isinstance(value, str | bytes | bytearray | dict | int | float):
 				import numpy as np
-				metadata_parts.append(f"min: {np.min(value)}")
-				metadata_parts.append(f"max: {np.max(value)}")
+				mini, maxi = np.min(value), np.max(value)
+				if mini != maxi:
+					metadata_parts.append(f"min: {mini}")
+					metadata_parts.append(f"max: {maxi}")
 		except (Exception):
 			pass
 

{stouputils-1.13.1 → stouputils-1.13.3}/stouputils/stouputils/decorators.pyi

@@ -151,6 +151,16 @@ def simple_cache(func: Callable[..., Any] | None = None, *, method: Literal['str
 \t\t3
 \t\t>>> test2(3, 4)
 \t\t7
+
+\t\t>>> @simple_cache
+\t\t... def factorial(n: int) -> int:
+\t\t...     return n * factorial(n - 1) if n else 1
+\t\t>>> factorial(10)   # no previously cached result, makes 11 recursive calls
+\t\t3628800
+\t\t>>> factorial(5)    # no new calls, just returns the cached result
+\t\t120
+\t\t>>> factorial(12)   # two new recursive calls, factorial(10) is cached
+\t\t479001600
 \t'''
 def abstract(func: Callable[..., Any] | None = None, *, error_log: LogLevels = ...) -> Callable[..., Any]:
     """ Decorator that marks a function as abstract.

{stouputils-1.13.1 → stouputils-1.13.3}/stouputils/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) -> 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, 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.
@@ -35,6 +35,8 @@ def multiprocessing[T, R](func: Callable[..., R] | list[Callable[..., R]], args:
 \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
+\t\tsmooth_tqdm\t\t\t(bool):\t\t\t\tWhether to enable smooth progress bar updates by setting miniters and mininterval (Defaults to True)
+\t\t**tqdm_kwargs\t\t(Any):\t\t\t\tAdditional keyword arguments to pass to tqdm
 
 \tReturns:
 \t\tlist[object]:\tResults of the function execution
@@ -66,7 +68,7 @@ def multiprocessing[T, R](func: Callable[..., R] | list[Callable[..., R]], args:
 \t\t\t. )
 \t\t\t[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 \t'''
-def multithreading[T, R](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]:
+def multithreading[T, R](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, smooth_tqdm: bool = True, **tqdm_kwargs: Any) -> 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.
@@ -89,6 +91,8 @@ def multithreading[T, R](func: Callable[..., R] | list[Callable[..., R]], args:
 \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
+\t\tsmooth_tqdm\t\t\t(bool):\t\t\t\tWhether to enable smooth progress bar updates by setting miniters and mininterval (Defaults to True)
+\t\t**tqdm_kwargs\t\t(Any):\t\t\t\tAdditional keyword arguments to pass to tqdm
 
 \tReturns:
 \t\tlist[object]:\tResults of the function execution
@@ -120,7 +124,7 @@ def multithreading[T, R](func: Callable[..., R] | list[Callable[..., R]], args:
 \t\t\t. )
 \t\t\t[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 \t'''
-def run_in_subprocess[R](func: Callable[..., R], *args: Any, timeout: float | None = None, **kwargs: Any) -> R:
+def run_in_subprocess[R](func: Callable[..., R], *args: Any, timeout: float | None = None, no_join: bool = False, **kwargs: Any) -> R:
     ''' Execute a function in a subprocess with positional and keyword arguments.
 
 \tThis is useful when you need to run a function in isolation to avoid memory leaks,
@@ -133,6 +137,7 @@ def run_in_subprocess[R](func: Callable[..., R], *args: Any, timeout: float | No
 \t\t*args        (Any):          Positional arguments to pass to the function.
 \t\ttimeout      (float | None): Maximum time in seconds to wait for the subprocess.
 \t\t\tIf None, wait indefinitely. If the subprocess exceeds this time, it will be terminated.
+\t\tno_join      (bool):         If True, do not wait for the subprocess to finish (fire-and-forget).
 \t\t**kwargs     (Any):          Keyword arguments to pass to the function.
 
 \tReturns:

{stouputils-1.13.1 → stouputils-1.13.3}/stouputils/stouputils/print.pyi

@@ -15,7 +15,7 @@ previous_args_kwards: tuple[Any, Any]
 nb_values: int
 import_time: float
 
-def colored_for_loop[T](iterable: Iterable[T], desc: str = 'Processing', color: str = ..., bar_format: str = ..., ascii: bool = False, **kwargs: Any) -> Iterator[T]:
+def colored_for_loop[T](iterable: Iterable[T], desc: str = 'Processing', color: str = ..., bar_format: str = ..., ascii: bool = False, smooth_tqdm: bool = True, **kwargs: Any) -> Iterator[T]:
     ''' Function to iterate over a list with a colored TQDM progress bar like the other functions in this module.
 
 \tArgs:
@@ -24,7 +24,7 @@ def colored_for_loop[T](iterable: Iterable[T], desc: str = 'Processing', color:
 \t\tcolor\t\t(str):\t\t\t\tColor of the progress bar (Defaults to MAGENTA)
 \t\tbar_format\t(str):\t\t\t\tFormat of the progress bar (Defaults to BAR_FORMAT)
 \t\tascii\t\t(bool):\t\t\t\tWhether to use ASCII or Unicode characters for the progress bar (Defaults to False)
-\t\tverbose\t\t(int):\t\t\t\tLevel of verbosity, decrease by 1 for each depth (Defaults to 1)
+\t\tsmooth_tqdm\t(bool):\t\t\t\tWhether to enable smooth progress bar updates by setting miniters=1 and mininterval=0.0 (Defaults to True)
 \t\t**kwargs:\t\t\t\t\t\tAdditional arguments to pass to the TQDM progress bar
 
 \tYields: