stouputils 1.14.0__py3-none-any.whl

stouputils/stouputils/decorators.pyi

@@ -0,0 +1,252 @@
+from .ctx import MeasureTime as MeasureTime, Muffle as Muffle
+from .print import error as error, progress as progress, warning as warning
+from collections.abc import Callable as Callable
+from enum import Enum
+from typing import Any, Literal
+
+def measure_time(func: Callable[..., Any] | None = None, *, printer: Callable[..., None] = ..., message: str = '', perf_counter: bool = True, is_generator: bool = False) -> Callable[..., Any]:
+    ''' Decorator that will measure the execution time of a function and print it with the given print function
+
+\tArgs:
+\t\tfunc\t\t\t(Callable[..., Any] | None): Function to decorate
+\t\tprinter\t\t\t(Callable):\tFunction to use to print the execution time (e.g. debug, info, warning, error, etc.)
+\t\tmessage\t\t\t(str):\t\tMessage to display with the execution time (e.g. "Execution time of Something"),
+\t\t\tdefaults to "Execution time of {func.__name__}"
+\t\tperf_counter\t(bool):\t\tWhether to use time.perf_counter_ns or time.time_ns
+\t\t\tdefaults to True (use time.perf_counter_ns)
+\t\tis_generator\t(bool):\t\tWhether the function is a generator or not (default: False)
+\t\t\tWhen True, the decorator will yield from the function instead of returning it.
+
+\tReturns:
+\t\tCallable: Decorator to measure the time of the function.
+
+\tExamples:
+\t\t.. code-block:: python
+
+\t\t\t> @measure_time(printer=info)
+\t\t\t> def test():
+\t\t\t>     pass
+\t\t\t> test()  # [INFO HH:MM:SS] Execution time of test: 0.000ms (400ns)
+\t'''
+
+class LogLevels(Enum):
+    """ Log level for the errors in the decorator handle_error() """
+    NONE = 0
+    WARNING = 1
+    WARNING_TRACEBACK = 2
+    ERROR_TRACEBACK = 3
+    RAISE_EXCEPTION = 4
+
+force_raise_exception: bool
+
+def handle_error(func: Callable[..., Any] | None = None, *, exceptions: tuple[type[BaseException], ...] | type[BaseException] = ..., message: str = '', error_log: LogLevels = ..., sleep_time: float = 0.0) -> Callable[..., Any]:
+    ''' Decorator that handle an error with different log levels.
+
+\tArgs:
+\t\tfunc        (Callable[..., Any] | None):    \tFunction to decorate
+\t\texceptions\t(tuple[type[BaseException]], ...):\tExceptions to handle
+\t\tmessage\t\t(str):\t\t\t\t\t\t\t\tMessage to display with the error. (e.g. "Error during something")
+\t\terror_log\t(LogLevels):\t\t\t\t\t\tLog level for the errors
+\t\t\tLogLevels.NONE:\t\t\t\t\tNone
+\t\t\tLogLevels.WARNING:\t\t\t\tShow as warning
+\t\t\tLogLevels.WARNING_TRACEBACK:\tShow as warning with traceback
+\t\t\tLogLevels.ERROR_TRACEBACK:\t\tShow as error with traceback
+\t\t\tLogLevels.RAISE_EXCEPTION:\t\tRaise exception
+\t\tsleep_time\t(float):\t\t\t\t\t\t\tTime to sleep after the error (e.g. 0.0 to not sleep, 1.0 to sleep for 1 second)
+
+\tExamples:
+\t\t>>> @handle_error
+\t\t... def might_fail():
+\t\t...     raise ValueError("Let\'s fail")
+
+\t\t>>> @handle_error(error_log=LogLevels.WARNING)
+\t\t... def test():
+\t\t...     raise ValueError("Let\'s fail")
+\t\t>>> # test()\t# [WARNING HH:MM:SS] Error during test: (ValueError) Let\'s fail
+\t'''
+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.
+
+\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\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]: Decorator that enforces timeout on the function
+
+\tRaises:
+\t\tTimeoutError: If the function execution exceeds the timeout duration
+
+\tExamples:
+\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>>> @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.
+
+\tArgs:
+\t\tfunc\t\t\t(Callable[..., Any] | None):\t\tFunction to retry
+\t\texceptions\t\t(tuple[type[BaseException], ...]):\tExceptions to catch and retry on
+\t\tmax_attempts\t(int | None):\t\t\t\t\t\tMaximum number of attempts (None for infinite retries)
+\t\tdelay\t\t\t(float):\t\t\t\t\t\t\tInitial delay in seconds between retries (default: 1.0)
+\t\tbackoff\t\t\t(float):\t\t\t\t\t\t\tMultiplier for delay after each retry (default: 1.0 for constant delay)
+\t\tmessage\t\t\t(str):\t\t\t\t\t\t\t\tCustom message to display before ", retrying" (default: "{ExceptionName} encountered while running {func_name}")
+
+\tReturns:
+\t\tCallable[..., Any]: Decorator that retries the function on specified exceptions
+
+\tExamples:
+\t\t>>> import os
+\t\t>>> @retry(exceptions=PermissionError, max_attempts=3, delay=0.1)
+\t\t... def write_file():
+\t\t...     with open("test.txt", "w") as f:
+\t\t...         f.write("test")
+
+\t\t>>> @retry(exceptions=(OSError, IOError), delay=0.5, backoff=2.0)
+\t\t... def network_call():
+\t\t...     pass
+
+\t\t>>> @retry(max_attempts=5, delay=1.0)
+\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\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.
+
+\tContrary to the abstractmethod decorator from the abc module that raises a TypeError
+\twhen you try to instantiate a class that has abstract methods, this decorator raises
+\ta NotImplementedError ONLY when the decorated function is called, indicating that the function
+\tmust be implemented by a subclass.
+
+\tArgs:
+\t\tfunc                (Callable[..., Any] | None): The function to mark as abstract
+\t\terror_log           (LogLevels):                 Log level for the error handling
+\t\t\tLogLevels.NONE:              None
+\t\t\tLogLevels.WARNING:           Show as warning
+\t\t\tLogLevels.WARNING_TRACEBACK: Show as warning with traceback
+\t\t\tLogLevels.ERROR_TRACEBACK:   Show as error with traceback
+\t\t\tLogLevels.RAISE_EXCEPTION:   Raise exception
+
+\tReturns:
+\t\tCallable[..., Any]: Decorator that raises NotImplementedError when called
+
+\tExamples:
+\t\t>>> class Base:
+\t\t...     @abstract
+\t\t...     def method(self):
+\t\t...         pass
+\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"""
+def deprecated(func: Callable[..., Any] | None = None, *, message: str = '', version: str = '', error_log: LogLevels = ...) -> Callable[..., Any]:
+    ''' Decorator that marks a function as deprecated.
+
+\tArgs:
+\t\tfunc        (Callable[..., Any] | None): Function to mark as deprecated
+\t\tmessage     (str):                       Additional message to display with the deprecation warning
+\t\tversion     (str):                       Version since when the function is deprecated (e.g. "v1.2.0")
+\t\terror_log   (LogLevels):                 Log level for the deprecation warning
+\t\t\tLogLevels.NONE:              None
+\t\t\tLogLevels.WARNING:           Show as warning
+\t\t\tLogLevels.WARNING_TRACEBACK: Show as warning with traceback
+\t\t\tLogLevels.ERROR_TRACEBACK:   Show as error with traceback
+\t\t\tLogLevels.RAISE_EXCEPTION:   Raise exception
+\tReturns:
+\t\tCallable[..., Any]: Decorator that marks a function as deprecated
+
+\tExamples:
+\t\t>>> @deprecated
+\t\t... def old_function():
+\t\t...     pass
+
+\t\t>>> @deprecated(message="Use \'new_function()\' instead", error_log=LogLevels.WARNING)
+\t\t... def another_old_function():
+\t\t...     pass
+\t'''
+def silent(func: Callable[..., Any] | None = None, *, mute_stderr: bool = False) -> Callable[..., Any]:
+    ''' Decorator that makes a function silent (disable stdout, and stderr if specified).
+
+\tAlternative to stouputils.ctx.Muffle.
+
+\tArgs:
+\t\tfunc\t\t\t(Callable[..., Any] | None):\tFunction to make silent
+\t\tmute_stderr\t\t(bool):\t\t\t\t\t\t\tWhether to mute stderr or not
+
+\tExamples:
+\t\t>>> @silent
+\t\t... def test():
+\t\t...     print("Hello, world!")
+\t\t>>> test()
+
+\t\t>>> @silent(mute_stderr=True)
+\t\t... def test2():
+\t\t...     print("Hello, world!")
+\t\t>>> test2()
+
+\t\t>>> silent(print)("Hello, world!")
+\t'''
+def _get_func_name(func: Callable[..., Any]) -> str:
+    ''' Get the name of a function, returns "<unknown>" if the name cannot be retrieved. '''
+def _get_wrapper_name(decorator_name: str, func: Callable[..., Any]) -> str:
+    ''' Get a descriptive name for a wrapper function.
+
+\tArgs:
+\t\tdecorator_name\t(str):\t\t\t\t\tName of the decorator
+\t\tfunc\t\t\t(Callable[..., Any]):\tFunction being decorated
+\tReturns:
+\t\tstr: Combined name for the wrapper function (e.g., "stouputils.decorators.handle_error@function_name")
+\t'''

stouputils/stouputils/image.pyi

@@ -0,0 +1,172 @@
+import numpy as np
+from .io import super_open as super_open
+from .print import debug as debug, info as info
+from PIL import Image
+from collections.abc import Callable
+from numpy.typing import NDArray
+from typing import Any, TypeVar
+
+PIL_Image_or_NDArray = TypeVar('PIL_Image_or_NDArray', bound='Image.Image | NDArray[np.number]')
+
+def image_resize[PIL_Image_or_NDArray](image: PIL_Image_or_NDArray, max_result_size: int, resampling: Image.Resampling | None = None, min_or_max: Callable[[int, int], int] = ..., return_type: type[PIL_Image_or_NDArray] | str = 'same', keep_aspect_ratio: bool = True) -> Any:
+    ''' Resize an image while preserving its aspect ratio by default.
+\tScales the image so that its largest dimension equals max_result_size.
+
+\tArgs:
+\t\timage             (Image.Image | np.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.
+\t\treturn_type       (type | str):               Type of the return value (Image.Image, np.ndarray, or "same" to match input type).
+\t\tkeep_aspect_ratio (bool):                     Whether to keep the aspect ratio.
+\tReturns:
+\t\tImage.Image | NDArray[np.number]: The resized image with preserved aspect ratio.
+\tExamples:
+\t\t>>> # Test with (height x width x channels) numpy array
+\t\t>>> import numpy as np
+\t\t>>> array = np.random.randint(0, 255, (100, 50, 3), dtype=np.uint8)
+\t\t>>> image_resize(array, 100).shape
+\t\t(100, 50, 3)
+\t\t>>> image_resize(array, 100, min_or_max=max).shape
+\t\t(100, 50, 3)
+\t\t>>> image_resize(array, 100, min_or_max=min).shape
+\t\t(200, 100, 3)
+
+\t\t>>> # Test with PIL Image
+\t\t>>> from PIL import Image
+\t\t>>> pil_image: Image.Image = Image.new(\'RGB\', (200, 100))
+\t\t>>> image_resize(pil_image, 50).size
+\t\t(50, 25)
+\t\t>>> # Test with different return types
+\t\t>>> resized_array = image_resize(array, 50, return_type=np.ndarray)
+\t\t>>> isinstance(resized_array, np.ndarray)
+\t\tTrue
+\t\t>>> resized_array.shape
+\t\t(50, 25, 3)
+\t\t>>> # Test with different resampling methods
+\t\t>>> image_resize(pil_image, 50, resampling=Image.Resampling.NEAREST).size
+\t\t(50, 25)
+\t'''
+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, return_type: type[PIL_Image_or_NDArray] | str = 'same', contiguous: bool = True) -> Any:
+    ''' Automatically crop an image to remove zero or uniform regions.
+
+\tThis function crops the image to keep only the region where pixels are non-zero
+\t(or above a threshold). It can work with a mask or directly analyze the image.
+
+\tArgs:
+\t\timage       (Image.Image | NDArray):\t  The image to crop.
+\t\tmask        (NDArray[bool] | None):       Optional binary mask indicating regions to keep.
+\t\tthreshold   (int | float | Callable):     Threshold value or function (default: np.min).
+\t\treturn_type (type | str):                 Type of the return value (Image.Image, NDArray[np.number], or "same" to match input type).
+\t\tcontiguous  (bool):                       If True (default), crop to bounding box. If False, remove entire rows/columns with no content.
+\tReturns:
+\t\tImage.Image | NDArray[np.number]: The cropped image.
+
+\tExamples:
+\t\t>>> # Test with numpy array with zeros on edges
+\t\t>>> import numpy as np
+\t\t>>> array = np.zeros((100, 100, 3), dtype=np.uint8)
+\t\t>>> array[20:80, 30:70] = 255  # White rectangle in center
+\t\t>>> cropped = auto_crop(array, return_type=np.ndarray)
+\t\t>>> cropped.shape
+\t\t(60, 40, 3)
+
+\t\t>>> # Test with custom mask
+\t\t>>> mask = np.zeros((100, 100), dtype=bool)
+\t\t>>> mask[10:90, 10:90] = True
+\t\t>>> cropped_with_mask = auto_crop(array, mask=mask, return_type=np.ndarray)
+\t\t>>> cropped_with_mask.shape
+\t\t(80, 80, 3)
+
+\t\t>>> # Test with PIL Image
+\t\t>>> from PIL import Image
+\t\t>>> pil_image = Image.new(\'RGB\', (100, 100), (0, 0, 0))
+\t\t>>> from PIL import ImageDraw
+\t\t>>> draw = ImageDraw.Draw(pil_image)
+\t\t>>> draw.rectangle([25, 25, 75, 75], fill=(255, 255, 255))
+\t\t>>> cropped_pil = auto_crop(pil_image)
+\t\t>>> cropped_pil.size
+\t\t(51, 51)
+
+\t\t>>> # Test with threshold
+\t\t>>> array_gray = np.ones((100, 100), dtype=np.uint8) * 10
+\t\t>>> array_gray[20:80, 30:70] = 255
+\t\t>>> cropped_threshold = auto_crop(array_gray, threshold=50, return_type=np.ndarray)
+\t\t>>> cropped_threshold.shape
+\t\t(60, 40)
+
+\t\t>>> # Test with callable threshold (using lambda to avoid min value)
+\t\t>>> array_gray2 = np.ones((100, 100), dtype=np.uint8) * 10
+\t\t>>> array_gray2[20:80, 30:70] = 255
+\t\t>>> cropped_max = auto_crop(array_gray2, threshold=lambda x: 50, return_type=np.ndarray)
+\t\t>>> cropped_max.shape
+\t\t(60, 40)
+
+\t>>> # Test with non-contiguous crop
+\t>>> array_sparse = np.zeros((100, 100, 3), dtype=np.uint8)
+\t>>> array_sparse[10, 10] = 255
+\t>>> array_sparse[50, 50] = 255
+\t>>> array_sparse[90, 90] = 255
+\t>>> cropped_contiguous = auto_crop(array_sparse, contiguous=True, return_type=np.ndarray)
+\t>>> cropped_contiguous.shape  # Bounding box from (10,10) to (90,90)
+\t(81, 81, 3)
+\t>>> cropped_non_contiguous = auto_crop(array_sparse, contiguous=False, return_type=np.ndarray)
+\t>>> cropped_non_contiguous.shape  # Only rows/cols 10, 50, 90
+\t(3, 3, 3)
+
+\t>>> # Test with 3D crop on depth dimension
+\t>>> array_3d = np.zeros((50, 50, 10), dtype=np.uint8)
+\t>>> array_3d[10:40, 10:40, 2:8] = 255  # Content only in depth slices 2-7
+\t>>> cropped_3d = auto_crop(array_3d, contiguous=True, return_type=np.ndarray)
+\t>>> cropped_3d.shape  # Should crop all 3 dimensions
+\t(30, 30, 6)
+\t'''
+def numpy_to_gif(path: str, array: NDArray[np.integer | np.floating | np.bool_], duration: int = 100, loop: int = 0, mkdir: bool = True, **kwargs: Any) -> None:
+    ''' Generate a \'.gif\' file from a numpy array for 3D/4D visualization.
+
+\tArgs:
+\t\tpath     (str):     Path to the output .gif file.
+\t\tarray    (NDArray): Numpy array to be dumped (must be 3D or 4D).
+\t\t\t3D: (depth, height, width) - e.g. (64, 1024, 1024)
+\t\t\t4D: (depth, height, width, channels) - e.g. (50, 64, 1024, 3)
+\t\tduration (int):     Duration between frames in milliseconds.
+\t\tloop     (int):     Number of loops (0 = infinite).
+\t\tmkdir    (bool):    Create the directory if it does not exist.
+\t\t**kwargs (Any):     Additional keyword arguments for PIL.Image.save().
+
+\tExamples:
+
+\t\t.. code-block:: python
+
+\t\t\t> # 3D array example
+\t\t\t> array = np.random.randint(0, 256, (10, 100, 100), dtype=np.uint8)
+\t\t\t> numpy_to_gif("output_10_frames_100x100.gif", array, duration=200, loop=0)
+
+\t\t\t> # 4D array example (batch of 3D images)
+\t\t\t> array_4d = np.random.randint(0, 256, (5, 10, 100, 3), dtype=np.uint8)
+\t\t\t> numpy_to_gif("output_50_frames_100x100.gif", array_4d, duration=200)
+
+\t\t\t> total_duration = 1000  # 1 second
+\t\t\t> numpy_to_gif("output_1s.gif", array, duration=total_duration // len(array))
+\t'''
+def numpy_to_obj(path: str, array: NDArray[np.integer | np.floating | np.bool_], threshold: float = 0.5, step_size: int = 1, pad_array: bool = True, verbose: int = 0) -> None:
+    ''' Generate a \'.obj\' file from a numpy array for 3D visualization using marching cubes.
+
+\tArgs:
+\t\tpath      (str):     Path to the output .obj file.
+\t\tarray     (NDArray): Numpy array to be dumped (must be 3D).
+\t\tthreshold (float):   Threshold level for marching cubes (0.5 for binary data).
+\t\tstep_size (int):     Step size for marching cubes (higher = simpler mesh, faster generation).
+\t\tpad_array (bool):    If True, pad array with zeros to ensure closed volumes for border cells.
+\t\tverbose   (int):     Verbosity level (0 = no output, 1 = some output, 2 = full output).
+
+\tExamples:
+
+\t\t.. code-block:: python
+
+\t\t\t> array = np.random.rand(64, 64, 64) > 0.5  # Binary volume
+\t\t\t> numpy_to_obj("output_mesh.obj", array, threshold=0.5, step_size=2, pad_array=True, verbose=1)
+
+\t\t\t> array = my_3d_data  # Some 3D numpy array (e.g. human lung scan)
+\t\t\t> numpy_to_obj("output_mesh.obj", array, threshold=0.3)
+\t'''

stouputils/stouputils/installer/__init__.pyi

@@ -0,0 +1,5 @@
+from .common import *
+from .downloader import *
+from .linux import *
+from .main import *
+from .windows import *

stouputils/stouputils/installer/common.pyi

@@ -0,0 +1,39 @@
+from ..print import warning as warning
+from typing import Literal
+
+def prompt_for_path(prompt_message: str, default_path: str) -> str:
+    """ Prompt the user to override a default path.
+
+\tArgs:
+\t\tprompt_message (str): The message to display to the user.
+\t\tdefault_path   (str): The default path to suggest.
+
+\tReturns:
+\t\tstr: The path entered by the user, or the default path if they pressed Enter.
+\t"""
+def ask_install_type(ask_global: int, default_local_path: str, default_global_path: str | None) -> Literal['g', 'l']:
+    ''' Determine the installation type (global \'g\' or local \'l\') based on user input.
+
+\tArgs:
+\t\task_global          (int):           0 = ask, 1 = force global, 2 = force local.
+\t\tdefault_local_path  (str):           The default local path.
+\t\tdefault_global_path (str | None):    The default global path (if applicable).
+
+\tReturns:
+\t\tLiteral["g", "l"]: \'g\' for global install, \'l\' for local install.
+
+\tExamples:
+\t\t.. code-block:: python
+
+\t\t\t> # Ask the user while providing default paths
+\t\t\t> install_choice: str = ask_install_type(0, f"{os.getcwd()}/MyProgram", "C:\\Program Files\\MyProgram")
+\t\t\tg
+
+\t\t\t> # Don\'t ask, force global
+\t\t\t> install_choice: str = ask_install_type(1, ...)
+\t\t\tg
+
+\t\t\t> # Don\'t ask, force local
+\t\t\t> install_choice: str = ask_install_type(2, ...)
+\t\t\tl
+\t'''

stouputils/stouputils/installer/downloader.pyi

@@ -0,0 +1,24 @@
+from ..print import info as info, warning as warning
+from .main import install_program as install_program
+
+def download_executable(download_urls: dict[str, str], program_name: str, append_to_path: str = '') -> bool:
+    """ Ask the user if they want to download the program (ex: waifu2x-ncnn-vulkan).
+\tIf yes, try to download the program from the GitHub releases page.
+
+\tArgs:
+\t\tdownload_urls  (dict[str, str]):  The URLs to download the program from.
+\t\tprogram_name   (str):             The name of the program to download.
+
+\tReturns:
+\t\tbool: True if the program is now ready to use, False otherwise.
+\t"""
+def check_executable(executable: str, executable_help_text: str, download_urls: dict[str, str], append_to_path: str = '') -> None:
+    ''' Check if the executable exists, optionally download it if it doesn\'t.
+
+\tArgs:
+\t\texecutable            (str):             The path to the executable.
+\t\texecutable_help_text  (str):             The help text to check for in the executable\'s output.
+\t\tdownload_urls         (dict[str, str]):  The URLs to download the executable from.
+\t\tappend_to_path        (str):             The path to append to the executable\'s path.
+\t\t\t(ex: "bin" if executables are in the bin folder)
+\t'''

stouputils/stouputils/installer/linux.pyi

@@ -0,0 +1,39 @@
+from ..decorators import LogLevels as LogLevels, handle_error as handle_error
+from ..io import clean_path as clean_path
+from ..print import debug as debug, info as info, warning as warning
+from .common import ask_install_type as ask_install_type, prompt_for_path as prompt_for_path
+
+def add_to_path_linux(install_path: str) -> bool:
+    """ Suggest how to add install_path to PATH on Linux.
+
+\tChecks the current shell and provides instructions for adding the path
+\tto the appropriate configuration file (e.g., .bashrc, .zshrc, config.fish).
+
+\tArgs:
+\t\tinstall_path (str): The path to add to the PATH environment variable.
+
+\tReturns:
+\t\tbool: True if instructions were provided, False otherwise (e.g., unknown shell).
+\t"""
+def check_admin_linux() -> bool:
+    """ Check if the script is running with root privileges on Linux/macOS.
+
+\tReturns:
+\t\tbool: True if the effective user ID is 0 (root), False otherwise.
+\t"""
+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.
+
+\tArgs:
+\t\tprogram_name   (str):   The name of the program to install.
+\t\task_global     (int):   0 = ask for anything, 1 = install globally, 2 = install locally
+\t\tadd_path       (bool):  Whether to add the program to the PATH environment variable. (Only if installed globally)
+\t\tappend_to_path (str):   String to append to the installation path when adding to PATH.
+\t\t\t(ex: "bin" if executables are in the bin folder)
+\t\tdefault_global (str):   The default global installation path.
+\t\t\t(Default is "/usr/local/bin" which is the most common location for executables on Linux/macOS,
+\t\t\tcould be "/opt" or any other directory)
+
+\tReturns:
+\t\tstr: The chosen installation path, or an empty string if installation is cancelled.
+\t'''

stouputils/stouputils/installer/main.pyi

@@ -0,0 +1,57 @@
+from .common import *
+from .linux import *
+from .windows import *
+from ..decorators import LogLevels as LogLevels, handle_error as handle_error
+from ..print import info as info, warning as warning
+from collections.abc import Callable as Callable
+
+def extract_archive(extraction_path: str, temp_dir: str, extract_func: Callable[[str], None], get_file_list_func: Callable[[], list[str]]) -> None:
+    """ Helper function to extract archive files with consistent handling.
+
+\tArgs:
+\t\textraction_path     (str): Path where files should be extracted
+\t\ttemp_dir            (str): Temporary directory for intermediate extraction
+\t\textract_func        (Callable[[str], None]): Function to extract the archive
+\t\tget_file_list_func  (Callable[[], list[str]]): Function to get the list of files in the archive
+\t"""
+def get_install_path(program_name: str, platform_str: str = ..., ask_global: int = 0, add_path: bool = True, append_to_path: str = '') -> str:
+    ''' Get the installation path for the program on the current platform.
+
+\tArgs:
+\t\tprogram_name  (str):  The name of the program to install.
+\t\tplatform_str  (str):  The platform to get the installation path for.
+\t\task_global    (int):  Whether to ask the user for a path, 0 = ask, 1 = install globally, 2 = install locally.
+\t\tadd_path      (bool): Whether to add the program to the PATH environment variable.
+\t\tappend_to_path (str):  String to append to the installation path when adding to PATH.
+\t\t\t(ex: "bin" if executables are in the bin folder)
+
+\tReturns:
+\t\tstr: The installation path for the program.
+\t'''
+def add_to_path(install_path: str, platform_str: str = ...) -> bool:
+    ''' Add the program to the PATH environment variable.
+
+\tArgs:
+\t\tinstall_path  (str):  The path to the program to add to the PATH environment variable.
+\t\tplatform_str  (str):  The platform you are running on (ex: "Windows", "Linux", "Darwin", ...),
+\t\t\twe use this to determine the installation path if not provided.
+
+\tReturns:
+\t\tbool: True if add to PATH was successful, False otherwise.
+\t'''
+def install_program(input_path: str, install_path: str = '', platform_str: str = ..., program_name: str = '', add_path: bool = True, append_to_path: str = '') -> bool:
+    ''' Install a program to a specific path from a local zip file or URL.
+
+\tArgs:
+\t\tinput_path     (str):  Path to a zip file or a download URL.
+\t\tinstall_path   (str):  The directory to extract the program into, we ask user for a path if not provided.
+\t\tplatform_str   (str):  The platform you are running on (ex: "Windows", "Linux", "Darwin", ...),
+\t\t\twe use this to determine the installation path if not provided.
+\t\tadd_path       (bool): Whether to add the program to the PATH environment variable.
+\t\tprogram_name   (str):  Override the program name, we get it from the input path if not provided.
+\t\tappend_to_path (str):  String to append to the installation path when adding to PATH.
+\t\t\t(ex: "bin" if executables are in the bin folder)
+
+\tReturns:
+\t\tbool: True if installation was successful, False otherwise.
+\t'''

stouputils/stouputils/installer/windows.pyi

@@ -0,0 +1,31 @@
+from ..decorators import LogLevels as LogLevels, handle_error as handle_error
+from ..io import clean_path as clean_path
+from ..print import debug as debug, info as info, warning as warning
+from .common import ask_install_type as ask_install_type, prompt_for_path as prompt_for_path
+
+def add_to_path_windows(install_path: str) -> bool | None:
+    """ Add install_path to the User PATH environment variable on Windows.
+
+\tArgs:
+\t\tinstall_path (str): The path to add to the User PATH environment variable.
+
+\tReturns:
+\t\tbool | None: True if the path was added to the User PATH environment variable, None otherwise.
+\t"""
+def check_admin_windows() -> bool:
+    """ Check if the script is running with administrator privileges on Windows. """
+def get_install_path_windows(program_name: str, ask_global: int = 0, add_path: bool = True, append_to_path: str = '', default_global: str = ...) -> str:
+    ''' Get the installation path for the program
+
+\tArgs:
+\t\tprogram_name  (str):   The name of the program to install.
+\t\task_global    (int):   0 = ask for anything, 1 = install globally, 2 = install locally
+\t\tadd_path      (bool):  Whether to add the program to the PATH environment variable. (Only if installed globally)
+\t\tappend_to_path (str):  String to append to the installation path when adding to PATH.
+\t\t\t(ex: "bin" if executables are in the bin folder)
+\t\tdefault_global (str):  The default global installation path.
+\t\t\t(Default is "C:\\Program Files" which is the most common location for executables on Windows)
+
+\tReturns:
+\t\tstr: The installation path.
+\t'''