stouputils 1.12.2__py3-none-any.whl → 1.13.1__py3-none-any.whl

stouputils/stouputils/continuous_delivery/pyproject.pyi

@@ -0,0 +1,67 @@
+from ..io import super_open as super_open
+from typing import Any
+
+def read_pyproject(pyproject_path: str) -> dict[str, Any]:
+    ''' Read the pyproject.toml file.
+
+\tArgs:
+\t\tpyproject_path: Path to the pyproject.toml file.
+\tReturns:
+\t\tdict[str, Any]: The content of the pyproject.toml file.
+\tExample:
+\t\t>>> content = read_pyproject("pyproject.toml")
+\t\t>>> "." in content["project"]["version"]
+\t\tTrue
+\t'''
+def format_toml_lists(content: str) -> str:
+    ''' Format TOML lists with indentation.
+
+\tArgs:
+\t\tcontent (str): The content of the pyproject.toml file.
+\tReturns:
+\t\tstr: The formatted content with properly indented lists.
+\tExample:
+\t\t>>> toml_content = \'\'\'[project]
+\t\t... dependencies = [ "tqdm>=4.0.0", "requests>=2.20.0", "pyyaml>=6.0.0", ]\'\'\'
+\t\t>>> format_toml_lists(toml_content).replace("\\t", "    ") == \'\'\'[project]
+\t\t... dependencies = [
+\t\t...     "tqdm>=4.0.0",
+\t\t...     "requests>=2.20.0",
+\t\t...     "pyyaml>=6.0.0",
+\t\t... ]\'\'\'
+\t\tTrue
+\t'''
+def write_pyproject(path: str, content: dict[str, Any]) -> None:
+    """ Write to the pyproject.toml file with properly indented lists.
+
+\tArgs:
+\t\tpath: Path to the pyproject.toml file.
+\t\tcontent: Content to write to the pyproject.toml file.
+\t"""
+def increment_version_from_input(version: str) -> str:
+    ''' Increment the version.
+
+\tArgs:
+\t\tversion: The version to increment. (ex: "0.1.0")
+\tReturns:
+\t\tstr: The incremented version. (ex: "0.1.1")
+\tExample:
+\t\t>>> increment_version_from_input("0.1.0")
+\t\t\'0.1.1\'
+\t\t>>> increment_version_from_input("1.2.9")
+\t\t\'1.2.10\'
+\t'''
+def increment_version_from_pyproject(path: str) -> None:
+    """ Increment the version in the pyproject.toml file.
+
+\tArgs:
+\t\tpath: Path to the pyproject.toml file.
+\t"""
+def get_version_from_pyproject(path: str) -> str:
+    ''' Get the version from the pyproject.toml file.
+
+\tArgs:
+\t\tpath: Path to the pyproject.toml file.
+\tReturns:
+\t\tstr: The version. (ex: "0.1.0")
+\t'''

stouputils/stouputils/continuous_delivery/stubs.pyi

@@ -0,0 +1,39 @@
+from ..decorators import LogLevels as LogLevels, handle_error as handle_error
+from collections.abc import Callable as Callable
+
+def generate_stubs(package_name: str, extra_args: str = '--include-docstrings --include-private') -> int:
+    ''' Generate stub files for a Python package using stubgen.
+
+\tNote: stubgen generates stubs in the \'out\' directory by default in the current working directory.
+
+\tArgs:
+\t\tpackage_name  (str): Name of the package to generate stubs for.
+\t\textra_args    (str): Extra arguments to pass to stubgen. Defaults to "--include-docstrings --include-private".
+\tReturns:
+\t\tint: Return code of the os.system call.
+\t'''
+def clean_stubs_directory(output_directory: str, package_name: str) -> None:
+    """ Clean the stubs directory by deleting all .pyi files.
+
+\tArgs:
+\t\toutput_directory  (str): Directory to clean.
+\t\tpackage_name      (str): Package name subdirectory. Only cleans output_directory/package_name.
+\t"""
+def stubs_full_routine(package_name: str, output_directory: str = 'typings', extra_args: str = '--include-docstrings --include-private', clean_before: bool = False, generate_stubs_function: Callable[[str, str], int] = ..., clean_stubs_function: Callable[[str, str], None] = ...) -> None:
+    ''' Generate stub files for a Python package using stubgen.
+
+\tNote: stubgen generates stubs in the \'out\' directory by default in the current working directory.
+
+\tArgs:
+\t\tpackage_name              (str):                       Name of the package to generate stubs for.
+\t\toutput_directory          (str):                       Directory to clean before generating stubs. Defaults to "typings".
+\t\t\tThis parameter is used for cleaning the directory before stub generation.
+\t\textra_args                (str):                       Extra arguments to pass to stubgen. Defaults to "--include-docstrings --include-private".
+\t\tclean_before              (bool):                      Whether to clean the output directory before generating stubs. Defaults to False.
+\t\tgenerate_stubs_function   (Callable[[str, str], int]): Function to generate stubs.
+\t\t\tDefaults to :func:`generate_stubs`.
+\t\tclean_stubs_function      (Callable[[str], None]):     Function to clean the stubs directory.
+\t\t\tDefaults to :func:`clean_stubs_directory`.
+\tRaises:
+\t\tException: If stub generation fails.
+\t'''

