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

stouputils/decorators.py

@@ -198,7 +198,7 @@ def timeout(
 		>>> slow_function()  # Raises TimeoutError after 2 seconds
 		Traceback (most recent call last):
 			...
-		TimeoutError: Function 'slow_function' timed out after 2.0 seconds
+		TimeoutError: Function 'slow_function()' timed out after 2.0 seconds
 
 		>>> @timeout(seconds=1.0, message="Custom timeout message")
 		... def another_slow_function():
@@ -209,59 +209,73 @@ def timeout(
 		TimeoutError: Custom timeout message
 	"""
 	def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+		# Check if we can use signal-based timeout (Unix only)
+		import os
+		use_signal: bool = os.name != 'nt'  # Not Windows
+
+		if use_signal:
+			try:
+				import signal
+				# Verify SIGALRM is available
+				use_signal = hasattr(signal, 'SIGALRM')
+			except ImportError:
+				use_signal = False
+
 		@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"
 
-			# Try to use signal-based timeout (Unix only, main thread only)
-			try:
+			# Use signal-based timeout on Unix (main thread only)
+			if use_signal:
 				import signal
-				def timeout_handler(signum: int, frame: Any) -> None:
-					raise TimeoutError(msg)
+				import threading
 
-				# Set the signal handler and alarm
-				old_handler = signal.signal(signal.SIGALRM, timeout_handler) # type: ignore
-				signal.setitimer(signal.ITIMER_REAL, seconds) # type: ignore
+				# Signal only works in main thread
+				if threading.current_thread() is threading.main_thread():
+					def timeout_handler(signum: int, frame: Any) -> None:
+						raise TimeoutError(msg)
 
-				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
+					# Set the signal handler and alarm
+					old_handler = signal.signal(signal.SIGALRM, timeout_handler) # type: ignore
+					signal.setitimer(signal.ITIMER_REAL, seconds) # type: ignore
 
-				return result
+					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
 
-			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
+					return result
 
-				result_container: list[Any] = []
-				exception_container: list[BaseException] = []
+			# Fall back to polling-based timeout (Windows or non-main thread)
+			import threading
 
-				def target() -> None:
-					try:
-						result_container.append(func(*args, **kwargs))
-					except BaseException as e_2:
-						exception_container.append(e_2)
+			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)
+			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
+			if thread.is_alive():
+				# Thread is still running, timeout occurred
+				raise TimeoutError(msg)
 
-				# Check if an exception was raised in the thread
-				if exception_container:
-					raise exception_container[0] from e
+			# Check if an exception was raised in the thread
+			if exception_container:
+				raise exception_container[0]
 
-				# Return the result if available
-				if result_container:
-					return result_container[0]
+			# Return the result if available
+			if result_container:
+				return result_container[0]
 
 		wrapper.__name__ = _get_wrapper_name("stouputils.decorators.timeout", func)
 		return wrapper
@@ -454,7 +468,7 @@ def abstract(
 		>>> Base().method()
 		Traceback (most recent call last):
 			...
-		NotImplementedError: Function 'method' is abstract and must be implemented by a subclass
+		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"

stouputils/decorators.pyi

@@ -88,7 +88,7 @@ def timeout(func: Callable[..., Any] | None = None, *, seconds: float = 60.0, me
 \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\tTimeoutError: Function \'slow_function()\' timed out after 2.0 seconds
 
 \t\t>>> @timeout(seconds=1.0, message="Custom timeout message")
 \t\t... def another_slow_function():
@@ -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.
@@ -180,7 +190,7 @@ def abstract(func: Callable[..., Any] | None = None, *, error_log: LogLevels = .
 \t\t>>> Base().method()
 \t\tTraceback (most recent call last):
 \t\t\t...
-\t\tNotImplementedError: Function 'method' is abstract and must be implemented by a subclass
+\t\tNotImplementedError: Function 'method()' is abstract and must be implemented by a subclass
 \t"""
 def deprecated(func: Callable[..., Any] | None = None, *, message: str = '', version: str = '', error_log: LogLevels = ...) -> Callable[..., Any]:
     ''' Decorator that marks a function as deprecated.

stouputils/installer/__init__.py

@@ -1,18 +1,18 @@
-""" Installer module for stouputils.
-
-Provides functions for platform-agnostic installation tasks by dispatching
-to platform-specific implementations (Windows, Linux/macOS).
-
-It handles getting installation paths, adding programs to the PATH environment variable,
-and installing programs from local zip files or URLs.
-"""
-# ruff: noqa: F403
-# ruff: noqa: F405
-
-# Imports
-from .common import *
-from .downloader import *
-from .linux import *
-from .main import *
-from .windows import *
-
+""" Installer module for stouputils.
+
+Provides functions for platform-agnostic installation tasks by dispatching
+to platform-specific implementations (Windows, Linux/macOS).
+
+It handles getting installation paths, adding programs to the PATH environment variable,
+and installing programs from local zip files or URLs.
+"""
+# ruff: noqa: F403
+# ruff: noqa: F405
+
+# Imports
+from .common import *
+from .downloader import *
+from .linux import *
+from .main import *
+from .windows import *
+

stouputils/installer/linux.py

@@ -1,144 +1,144 @@
-""" Installer module for Linux/macOS specific functions.
-
-Provides Linux/macOS specific implementations for checking admin privileges,
-determining appropriate installation paths (global/local), and suggesting
-how to add directories to the system's PATH environment variable.
-"""
-# Imports
-import os
-
-from ..decorators import LogLevels, handle_error
-from ..io import clean_path
-from ..print import debug, info, warning
-from .common import ask_install_type, prompt_for_path
-
-
-# Functions
-@handle_error(message="Failed to suggest how to add to PATH (Linux)", error_log=LogLevels.WARNING_TRACEBACK)
-def add_to_path_linux(install_path: str) -> bool:
-	""" Suggest how to add install_path to PATH on Linux.
-
-	Checks the current shell and provides instructions for adding the path
-	to the appropriate configuration file (e.g., .bashrc, .zshrc, config.fish).
-
-	Args:
-		install_path (str): The path to add to the PATH environment variable.
-
-	Returns:
-		bool: True if instructions were provided, False otherwise (e.g., unknown shell).
-	"""
-	shell_config_files: dict[str, str] = {
-		"bash": "~/.bashrc",
-		"zsh": "~/.zshrc",
-		"fish": "~/.config/fish/config.fish"
-	}
-	current_shell: str = os.environ.get("SHELL", "").split('/')[-1]
-	config_file: str | None = shell_config_files.get(current_shell)
-
-	if config_file:
-		export_cmd: str = ""
-		if current_shell == "fish":
-			export_cmd = f"set -gx PATH $PATH {install_path}"
-		else:
-			export_cmd = f"export PATH=\"$PATH:{install_path}\"" # Escape quotes for print
-
-		debug(
-			f"To add the installation directory to your PATH, add the following line to your '{config_file}':\n"
-			f"  {export_cmd}\n"
-			f"Then restart your shell or run 'source {config_file}'."
-		)
-		return True
-	else:
-		warning(f"Could not determine your shell configuration file. Please add '{install_path}' to your PATH manually.")
-		return False
-
-
-def check_admin_linux() -> bool:
-	""" Check if the script is running with root privileges on Linux/macOS.
-
-	Returns:
-		bool: True if the effective user ID is 0 (root), False otherwise.
-	"""
-	try:
-		return os.geteuid() == 0 # type: ignore
-	except AttributeError as e:
-		# os.geteuid() is not available on all platforms (e.g., Windows)
-		# This function should ideally only be called on Linux/macOS.
-		warning(f"Could not determine user privileges on this platform: {e}")
-		return False
-	except Exception as e:
-		warning(f"Error checking admin privileges: {e}")
-		return False
-
-
-@handle_error(message="Failed to get installation path (Linux)", error_log=LogLevels.ERROR_TRACEBACK)
-def get_install_path_linux(
-	program_name: str,
-	ask_global: int = 0,
-	add_path: bool = True,
-	append_to_path: str = "",
-	default_global: str = "/usr/local/bin",
-	) -> str:
-	""" Get the installation path for the program on Linux/macOS.
-
-	Args:
-		program_name   (str):   The name of the program to install.
-		ask_global     (int):   0 = ask for anything, 1 = install globally, 2 = install locally
-		add_path       (bool):  Whether to add the program to the PATH environment variable. (Only if installed globally)
-		append_to_path (str):   String to append to the installation path when adding to PATH.
-			(ex: "bin" if executables are in the bin folder)
-		default_global (str):   The default global installation path.
-			(Default is "/usr/local/bin" which is the most common location for executables on Linux/macOS,
-			could be "/opt" or any other directory)
-
-	Returns:
-		str: The chosen installation path, or an empty string if installation is cancelled.
-	"""
-	# Default paths
-	default_local_path: str = clean_path(os.path.join(os.getcwd(), program_name))
-
-	# Common global locations: /usr/local/bin for executables, /opt/ for self-contained apps
-	# We assume 'program_name' might be an executable or a directory, /usr/local/ is safer
-	default_global_path: str = clean_path(f"{default_global}/{program_name}") # Or potentially /opt/{program_name}
-
-	# Ask user for installation type (global/local)
-	install_type: str = ask_install_type(ask_global, default_local_path, default_global_path)
-
-	# Handle global installation choice
-	if install_type == 'g':
-		if not check_admin_linux():
-			warning(
-				f"Global installation typically requires sudo privileges to write to "
-				f"'{os.path.dirname(default_global_path)}'.\n"
-				f"You may need to re-run the script with 'sudo'.\n"
-				f"Install locally instead to '{default_local_path}'? (Y/n): "
-			)
-			if input().lower() == 'n':
-				info("Installation cancelled.")
-				return ""
-			else:
-				# Fallback to local path if user agrees
-				return prompt_for_path(
-					f"Falling back to local installation path: {default_local_path}.",
-					default_local_path
-				)
-		else:
-			# User is admin or proceeding with global install anyway
-			install_path: str = prompt_for_path(
-				f"Default global installation path is {default_global_path}.",
-				default_global_path
-			)
-			if add_path:
-				# Suggest adding the *directory* containing the program to PATH,
-				# or the path itself if it seems like a directory install
-				path_to_add: str = os.path.dirname(install_path) if os.path.isfile(install_path) else install_path
-				add_to_path_linux(os.path.join(path_to_add, append_to_path))
-			return install_path
-
-	# Handle local installation choice
-	else: # install_type == 'l'
-		return prompt_for_path(
-			f"Default local installation path is {default_local_path}.",
-			default_local_path
-		)
-
+""" Installer module for Linux/macOS specific functions.
+
+Provides Linux/macOS specific implementations for checking admin privileges,
+determining appropriate installation paths (global/local), and suggesting
+how to add directories to the system's PATH environment variable.
+"""
+# Imports
+import os
+
+from ..decorators import LogLevels, handle_error
+from ..io import clean_path
+from ..print import debug, info, warning
+from .common import ask_install_type, prompt_for_path
+
+
+# Functions
+@handle_error(message="Failed to suggest how to add to PATH (Linux)", error_log=LogLevels.WARNING_TRACEBACK)
+def add_to_path_linux(install_path: str) -> bool:
+	""" Suggest how to add install_path to PATH on Linux.
+
+	Checks the current shell and provides instructions for adding the path
+	to the appropriate configuration file (e.g., .bashrc, .zshrc, config.fish).
+
+	Args:
+		install_path (str): The path to add to the PATH environment variable.
+
+	Returns:
+		bool: True if instructions were provided, False otherwise (e.g., unknown shell).
+	"""
+	shell_config_files: dict[str, str] = {
+		"bash": "~/.bashrc",
+		"zsh": "~/.zshrc",
+		"fish": "~/.config/fish/config.fish"
+	}
+	current_shell: str = os.environ.get("SHELL", "").split('/')[-1]
+	config_file: str | None = shell_config_files.get(current_shell)
+
+	if config_file:
+		export_cmd: str = ""
+		if current_shell == "fish":
+			export_cmd = f"set -gx PATH $PATH {install_path}"
+		else:
+			export_cmd = f"export PATH=\"$PATH:{install_path}\"" # Escape quotes for print
+
+		debug(
+			f"To add the installation directory to your PATH, add the following line to your '{config_file}':\n"
+			f"  {export_cmd}\n"
+			f"Then restart your shell or run 'source {config_file}'."
+		)
+		return True
+	else:
+		warning(f"Could not determine your shell configuration file. Please add '{install_path}' to your PATH manually.")
+		return False
+
+
+def check_admin_linux() -> bool:
+	""" Check if the script is running with root privileges on Linux/macOS.
+
+	Returns:
+		bool: True if the effective user ID is 0 (root), False otherwise.
+	"""
+	try:
+		return os.geteuid() == 0 # type: ignore
+	except AttributeError as e:
+		# os.geteuid() is not available on all platforms (e.g., Windows)
+		# This function should ideally only be called on Linux/macOS.
+		warning(f"Could not determine user privileges on this platform: {e}")
+		return False
+	except Exception as e:
+		warning(f"Error checking admin privileges: {e}")
+		return False
+
+
+@handle_error(message="Failed to get installation path (Linux)", error_log=LogLevels.ERROR_TRACEBACK)
+def get_install_path_linux(
+	program_name: str,
+	ask_global: int = 0,
+	add_path: bool = True,
+	append_to_path: str = "",
+	default_global: str = "/usr/local/bin",
+	) -> str:
+	""" Get the installation path for the program on Linux/macOS.
+
+	Args:
+		program_name   (str):   The name of the program to install.
+		ask_global     (int):   0 = ask for anything, 1 = install globally, 2 = install locally
+		add_path       (bool):  Whether to add the program to the PATH environment variable. (Only if installed globally)
+		append_to_path (str):   String to append to the installation path when adding to PATH.
+			(ex: "bin" if executables are in the bin folder)
+		default_global (str):   The default global installation path.
+			(Default is "/usr/local/bin" which is the most common location for executables on Linux/macOS,
+			could be "/opt" or any other directory)
+
+	Returns:
+		str: The chosen installation path, or an empty string if installation is cancelled.
+	"""
+	# Default paths
+	default_local_path: str = clean_path(os.path.join(os.getcwd(), program_name))
+
+	# Common global locations: /usr/local/bin for executables, /opt/ for self-contained apps
+	# We assume 'program_name' might be an executable or a directory, /usr/local/ is safer
+	default_global_path: str = clean_path(f"{default_global}/{program_name}") # Or potentially /opt/{program_name}
+
+	# Ask user for installation type (global/local)
+	install_type: str = ask_install_type(ask_global, default_local_path, default_global_path)
+
+	# Handle global installation choice
+	if install_type == 'g':
+		if not check_admin_linux():
+			warning(
+				f"Global installation typically requires sudo privileges to write to "
+				f"'{os.path.dirname(default_global_path)}'.\n"
+				f"You may need to re-run the script with 'sudo'.\n"
+				f"Install locally instead to '{default_local_path}'? (Y/n): "
+			)
+			if input().lower() == 'n':
+				info("Installation cancelled.")
+				return ""
+			else:
+				# Fallback to local path if user agrees
+				return prompt_for_path(
+					f"Falling back to local installation path: {default_local_path}.",
+					default_local_path
+				)
+		else:
+			# User is admin or proceeding with global install anyway
+			install_path: str = prompt_for_path(
+				f"Default global installation path is {default_global_path}.",
+				default_global_path
+			)
+			if add_path:
+				# Suggest adding the *directory* containing the program to PATH,
+				# or the path itself if it seems like a directory install
+				path_to_add: str = os.path.dirname(install_path) if os.path.isfile(install_path) else install_path
+				add_to_path_linux(os.path.join(path_to_add, append_to_path))
+			return install_path
+
+	# Handle local installation choice
+	else: # install_type == 'l'
+		return prompt_for_path(
+			f"Default local installation path is {default_local_path}.",
+			default_local_path
+		)
+