stouputils 1.9.2__tar.gz → 1.9.4__tar.gz

{stouputils-1.9.2 → stouputils-1.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.9.2
+Version: 1.9.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
@@ -149,7 +149,7 @@ stouputils all_<TAB>    # Completes to: all_doctests
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.backup.html">backup.py</a>                <span class="comment"># 💾 Utilities for backup management (delta backup, consolidate)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.collections.html">collections.py</a>           <span class="comment"># 🧰 Utilities for collection manipulation (unique_list, sort_dict_keys, upsert_in_dataframe, array_to_disk)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.ctx.html">ctx.py</a>                   <span class="comment"># 🔇 Context managers (Muffle, LogToFile, MeasureTime, DoNothing)</span>
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.decorators.html">decorators.py</a>            <span class="comment"># 🎯 Decorators (measure_time, handle_error, simple_cache, retry, abstract, deprecated, silent)</span>
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.decorators.html">decorators.py</a>            <span class="comment"># 🎯 Decorators (measure_time, handle_error, timeout, retry, simple_cache, abstract, deprecated, silent)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.image.html">image.py</a>                 <span class="comment"># 🖼️ Little utilities for image processing (image_resize, auto_crop, numpy_to_gif, numpy_to_obj)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.io.html">io.py</a>                    <span class="comment"># 💾 Utilities for file management (super_json, super_csv, super_copy, super_open, clean_path)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.parallel.html">parallel.py</a>              <span class="comment"># 🔀 Utility functions for parallel processing (multiprocessing, multithreading)</span>

{stouputils-1.9.2 → stouputils-1.9.4}/README.md

@@ -107,7 +107,7 @@ stouputils all_<TAB>    # Completes to: all_doctests
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.backup.html">backup.py</a>                <span class="comment"># 💾 Utilities for backup management (delta backup, consolidate)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.collections.html">collections.py</a>           <span class="comment"># 🧰 Utilities for collection manipulation (unique_list, sort_dict_keys, upsert_in_dataframe, array_to_disk)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.ctx.html">ctx.py</a>                   <span class="comment"># 🔇 Context managers (Muffle, LogToFile, MeasureTime, DoNothing)</span>
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.decorators.html">decorators.py</a>            <span class="comment"># 🎯 Decorators (measure_time, handle_error, simple_cache, retry, abstract, deprecated, silent)</span>
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.decorators.html">decorators.py</a>            <span class="comment"># 🎯 Decorators (measure_time, handle_error, timeout, retry, simple_cache, abstract, deprecated, silent)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.image.html">image.py</a>                 <span class="comment"># 🖼️ Little utilities for image processing (image_resize, auto_crop, numpy_to_gif, numpy_to_obj)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.io.html">io.py</a>                    <span class="comment"># 💾 Utilities for file management (super_json, super_csv, super_copy, super_open, clean_path)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.parallel.html">parallel.py</a>              <span class="comment"># 🔀 Utility functions for parallel processing (multiprocessing, multithreading)</span>

{stouputils-1.9.2 → stouputils-1.9.4}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stouputils"
-version = "1.9.2"
+version = "1.9.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.10"

{stouputils-1.9.2 → stouputils-1.9.4}/stouputils/__main__.py

@@ -8,13 +8,14 @@ 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, show_version
 
 # Argument Parser Setup for Auto-Completion
 parser = argparse.ArgumentParser(prog="stouputils", add_help=False)
-parser.add_argument("command", nargs="?", choices=["--version", "-v", "all_doctests", "backup"])
+parser.add_argument("command", nargs="?", choices=["--version", "-v", "all_doctests", "archive", "backup"])
 parser.add_argument("args", nargs="*")
 argcomplete.autocomplete(parser)
 
@@ -33,6 +34,11 @@ def main() -> None:
 			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
+		return archive_cli()
+
 	# Handle "backup" command
 	if second_arg == "backup":
 		sys.argv.pop(1)  # Remove "backup" from argv so backup_cli gets clean arguments
@@ -58,6 +64,7 @@ def main() -> None:
 	print(f"\n{CYAN}Available commands:{RESET}")
 	print(f"  {GREEN}--version, -v{RESET}       Show version information")
 	print(f"  {GREEN}all_doctests{RESET} [dir]  Run all doctests in the specified directory")
+	print(f"  {GREEN}archive{RESET} --help      Archive utilities (make, repair)")
 	print(f"  {GREEN}backup{RESET} --help       Backup utilities (delta, consolidate, limit)")
 	print(f"{CYAN}{separator}{RESET}")
 	return

{stouputils-1.9.2 → stouputils-1.9.4}/stouputils/archive.py

@@ -17,7 +17,7 @@ from zipfile import ZIP_DEFLATED, ZipFile, ZipInfo
 
 from .decorators import LogLevels, handle_error
 from .io import clean_path, super_copy
-from .print import debug, error, info
+from .print import CYAN, GREEN, RESET, debug, error, info
 
 
 # Function that repair a corrupted zip file (ignoring some of the errors)
@@ -267,6 +267,24 @@ def archive_cli() -> None:
 	import argparse
 	import sys
 
+	# Check for help or no command
+	if len(sys.argv) == 1 or (len(sys.argv) == 2 and sys.argv[1] in ("--help", "-h", "help")):
+		separator: str = "─" * 60
+		print(f"{CYAN}{separator}{RESET}")
+		print(f"{CYAN}stouputils {GREEN}archive {CYAN}utilities{RESET}")
+		print(f"{CYAN}{separator}{RESET}")
+		print(f"\n{CYAN}Usage:{RESET} stouputils archive <command> [options]")
+		print(f"\n{CYAN}Available commands:{RESET}")
+		print(f"  {GREEN}make{RESET} <source> <destination> [--ignore PATTERNS] [--create-dir]")
+		print("      Create a zip archive from source directory")
+		print(f"      {CYAN}--ignore{RESET}      Glob patterns to ignore (comma-separated)")
+		print(f"      {CYAN}--create-dir{RESET}  Create destination directory if needed")
+		print(f"\n  {GREEN}repair{RESET} <input_file> [output_file]")
+		print("      Repair a corrupted zip file")
+		print("      If output_file is omitted, adds '_repaired' suffix")
+		print(f"{CYAN}{separator}{RESET}")
+		return
+
 	parser = argparse.ArgumentParser(description="Archive utilities")
 	subparsers = parser.add_subparsers(dest="command", help="Available commands")
 

{stouputils-1.9.2 → stouputils-1.9.4}/stouputils/archive.pyi

@@ -1,6 +1,6 @@
 from .decorators import LogLevels as LogLevels, handle_error as handle_error
 from .io import clean_path as clean_path, super_copy as super_copy
-from .print import debug as debug, error as error, info as info
+from .print import CYAN as CYAN, GREEN as GREEN, RESET as RESET, debug as debug, error as error, info as info
 
 def repair_zip_file(file_path: str, destination: str) -> bool:
     ''' Try to repair a corrupted zip file by ignoring some of the errors

{stouputils-1.9.2 → stouputils-1.9.4}/stouputils/backup.py

@@ -50,6 +50,23 @@ def backup_cli() -> None:
 		python -m stouputils.backup limit 5 /path/to/backups
 	"""
 	import argparse
+	import sys
+
+	# Check for help or no command
+	if len(sys.argv) == 1 or (len(sys.argv) == 2 and sys.argv[1] in ("--help", "-h", "help")):
+		separator: str = "─" * 60
+		print(f"{CYAN}{separator}{RESET}")
+		print(f"{CYAN}Backup Utilities{RESET}")
+		print(f"{CYAN}{separator}{RESET}")
+		print(f"\n{CYAN}Usage:{RESET} stouputils backup <command> [options]")
+		print(f"\n{CYAN}Available commands:{RESET}")
+		print(f"  {GREEN}delta{RESET}         Create a new delta backup")
+		print(f"  {GREEN}consolidate{RESET}   Consolidate existing backups into one")
+		print(f"  {GREEN}limit{RESET}         Limit the number of delta backups")
+		print(f"\n{CYAN}For detailed help on a specific command:{RESET}")
+		print("  stouputils backup <command> --help")
+		print(f"{CYAN}{separator}{RESET}")
+		return
 
 	# Setup command line argument parser
 	parser: argparse.ArgumentParser = argparse.ArgumentParser(
@@ -82,21 +99,6 @@ def backup_cli() -> None:
 	# Parse arguments and execute appropriate command
 	args: argparse.Namespace = parser.parse_args()
 
-	# Show custom help if no command is provided
-	if not args.command:
-		separator: str = "─" * 60
-		print(f"{CYAN}{separator}{RESET}")
-		print(f"{CYAN}Backup Utilities{RESET}")
-		print(f"{CYAN}{separator}{RESET}")
-		print(f"\n{CYAN}Usage:{RESET} stouputils backup <command> [options]")
-		print(f"\n{CYAN}Available commands:{RESET}")
-		print(f"  {GREEN}delta{RESET}         Create a new delta backup")
-		print(f"  {GREEN}consolidate{RESET}   Consolidate existing backups into one")
-		print(f"  {GREEN}limit{RESET}         Limit the number of delta backups")
-		print(f"\n{CYAN}For detailed help on a specific command:{RESET}")
-		print("  stouputils backup <command> --help")
-		print(f"{CYAN}{separator}{RESET}")
-		return
 
 	if args.command == "delta":
 		create_delta_backup(args.source, args.destination, args.exclude)

{stouputils-1.9.2 → stouputils-1.9.4}/stouputils/collections.py

@@ -15,6 +15,7 @@ import atexit
 import os
 import shutil
 import tempfile
+from collections.abc import Iterable
 from typing import TYPE_CHECKING, Any, Literal, TypeVar
 
 # Lazy imports for typing
@@ -28,14 +29,14 @@ if TYPE_CHECKING:
 T = TypeVar("T")
 
 # Functions
-def unique_list(list_to_clean: list[Any], method: Literal["id", "hash", "str"] = "str") -> list[Any]:
+def unique_list(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
 
 	Args:
-		list_to_clean	(list[Any]):					The list to clean
+		list_to_clean	(Iterable[T]):					The list to clean
 		method			(Literal["id", "hash", "str"]):	The method to use to identify duplicates
 	Returns:
-		list[Any]: The cleaned list
+		list[T]: The cleaned list
 
 	Examples:
 		>>> unique_list([1, 2, 3, 2, 1], method="id")
@@ -54,8 +55,8 @@ def unique_list(list_to_clean: list[Any], method: Literal["id", "hash", "str"] =
 		[{1, 2, 3}, {2, 3, 4}]
 	"""
 	# Initialize the seen ids set and the result list
-	seen: set[Any] = set()
-	result: list[Any] = []
+	seen: set[int | str] = set()
+	result: list[T] = []
 
 	# Iterate over each item in the list
 	for item in list_to_clean:

{stouputils-1.9.2 → stouputils-1.9.4}/stouputils/collections.pyi

@@ -1,18 +1,19 @@
 import polars as pl
 import zarr
+from collections.abc import Iterable
 from numpy.typing import NDArray as NDArray
 from typing import Any, Literal, TypeVar
 
 T = TypeVar('T')
 
-def unique_list(list_to_clean: list[Any], method: Literal['id', 'hash', 'str'] = 'str') -> list[Any]:
+def unique_list(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
 
 \tArgs:
-\t\tlist_to_clean\t(list[Any]):\t\t\t\t\tThe list to clean
+\t\tlist_to_clean\t(Iterable[T]):\t\t\t\t\tThe list to clean
 \t\tmethod\t\t\t(Literal["id", "hash", "str"]):\tThe method to use to identify duplicates
 \tReturns:
-\t\tlist[Any]: The cleaned list
+\t\tlist[T]: The cleaned list
 
 \tExamples:
 \t\t>>> unique_list([1, 2, 3, 2, 1], method="id")

{stouputils-1.9.2 → stouputils-1.9.4}/stouputils/ctx.py

@@ -5,6 +5,7 @@ This module provides context managers for temporarily silencing output.
 - MeasureTime: Context manager to measure execution time of a code block
 - Muffle: Context manager that temporarily silences output (alternative to stouputils.decorators.silent())
 - DoNothing: Context manager that does nothing (no-op)
+- SetMPStartMethod: Context manager to temporarily set multiprocessing start method
 
 .. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/ctx_module.gif
   :alt: stouputils ctx examples
@@ -284,3 +285,51 @@ class DoNothing:
 		""" Exit async context manager (does nothing) """
 		pass
 
+# Context manager to temporarily set multiprocessing start method
+class SetMPStartMethod:
+	""" Context manager to temporarily set multiprocessing start method.
+
+	This context manager allows you to temporarily change the multiprocessing start method
+	and automatically restores the original method when exiting the context.
+
+	Args:
+		start_method (str): The start method to use: "spawn", "fork", or "forkserver"
+
+	Examples:
+		.. code-block:: python
+
+			> import multiprocessing as mp
+			> import stouputils as stp
+			> # Temporarily use spawn method
+			> with stp.SetMPStartMethod("spawn"):
+			> ...     # Your multiprocessing code here
+			> ...     pass
+
+			> # Original method is automatically restored
+	"""
+	def __init__(self, start_method: str | None) -> None:
+		self.start_method: str | None = start_method
+		""" The start method to use """
+		self.old_method: str | None = None
+		""" The original start method to restore """
+
+	def __enter__(self) -> SetMPStartMethod:
+		""" Enter context manager which sets the start method """
+		if self.start_method is None:
+			return self
+		import multiprocessing as mp
+
+		self.old_method = mp.get_start_method(allow_none=True)
+		if self.old_method != self.start_method:
+			mp.set_start_method(self.start_method, force=True)
+		return self
+
+	def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+		""" Exit context manager which restores the original start method """
+		if self.start_method is None:
+			return
+		import multiprocessing as mp
+
+		if self.old_method != self.start_method:
+			mp.set_start_method(self.old_method, force=True)
+

{stouputils-1.9.2 → stouputils-1.9.4}/stouputils/ctx.pyi

@@ -141,3 +141,32 @@ class DoNothing:
         """ Enter async context manager (does nothing) """
     async def __aexit__(self, *excinfo: Any) -> None:
         """ Exit async context manager (does nothing) """
+
+class SetMPStartMethod:
+    ''' Context manager to temporarily set multiprocessing start method.
+
+\tThis context manager allows you to temporarily change the multiprocessing start method
+\tand automatically restores the original method when exiting the context.
+
+\tArgs:
+\t\tstart_method (str): The start method to use: "spawn", "fork", or "forkserver"
+
+\tExamples:
+\t\t.. code-block:: python
+
+\t\t\t> import multiprocessing as mp
+\t\t\t> import stouputils as stp
+\t\t\t> # Temporarily use spawn method
+\t\t\t> with stp.SetMPStartMethod("spawn"):
+\t\t\t> ...     # Your multiprocessing code here
+\t\t\t> ...     pass
+
+\t\t\t> # Original method is automatically restored
+\t'''
+    start_method: str | None
+    old_method: str | None
+    def __init__(self, start_method: str | None) -> None: ...
+    def __enter__(self) -> SetMPStartMethod:
+        """ Enter context manager which sets the start method """
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """ Exit context manager which restores the original start method """

{stouputils-1.9.2 → stouputils-1.9.4}/stouputils/decorators.py

@@ -3,8 +3,9 @@ This module provides decorators for various purposes:
 
 - measure_time(): Measure the execution time of a function and print it with the given print function
 - handle_error(): Handle an error with different log levels
-- simple_cache(): Easy cache function with parameter caching method
+- timeout(): Raise an exception if the function runs longer than the specified timeout
 - retry(): Retry a function when specific exceptions are raised, with configurable delay and max attempts
+- simple_cache(): Easy cache function with parameter caching method
 - abstract(): Mark a function as abstract, using LogLevels for error handling
 - deprecated(): Mark a function as deprecated, using LogLevels for warning handling
 - silent(): Make a function silent (disable stdout, and stderr if specified) (alternative to stouputils.ctx.Muffle)
@@ -167,67 +168,105 @@ def handle_error(
 		return decorator
 	return decorator(func)
 
-# Easy cache function with parameter caching method
-def simple_cache(
+# Decorator that raises an exception if the function runs too long
+def timeout(
 	func: Callable[..., Any] | None = None,
 	*,
-	method: Literal["str", "pickle"] = "str"
+	seconds: float = 60.0,
+	message: str = ""
 ) -> Callable[..., Any]:
-	""" Decorator that caches the result of a function based on its arguments.
+	""" Decorator that raises a TimeoutError if the function runs longer than the specified timeout.
 
-	The str method is often faster than the pickle method (by a little) but not as accurate with complex objects.
+	Note: This decorator uses SIGALRM on Unix systems, which only works in the main thread.
+	On Windows or in non-main threads, it will fall back to a polling-based approach.
 
 	Args:
-		func   (Callable[..., Any] | None): Function to cache
-		method (Literal["str", "pickle"]):  The method to use for caching.
+		func		(Callable[..., Any] | None):	Function to apply timeout to
+		seconds		(float):						Timeout duration in seconds (default: 60.0)
+		message		(str):							Custom timeout message (default: "Function '{func_name}' timed out after {seconds} seconds")
+
 	Returns:
-		Callable[..., Any]: A decorator that caches the result of a function.
+		Callable[..., Any]: Decorator that enforces timeout on the function
+
+	Raises:
+		TimeoutError: If the function execution exceeds the timeout duration
+
 	Examples:
-		>>> @simple_cache
-		... def test1(a: int, b: int) -> int:
-		...     return a + b
+		>>> @timeout(seconds=2.0)
+		... def slow_function():
+		...     time.sleep(5)
+		>>> slow_function()  # Raises TimeoutError after 2 seconds
+		Traceback (most recent call last):
+			...
+		TimeoutError: Function 'slow_function' timed out after 2.0 seconds
 
-		>>> @simple_cache(method="str")
-		... def test2(a: int, b: int) -> int:
-		...     return a + b
-		>>> test2(1, 2)
-		3
-		>>> test2(1, 2)
-		3
-		>>> test2(3, 4)
-		7
+		>>> @timeout(seconds=1.0, message="Custom timeout message")
+		... def another_slow_function():
+		...     time.sleep(3)
+		>>> another_slow_function()  # Raises TimeoutError after 1 second
+		Traceback (most recent call last):
+			...
+		TimeoutError: Custom timeout message
 	"""
 	def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
-		# Create the cache dict
-		cache_dict: dict[bytes, Any] = {}
-
-		# Create the wrapper
 		@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"
 
-			# Get the hashed key
-			if method == "str":
-				hashed: bytes = str(args).encode() + str(kwargs).encode()
-			elif method == "pickle":
-				hashed: bytes = pickle_dumps((args, kwargs))
-			else:
-				raise ValueError("Invalid caching method. Supported methods are 'str' and 'pickle'.")
+			# Try to use signal-based timeout (Unix only, main thread only)
+			try:
+				import signal
+				def timeout_handler(signum: int, frame: Any) -> None:
+					raise TimeoutError(msg)
 
-			# If the key is in the cache, return it
-			if hashed in cache_dict:
-				return cache_dict[hashed]
+				# Set the signal handler and alarm
+				old_handler = signal.signal(signal.SIGALRM, timeout_handler) # type: ignore
+				signal.setitimer(signal.ITIMER_REAL, seconds) # type: ignore
+
+				try:
+					result = func(*args, **kwargs)
+				finally:
+					# Cancel the alarm and restore the old handler
+					signal.setitimer(signal.ITIMER_REAL, 0) # type: ignore
+					signal.signal(signal.SIGALRM, old_handler) # type: ignore
 
-			# Else, call the function and add the result to the cache
-			else:
-				result: Any = func(*args, **kwargs)
-				cache_dict[hashed] = result
 				return result
 
-		# Return the wrapper
-		wrapper.__name__ = _get_wrapper_name("stouputils.decorators.simple_cache", func)
+			except (ValueError, AttributeError) as e:
+				# SIGALRM not available (Windows) or not in main thread
+				# Fall back to polling-based timeout (less precise but portable)
+				import threading
+
+				result_container: list[Any] = []
+				exception_container: list[BaseException] = []
+
+				def target() -> None:
+					try:
+						result_container.append(func(*args, **kwargs))
+					except BaseException as e_2:
+						exception_container.append(e_2)
+
+				thread = threading.Thread(target=target, daemon=True)
+				thread.start()
+				thread.join(timeout=seconds)
+
+				if thread.is_alive():
+					# Thread is still running, timeout occurred
+					raise TimeoutError(msg) from e
+
+				# Check if an exception was raised in the thread
+				if exception_container:
+					raise exception_container[0] from e
+
+				# Return the result if available
+				if result_container:
+					return result_container[0]
+
+		wrapper.__name__ = _get_wrapper_name("stouputils.decorators.timeout", func)
 		return wrapper
 
-	# Handle both @simple_cache and @simple_cache(method=...)
+	# Handle both @timeout and @timeout(seconds=..., message=...)
 	if func is None:
 		return decorator
 	return decorator(func)
@@ -307,6 +346,71 @@ def retry(
 		return decorator
 	return decorator(func)
 
+# Easy cache function with parameter caching method
+def simple_cache(
+	func: Callable[..., Any] | None = None,
+	*,
+	method: Literal["str", "pickle"] = "str"
+) -> Callable[..., Any]:
+	""" Decorator that caches the result of a function based on its arguments.
+
+	The str method is often faster than the pickle method (by a little) but not as accurate with complex objects.
+
+	Args:
+		func   (Callable[..., Any] | None): Function to cache
+		method (Literal["str", "pickle"]):  The method to use for caching.
+	Returns:
+		Callable[..., Any]: A decorator that caches the result of a function.
+	Examples:
+		>>> @simple_cache
+		... def test1(a: int, b: int) -> int:
+		...     return a + b
+
+		>>> @simple_cache(method="str")
+		... def test2(a: int, b: int) -> int:
+		...     return a + b
+		>>> test2(1, 2)
+		3
+		>>> test2(1, 2)
+		3
+		>>> test2(3, 4)
+		7
+	"""
+	def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+		# Create the cache dict
+		cache_dict: dict[bytes, Any] = {}
+
+		# Create the wrapper
+		@wraps(func)
+		def wrapper(*args: tuple[Any, ...], **kwargs: dict[str, Any]) -> Any:
+
+			# Get the hashed key
+			if method == "str":
+				hashed: bytes = str(args).encode() + str(kwargs).encode()
+			elif method == "pickle":
+				hashed: bytes = pickle_dumps((args, kwargs))
+			else:
+				raise ValueError("Invalid caching method. Supported methods are 'str' and 'pickle'.")
+
+			# If the key is in the cache, return it
+			if hashed in cache_dict:
+				return cache_dict[hashed]
+
+			# Else, call the function and add the result to the cache
+			else:
+				result: Any = func(*args, **kwargs)
+				cache_dict[hashed] = result
+				return result
+
+		# Return the wrapper
+		wrapper.__name__ = _get_wrapper_name("stouputils.decorators.simple_cache", func)
+		return wrapper
+
+	# Handle both @simple_cache and @simple_cache(method=...)
+	if func is None:
+		return decorator
+	return decorator(func)
+
 # Decorator that marks a function as abstract
 def abstract(
 	func: Callable[..., Any] | None = None,

{stouputils-1.9.2 → stouputils-1.9.4}/stouputils/decorators.pyi

@@ -64,30 +64,39 @@ def handle_error(func: Callable[..., Any] | None = None, *, exceptions: tuple[ty
 \t\t...     raise ValueError("Let\'s fail")
 \t\t>>> # test()\t# [WARNING HH:MM:SS] Error during test: (ValueError) Let\'s fail
 \t'''
-def simple_cache(func: Callable[..., Any] | None = None, *, method: Literal['str', 'pickle'] = 'str') -> Callable[..., Any]:
-    ''' Decorator that caches the result of a function based on its arguments.
+def timeout(func: Callable[..., Any] | None = None, *, seconds: float = 60.0, message: str = '') -> Callable[..., Any]:
+    ''' Decorator that raises a TimeoutError if the function runs longer than the specified timeout.
 
-\tThe str method is often faster than the pickle method (by a little) but not as accurate with complex objects.
+\tNote: This decorator uses SIGALRM on Unix systems, which only works in the main thread.
+\tOn Windows or in non-main threads, it will fall back to a polling-based approach.
 
 \tArgs:
-\t\tfunc   (Callable[..., Any] | None): Function to cache
-\t\tmethod (Literal["str", "pickle"]):  The method to use for caching.
+\t\tfunc\t\t(Callable[..., Any] | None):\tFunction to apply timeout to
+\t\tseconds\t\t(float):\t\t\t\t\t\tTimeout duration in seconds (default: 60.0)
+\t\tmessage\t\t(str):\t\t\t\t\t\t\tCustom timeout message (default: "Function \'{func_name}\' timed out after {seconds} seconds")
+
 \tReturns:
-\t\tCallable[..., Any]: A decorator that caches the result of a function.
+\t\tCallable[..., Any]: Decorator that enforces timeout on the function
+
+\tRaises:
+\t\tTimeoutError: If the function execution exceeds the timeout duration
+
 \tExamples:
-\t\t>>> @simple_cache
-\t\t... def test1(a: int, b: int) -> int:
-\t\t...     return a + b
+\t\t>>> @timeout(seconds=2.0)
+\t\t... def slow_function():
+\t\t...     time.sleep(5)
+\t\t>>> slow_function()  # Raises TimeoutError after 2 seconds
+\t\tTraceback (most recent call last):
+\t\t\t...
+\t\tTimeoutError: Function \'slow_function\' timed out after 2.0 seconds
 
-\t\t>>> @simple_cache(method="str")
-\t\t... def test2(a: int, b: int) -> int:
-\t\t...     return a + b
-\t\t>>> test2(1, 2)
-\t\t3
-\t\t>>> test2(1, 2)
-\t\t3
-\t\t>>> test2(3, 4)
-\t\t7
+\t\t>>> @timeout(seconds=1.0, message="Custom timeout message")
+\t\t... def another_slow_function():
+\t\t...     time.sleep(3)
+\t\t>>> another_slow_function()  # Raises TimeoutError after 1 second
+\t\tTraceback (most recent call last):
+\t\t\t...
+\t\tTimeoutError: Custom timeout message
 \t'''
 def retry(func: Callable[..., Any] | None = None, *, exceptions: tuple[type[BaseException], ...] | type[BaseException] = ..., max_attempts: int = 10, delay: float = 1.0, backoff: float = 1.0, message: str = '') -> Callable[..., Any]:
     ''' Decorator that retries a function when specific exceptions are raised.
@@ -118,6 +127,31 @@ def retry(func: Callable[..., Any] | None = None, *, exceptions: tuple[type[Base
 \t\t... def might_fail():
 \t\t...     pass
 \t'''
+def simple_cache(func: Callable[..., Any] | None = None, *, method: Literal['str', 'pickle'] = 'str') -> Callable[..., Any]:
+    ''' Decorator that caches the result of a function based on its arguments.
+
+\tThe str method is often faster than the pickle method (by a little) but not as accurate with complex objects.
+
+\tArgs:
+\t\tfunc   (Callable[..., Any] | None): Function to cache
+\t\tmethod (Literal["str", "pickle"]):  The method to use for caching.
+\tReturns:
+\t\tCallable[..., Any]: A decorator that caches the result of a function.
+\tExamples:
+\t\t>>> @simple_cache
+\t\t... def test1(a: int, b: int) -> int:
+\t\t...     return a + b
+
+\t\t>>> @simple_cache(method="str")
+\t\t... def test2(a: int, b: int) -> int:
+\t\t...     return a + b
+\t\t>>> test2(1, 2)
+\t\t3
+\t\t>>> test2(1, 2)
+\t\t3
+\t\t>>> test2(3, 4)
+\t\t7
+\t'''
 def abstract(func: Callable[..., Any] | None = None, *, error_log: LogLevels = ...) -> Callable[..., Any]:
     """ Decorator that marks a function as abstract.