stouputils/stouputils/ctx.pyi

@@ -0,0 +1,211 @@
+import abc
+from .io import super_open as super_open
+from .print import TeeMultiOutput as TeeMultiOutput, debug as debug
+from collections.abc import Callable as Callable
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from typing import Any, IO, TextIO, TypeVar
+
+T = TypeVar('T')
+
+class AbstractBothContextManager[T](AbstractContextManager[T], AbstractAsyncContextManager[T], metaclass=abc.ABCMeta):
+    """ Abstract base class for context managers that support both synchronous and asynchronous usage. """
+
+class LogToFile(AbstractBothContextManager['LogToFile']):
+    ''' Context manager to log to a file.
+
+\tThis context manager allows you to temporarily log output to a file while still printing normally.
+\tThe file will receive log messages without ANSI color codes.
+
+\tArgs:
+\t\tpath (str): Path to the log file
+\t\tmode (str): Mode to open the file in (default: "w")
+\t\tencoding (str): Encoding to use for the file (default: "utf-8")
+\t\ttee_stdout (bool): Whether to redirect stdout to the file (default: True)
+\t\ttee_stderr (bool): Whether to redirect stderr to the file (default: True)
+\t\tignore_lineup (bool): Whether to ignore lines containing LINE_UP escape sequence in files (default: False)
+\t\trestore_on_exit (bool): Whether to restore original stdout/stderr on exit (default: False)
+\t\t\tThis ctx uses TeeMultiOutput which handles closed files gracefully, so restoring is not mandatory.
+
+\tExamples:
+\t\t.. code-block:: python
+
+\t\t\t> import stouputils as stp
+\t\t\t> with stp.LogToFile("output.log"):
+\t\t\t>     stp.info("This will be logged to output.log and printed normally")
+\t\t\t>     print("This will also be logged")
+
+\t\t\t> with stp.LogToFile("output.log") as log_ctx:
+\t\t\t>     stp.warning("This will be logged to output.log and printed normally")
+\t\t\t>     log_ctx.change_file("new_file.log")
+\t\t\t>     print("This will be logged to new_file.log")
+\t'''
+    path: str
+    mode: str
+    encoding: str
+    tee_stdout: bool
+    tee_stderr: bool
+    ignore_lineup: bool
+    restore_on_exit: bool
+    file: IO[Any]
+    original_stdout: TextIO
+    original_stderr: TextIO
+    def __init__(self, path: str, mode: str = 'w', encoding: str = 'utf-8', tee_stdout: bool = True, tee_stderr: bool = True, ignore_lineup: bool = True, restore_on_exit: bool = False) -> None: ...
+    def __enter__(self) -> LogToFile:
+        """ Enter context manager which opens the log file and redirects stdout/stderr """
+    def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any | None) -> None:
+        """ Exit context manager which closes the log file and restores stdout/stderr """
+    async def __aenter__(self) -> LogToFile:
+        """ Enter async context manager which opens the log file and redirects stdout/stderr """
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any | None) -> None:
+        """ Exit async context manager which closes the log file and restores stdout/stderr """
+    def change_file(self, new_path: str) -> None:
+        """ Change the log file to a new path.
+
+\t\tArgs:
+\t\t\tnew_path (str): New path to the log file
+\t\t"""
+    @staticmethod
+    def common(logs_folder: str, filepath: str, func: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+        ''' Common code used at the beginning of a program to launch main function
+
+\t\tArgs:
+\t\t\tlogs_folder (str): Folder to store logs in
+\t\t\tfilepath    (str): Path to the main function
+\t\t\tfunc        (Callable[..., Any]): Main function to launch
+\t\t\t*args       (tuple[Any, ...]): Arguments to pass to the main function
+\t\t\t**kwargs    (dict[str, Any]): Keyword arguments to pass to the main function
+\t\tReturns:
+\t\t\tAny: Return value of the main function
+
+\t\tExamples:
+\t\t\t>>> if __name__ == "__main__":
+\t\t\t...     LogToFile.common(f"{ROOT}/logs", __file__, main)
+\t\t'''
+
+class MeasureTime(AbstractBothContextManager['MeasureTime']):
+    ''' Context manager to measure execution time.
+
+\tThis context manager measures the execution time of the code block it wraps
+\tand prints the result using a specified print function.
+
+\tArgs:
+\t\tprint_func      (Callable): Function to use to print the execution time (e.g. debug, info, warning, error, etc.).
+\t\tmessage         (str):      Message to display with the execution time. Defaults to "Execution time".
+\t\tperf_counter    (bool):     Whether to use time.perf_counter_ns or time.time_ns. Defaults to True.
+
+\tExamples:
+\t\t.. code-block:: python
+
+\t\t\t> import time
+\t\t\t> import stouputils as stp
+\t\t\t> with stp.MeasureTime(stp.info, message="My operation"):
+\t\t\t...     time.sleep(0.5)
+\t\t\t> # [INFO HH:MM:SS] My operation: 500.123ms (500123456ns)
+
+\t\t\t> with stp.MeasureTime(): # Uses debug by default
+\t\t\t...     time.sleep(0.1)
+\t\t\t> # [DEBUG HH:MM:SS] Execution time: 100.456ms (100456789ns)
+\t'''
+    print_func: Callable[..., None]
+    message: str
+    perf_counter: bool
+    ns: Callable[[], int]
+    start_ns: int
+    def __init__(self, print_func: Callable[..., None] = ..., message: str = 'Execution time', perf_counter: bool = True) -> None: ...
+    def __enter__(self) -> MeasureTime:
+        """ Enter context manager, record start time """
+    def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any | None) -> None:
+        """ Exit context manager, calculate duration and print """
+    async def __aenter__(self) -> MeasureTime:
+        """ Enter async context manager, record start time """
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any | None) -> None:
+        """ Exit async context manager, calculate duration and print """
+
+class Muffle(AbstractBothContextManager['Muffle']):
+    ''' Context manager that temporarily silences output.
+\t(No thread-safety guaranteed)
+
+\tAlternative to stouputils.decorators.silent()
+
+\tExamples:
+\t\t>>> with Muffle():
+\t\t...     print("This will not be printed")
+\t'''
+    mute_stderr: bool
+    original_stdout: IO[Any]
+    original_stderr: IO[Any]
+    def __init__(self, mute_stderr: bool = False) -> None: ...
+    def __enter__(self) -> Muffle:
+        """ Enter context manager which redirects stdout and stderr to devnull """
+    def __exit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any | None) -> None:
+        """ Exit context manager which restores original stdout and stderr """
+    async def __aenter__(self) -> Muffle:
+        """ Enter async context manager which redirects stdout and stderr to devnull """
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any | None) -> None:
+        """ Exit async context manager which restores original stdout and stderr """
+
+class DoNothing(AbstractBothContextManager['DoNothing']):
+    ''' Context manager that does nothing.
+
+\tThis is a no-op context manager that can be used as a placeholder
+\tor for conditional context management.
+
+\tDifferent from contextlib.nullcontext because it handles args and kwargs,
+\talong with **async** context management.
+
+\tExamples:
+\t\t>>> with DoNothing():
+\t\t...     print("This will be printed normally")
+\t\tThis will be printed normally
+
+\t\t>>> # Conditional context management
+\t\t>>> some_condition = True
+\t\t>>> ctx = DoNothing() if some_condition else Muffle()
+\t\t>>> with ctx:
+\t\t...     print("May or may not be printed depending on condition")
+\t\tMay or may not be printed depending on condition
+\t'''
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """ No initialization needed, this is a no-op context manager """
+    def __enter__(self) -> DoNothing:
+        """ Enter context manager (does nothing) """
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """ Exit context manager (does nothing) """
+    async def __aenter__(self) -> DoNothing:
+        """ Enter async context manager (does nothing) """
+    async def __aexit__(self, *excinfo: Any) -> None:
+        """ Exit async context manager (does nothing) """
+NullContextManager = DoNothing
+
+class SetMPStartMethod(AbstractBothContextManager['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 """
+    async def __aenter__(self) -> SetMPStartMethod:
+        """ Enter async context manager which sets the start method """
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """ Exit async context manager which restores the original start method """

stouputils/stouputils/decorators.pyi

@@ -0,0 +1,242 @@
+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'''
+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'''