stouputils 1.14.0__py3-none-any.whl

stouputils/stouputils/io.pyi

@@ -0,0 +1,213 @@
+from typing import Any, IO
+
+def get_root_path(relative_path: str, go_up: int = 0) -> str:
+    """ Get the absolute path of the directory.
+\tUsually used to get the root path of the project using the __file__ variable.
+
+\tArgs:
+\t\trelative_path   (str): The path to get the absolute directory path from
+\t\tgo_up           (int): Number of parent directories to go up (default: 0)
+\tReturns:
+\t\tstr: The absolute path of the directory
+
+\tExamples:
+
+\t\t.. code-block:: python
+
+\t\t\t> get_root_path(__file__)
+\t\t\t'C:/Users/Alexandre-PC/AppData/Local/Programs/Python/Python310/lib/site-packages/stouputils'
+
+\t\t\t> get_root_path(__file__, 3)
+\t\t\t'C:/Users/Alexandre-PC/AppData/Local/Programs/Python/Python310'
+\t"""
+def relative_path(file_path: str, relative_to: str = '') -> str:
+    ''' Get the relative path of a file relative to a given directory.
+
+\tArgs:
+\t\tfile_path     (str): The path to get the relative path from
+\t\trelative_to   (str): The path to get the relative path to (default: current working directory -> os.getcwd())
+\tReturns:
+\t\tstr: The relative path of the file
+\tExamples:
+
+\t\t>>> relative_path("D:/some/random/path/stouputils/io.py", "D:\\\\some")
+\t\t\'random/path/stouputils/io.py\'
+\t\t>>> relative_path("D:/some/random/path/stouputils/io.py", "D:\\\\some\\\\")
+\t\t\'random/path/stouputils/io.py\'
+\t'''
+def json_dump(data: Any, file: IO[Any] | str | None = None, max_level: int | None = 2, indent: str | int = '\t', suffix: str = '\n', ensure_ascii: bool = False) -> str:
+    ''' Writes the provided data to a JSON file with a specified indentation depth.
+\tFor instance, setting max_level to 2 will limit the indentation to 2 levels.
+
+\tArgs:
+\t\tdata\t\t(Any): \t\t\t\tThe data to dump (usually a dict or a list)
+\t\tfile\t\t(IO[Any] | str): \tThe file object or path to dump the data to
+\t\tmax_level\t(int | None):\t\tThe depth of indentation to stop at (-1 for infinite), None will default to 2
+\t\tindent\t\t(str | int):\t\tThe indentation character (default: \'\\t\')
+\t\tsuffix\t\t(str):\t\t\t\tThe suffix to add at the end of the string (default: \'\\n\')
+\t\tensure_ascii (bool):\t\t\tWhether to escape non-ASCII characters (default: False)
+\tReturns:
+\t\tstr: The content of the file in every case
+
+\t>>> json_dump({"a": [[1,2,3]], "b": 2}, max_level = 0)
+\t\'{"a": [[1,2,3]],"b": 2}\\n\'
+\t>>> json_dump({"a": [[1,2,3]], "b": 2}, max_level = 1)
+\t\'{\\n\\t"a": [[1,2,3]],\\n\\t"b": 2\\n}\\n\'
+\t>>> json_dump({"a": [[1,2,3]], "b": 2}, max_level = 2)
+\t\'{\\n\\t"a": [\\n\\t\\t[1,2,3]\\n\\t],\\n\\t"b": 2\\n}\\n\'
+\t>>> json_dump({"a": [[1,2,3]], "b": 2}, max_level = 3)
+\t\'{\\n\\t"a": [\\n\\t\\t[\\n\\t\\t\\t1,\\n\\t\\t\\t2,\\n\\t\\t\\t3\\n\\t\\t]\\n\\t],\\n\\t"b": 2\\n}\\n\'
+\t>>> json_dump({"éà": "üñ"}, ensure_ascii = True, max_level = 0)
+\t\'{"\\\\u00e9\\\\u00e0": "\\\\u00fc\\\\u00f1"}\\n\'
+\t>>> json_dump({"éà": "üñ"}, ensure_ascii = False, max_level = 0)
+\t\'{"éà": "üñ"}\\n\'
+\t'''
+def json_load(file_path: str) -> Any:
+    """ Load a JSON file from the given path
+
+\tArgs:
+\t\tfile_path (str): The path to the JSON file
+\tReturns:
+\t\tAny: The content of the JSON file
+\t"""
+def csv_dump(data: Any, file: IO[Any] | str | None = None, delimiter: str = ',', has_header: bool = True, index: bool = False, *args: Any, **kwargs: Any) -> str:
+    ''' Writes data to a CSV file with customizable options and returns the CSV content as a string.
+
+\tArgs:
+\t\tdata\t\t(list[list[Any]] | list[dict[str, Any]] | pd.DataFrame | pl.DataFrame):
+\t\t\t\t\t\tThe data to write, either a list of lists, list of dicts, pandas DataFrame, or Polars DataFrame
+\t\tfile\t\t(IO[Any] | str): The file object or path to dump the data to
+\t\tdelimiter\t(str): The delimiter to use (default: \',\')
+\t\thas_header\t(bool): Whether to include headers (default: True, applies to dict and DataFrame data)
+\t\tindex\t\t(bool): Whether to include the index (default: False, only applies to pandas DataFrame)
+\t\t*args\t\t(Any): Additional positional arguments to pass to the underlying CSV writer or DataFrame method
+\t\t**kwargs\t(Any): Additional keyword arguments to pass to the underlying CSV writer or DataFrame method
+\tReturns:
+\t\tstr: The CSV content as a string
+
+\tExamples:
+
+\t\t>>> csv_dump([["a", "b", "c"], [1, 2, 3], [4, 5, 6]])
+\t\t\'a,b,c\\r\\n1,2,3\\r\\n4,5,6\\r\\n\'
+
+\t\t>>> csv_dump([{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}])
+\t\t\'name,age\\r\\nAlice,30\\r\\nBob,25\\r\\n\'
+\t'''
+def csv_load(file_path: str, delimiter: str = ',', has_header: bool = True, as_dict: bool = False, as_dataframe: bool = False, use_polars: bool = False, *args: Any, **kwargs: Any) -> Any:
+    ''' Load a CSV file from the given path
+
+\tArgs:
+\t\tfile_path (str): The path to the CSV file
+\t\tdelimiter (str): The delimiter used in the CSV (default: \',\')
+\t\thas_header (bool): Whether the CSV has a header row (default: True)
+\t\tas_dict (bool): Whether to return data as list of dicts (default: False)
+\t\tas_dataframe (bool): Whether to return data as a DataFrame (default: False)
+\t\tuse_polars (bool): Whether to use Polars instead of pandas for DataFrame (default: False, requires polars)
+\t\t*args: Additional positional arguments to pass to the underlying CSV reader or DataFrame method
+\t\t**kwargs: Additional keyword arguments to pass to the underlying CSV reader or DataFrame method
+\tReturns:
+\t\tlist[list[str]] | list[dict[str, str]] | pd.DataFrame | pl.DataFrame: The content of the CSV file
+
+\tExamples:
+
+\t\t.. code-block:: python
+
+\t\t\t> Assuming "test.csv" contains: a,b,c\\n1,2,3\\n4,5,6
+\t\t\t> csv_load("test.csv")
+\t\t\t[[\'1\', \'2\', \'3\'], [\'4\', \'5\', \'6\']]
+
+\t\t\t> csv_load("test.csv", as_dict=True)
+\t\t\t[{\'a\': \'1\', \'b\': \'2\', \'c\': \'3\'}, {\'a\': \'4\', \'b\': \'5\', \'c\': \'6\'}]
+
+\t\t\t> csv_load("test.csv", as_dataframe=True)
+\t\t\t   a  b  c
+\t\t\t0  1  2  3
+\t\t\t1  4  5  6
+
+\t\t.. code-block:: console
+
+\t\t\t> csv_load("test.csv", as_dataframe=True, use_polars=True)
+\t\t\tshape: (2, 3)
+\t\t\t┌─────┬─────┬─────┐
+\t\t\t│ a   ┆ b   ┆ c   │
+\t\t\t│ --- ┆ --- ┆ --- │
+\t\t\t│ i64 ┆ i64 ┆ i64 │
+\t\t\t╞═════╪═════╪═════╡
+\t\t\t│ 1   ┆ 2   ┆ 3   │
+\t\t\t│ 4   ┆ 5   ┆ 6   │
+\t\t\t└─────┴─────┴─────┘
+\t'''
+def super_copy(src: str, dst: str, create_dir: bool = True, symlink: bool = False) -> str:
+    """ Copy a file (or a folder) from the source to the destination
+
+\tArgs:
+\t\tsrc         (str):  The source path
+\t\tdst         (str):  The destination path
+\t\tcreate_dir  (bool): Whether to create the directory if it doesn't exist (default: True)
+\t\tsymlink     (bool): Whether to create a symlink instead of copying (Linux only, default: True)
+\tReturns:
+\t\tstr: The destination path
+\t"""
+def super_open(file_path: str, mode: str, encoding: str = 'utf-8') -> IO[Any]:
+    ''' Open a file with the given mode, creating the directory if it doesn\'t exist (only if writing)
+
+\tArgs:
+\t\tfile_path\t(str): The path to the file
+\t\tmode\t\t(str): The mode to open the file with, ex: "w", "r", "a", "wb", "rb", "ab"
+\t\tencoding\t(str): The encoding to use when opening the file (default: "utf-8")
+\tReturns:
+\t\topen: The file object, ready to be used
+\t'''
+def read_file(file_path: str, encoding: str = 'utf-8') -> str:
+    ''' Read the content of a file and return it as a string
+
+\tArgs:
+\t\tfile_path (str): The path to the file
+\t\tencoding  (str): The encoding to use when opening the file (default: "utf-8")
+\tReturns:
+\t\tstr: The content of the file
+\t'''
+def replace_tilde(path: str) -> str:
+    ''' Replace the "~" by the user\'s home directory
+
+\tArgs:
+\t\tpath (str): The path to replace the "~" by the user\'s home directory
+\tReturns:
+\t\tstr: The path with the "~" replaced by the user\'s home directory
+\tExamples:
+
+\t\t.. code-block:: python
+
+\t\t\t> replace_tilde("~/Documents/test.txt")
+\t\t\t\'/home/user/Documents/test.txt\'
+\t'''
+def clean_path(file_path: str, trailing_slash: bool = True) -> str:
+    ''' Clean the path by replacing backslashes with forward slashes and simplifying the path
+
+\tArgs:
+\t\tfile_path (str): The path to clean
+\t\ttrailing_slash (bool): Whether to keep the trailing slash, ex: "test/" -> "test/"
+\tReturns:
+\t\tstr: The cleaned path
+\tExamples:
+\t\t>>> clean_path("C:\\\\Users\\\\Stoupy\\\\Documents\\\\test.txt")
+\t\t\'C:/Users/Stoupy/Documents/test.txt\'
+
+\t\t>>> clean_path("Some Folder////")
+\t\t\'Some Folder/\'
+
+\t\t>>> clean_path("test/uwu/1/../../")
+\t\t\'test/\'
+
+\t\t>>> clean_path("some/./folder/../")
+\t\t\'some/\'
+
+\t\t>>> clean_path("folder1/folder2/../../folder3")
+\t\t\'folder3\'
+
+\t\t>>> clean_path("./test/./folder/")
+\t\t\'test/folder/\'
+
+\t\t>>> clean_path("C:/folder1\\\\folder2")
+\t\t\'C:/folder1/folder2\'
+\t'''

stouputils/stouputils/parallel.pyi

@@ -0,0 +1,216 @@
+from .ctx import SetMPStartMethod as SetMPStartMethod
+from .print import BAR_FORMAT as BAR_FORMAT, MAGENTA as MAGENTA
+from collections.abc import Callable, Iterable
+from typing import Any, TypeVar
+
+def doctest_square(x: int) -> int: ...
+def doctest_slow(x: int) -> int: ...
+
+CPU_COUNT: int
+T = TypeVar('T')
+R = TypeVar('R')
+
+def multiprocessing[T, R](func: Callable[..., R] | list[Callable[..., R]], args: Iterable[T], use_starmap: bool = False, chunksize: int = 1, desc: str = '', max_workers: int | float = ..., delay_first_calls: float = 0, color: str = ..., bar_format: str = ..., ascii: bool = False, smooth_tqdm: bool = True, **tqdm_kwargs: Any) -> list[R]:
+    ''' Method to execute a function in parallel using multiprocessing
+
+\t- For CPU-bound operations where the GIL (Global Interpreter Lock) is a bottleneck.
+\t- When the task can be divided into smaller, independent sub-tasks that can be executed concurrently.
+\t- For computationally intensive tasks like scientific simulations, data analysis, or machine learning workloads.
+
+\tArgs:
+\t\tfunc\t\t\t\t(Callable | list[Callable]):\tFunction to execute, or list of functions (one per argument)
+\t\targs\t\t\t\t(Iterable):\t\t\tIterable of arguments to pass to the function(s)
+\t\tuse_starmap\t\t\t(bool):\t\t\t\tWhether to use starmap or not (Defaults to False):
+\t\t\tTrue means the function will be called like func(\\*args[i]) instead of func(args[i])
+\t\tchunksize\t\t\t(int):\t\t\t\tNumber of arguments to process at a time
+\t\t\t(Defaults to 1 for proper progress bar display)
+\t\tdesc\t\t\t\t(str):\t\t\t\tDescription displayed in the progress bar
+\t\t\t(if not provided no progress bar will be displayed)
+\t\tmax_workers\t\t\t(int | float):\t\tNumber of workers to use (Defaults to CPU_COUNT), -1 means CPU_COUNT.
+\t\t\tIf float between 0 and 1, it\'s treated as a percentage of CPU_COUNT.
+\t\t\tIf negative float between -1 and 0, it\'s treated as a percentage of len(args).
+\t\tdelay_first_calls\t(float):\t\t\tApply i*delay_first_calls seconds delay to the first "max_workers" calls.
+\t\t\tFor instance, the first process will be delayed by 0 seconds, the second by 1 second, etc.
+\t\t\t(Defaults to 0): This can be useful to avoid functions being called in the same second.
+\t\tcolor\t\t\t\t(str):\t\t\t\tColor of the progress bar (Defaults to MAGENTA)
+\t\tbar_format\t\t\t(str):\t\t\t\tFormat of the progress bar (Defaults to BAR_FORMAT)
+\t\tascii\t\t\t\t(bool):\t\t\t\tWhether to use ASCII or Unicode characters for the progress bar
+\t\tsmooth_tqdm\t\t\t(bool):\t\t\t\tWhether to enable smooth progress bar updates by setting miniters and mininterval (Defaults to True)
+\t\t**tqdm_kwargs\t\t(Any):\t\t\t\tAdditional keyword arguments to pass to tqdm
+
+\tReturns:
+\t\tlist[object]:\tResults of the function execution
+
+\tExamples:
+\t\t.. code-block:: python
+
+\t\t\t> multiprocessing(doctest_square, args=[1, 2, 3])
+\t\t\t[1, 4, 9]
+
+\t\t\t> multiprocessing(int.__mul__, [(1,2), (3,4), (5,6)], use_starmap=True)
+\t\t\t[2, 12, 30]
+
+\t\t\t> # Using a list of functions (one per argument)
+\t\t\t> multiprocessing([doctest_square, doctest_square, doctest_square], [1, 2, 3])
+\t\t\t[1, 4, 9]
+
+\t\t\t> # Will process in parallel with progress bar
+\t\t\t> multiprocessing(doctest_slow, range(10), desc="Processing")
+\t\t\t[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+\t\t\t> # Will process in parallel with progress bar and delay the first threads
+\t\t\t> multiprocessing(
+\t\t\t.     doctest_slow,
+\t\t\t.     range(10),
+\t\t\t.     desc="Processing with delay",
+\t\t\t.     max_workers=2,
+\t\t\t.     delay_first_calls=0.6
+\t\t\t. )
+\t\t\t[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+\t'''
+def multithreading[T, R](func: Callable[..., R] | list[Callable[..., R]], args: Iterable[T], use_starmap: bool = False, desc: str = '', max_workers: int | float = ..., delay_first_calls: float = 0, color: str = ..., bar_format: str = ..., ascii: bool = False, smooth_tqdm: bool = True, **tqdm_kwargs: Any) -> list[R]:
+    ''' Method to execute a function in parallel using multithreading, you should use it:
+
+\t- For I/O-bound operations where the GIL is not a bottleneck, such as network requests or disk operations.
+\t- When the task involves waiting for external resources, such as network responses or user input.
+\t- For operations that involve a lot of waiting, such as GUI event handling or handling user input.
+
+\tArgs:
+\t\tfunc\t\t\t\t(Callable | list[Callable]):\tFunction to execute, or list of functions (one per argument)
+\t\targs\t\t\t\t(Iterable):\t\t\tIterable of arguments to pass to the function(s)
+\t\tuse_starmap\t\t\t(bool):\t\t\t\tWhether to use starmap or not (Defaults to False):
+\t\t\tTrue means the function will be called like func(\\*args[i]) instead of func(args[i])
+\t\tdesc\t\t\t\t(str):\t\t\t\tDescription displayed in the progress bar
+\t\t\t(if not provided no progress bar will be displayed)
+\t\tmax_workers\t\t\t(int | float):\t\tNumber of workers to use (Defaults to CPU_COUNT), -1 means CPU_COUNT.
+\t\t\tIf float between 0 and 1, it\'s treated as a percentage of CPU_COUNT.
+\t\t\tIf negative float between -1 and 0, it\'s treated as a percentage of len(args).
+\t\tdelay_first_calls\t(float):\t\t\tApply i*delay_first_calls seconds delay to the first "max_workers" calls.
+\t\t\tFor instance with value to 1, the first thread will be delayed by 0 seconds, the second by 1 second, etc.
+\t\t\t(Defaults to 0): This can be useful to avoid functions being called in the same second.
+\t\tcolor\t\t\t\t(str):\t\t\t\tColor of the progress bar (Defaults to MAGENTA)
+\t\tbar_format\t\t\t(str):\t\t\t\tFormat of the progress bar (Defaults to BAR_FORMAT)
+\t\tascii\t\t\t\t(bool):\t\t\t\tWhether to use ASCII or Unicode characters for the progress bar
+\t\tsmooth_tqdm\t\t\t(bool):\t\t\t\tWhether to enable smooth progress bar updates by setting miniters and mininterval (Defaults to True)
+\t\t**tqdm_kwargs\t\t(Any):\t\t\t\tAdditional keyword arguments to pass to tqdm
+
+\tReturns:
+\t\tlist[object]:\tResults of the function execution
+
+\tExamples:
+\t\t.. code-block:: python
+
+\t\t\t> multithreading(doctest_square, args=[1, 2, 3])
+\t\t\t[1, 4, 9]
+
+\t\t\t> multithreading(int.__mul__, [(1,2), (3,4), (5,6)], use_starmap=True)
+\t\t\t[2, 12, 30]
+
+\t\t\t> # Using a list of functions (one per argument)
+\t\t\t> multithreading([doctest_square, doctest_square, doctest_square], [1, 2, 3])
+\t\t\t[1, 4, 9]
+
+\t\t\t> # Will process in parallel with progress bar
+\t\t\t> multithreading(doctest_slow, range(10), desc="Threading")
+\t\t\t[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+\t\t\t> # Will process in parallel with progress bar and delay the first threads
+\t\t\t> multithreading(
+\t\t\t.     doctest_slow,
+\t\t\t.     range(10),
+\t\t\t.     desc="Threading with delay",
+\t\t\t.     max_workers=2,
+\t\t\t.     delay_first_calls=0.6
+\t\t\t. )
+\t\t\t[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+\t'''
+def run_in_subprocess[R](func: Callable[..., R], *args: Any, timeout: float | None = None, no_join: bool = False, **kwargs: Any) -> R:
+    ''' Execute a function in a subprocess with positional and keyword arguments.
+
+\tThis is useful when you need to run a function in isolation to avoid memory leaks,
+\tresource conflicts, or to ensure a clean execution environment. The subprocess will
+\tbe created, run the function with the provided arguments, and return the result.
+
+\tArgs:
+\t\tfunc         (Callable):     The function to execute in a subprocess.
+\t\t\t(SHOULD BE A TOP-LEVEL FUNCTION TO BE PICKLABLE)
+\t\t*args        (Any):          Positional arguments to pass to the function.
+\t\ttimeout      (float | None): Maximum time in seconds to wait for the subprocess.
+\t\t\tIf None, wait indefinitely. If the subprocess exceeds this time, it will be terminated.
+\t\tno_join      (bool):         If True, do not wait for the subprocess to finish (fire-and-forget).
+\t\t**kwargs     (Any):          Keyword arguments to pass to the function.
+
+\tReturns:
+\t\tR: The return value of the function.
+
+\tRaises:
+\t\tRuntimeError: If the subprocess exits with a non-zero exit code or times out.
+\t\tTimeoutError: If the subprocess exceeds the specified timeout.
+
+\tExamples:
+\t\t.. code-block:: python
+
+\t\t\t> # Simple function execution
+\t\t\t> run_in_subprocess(doctest_square, 5)
+\t\t\t25
+
+\t\t\t> # Function with multiple arguments
+\t\t\t> def add(a: int, b: int) -> int:
+\t\t\t.     return a + b
+\t\t\t> run_in_subprocess(add, 10, 20)
+\t\t\t30
+
+\t\t\t> # Function with keyword arguments
+\t\t\t> def greet(name: str, greeting: str = "Hello") -> str:
+\t\t\t.     return f"{greeting}, {name}!"
+\t\t\t> run_in_subprocess(greet, "World", greeting="Hi")
+\t\t\t\'Hi, World!\'
+
+\t\t\t> # With timeout to prevent hanging
+\t\t\t> run_in_subprocess(some_gpu_func, data, timeout=300.0)
+\t'''
+def _subprocess_wrapper[R](result_queue: Any, func: Callable[..., R], args: tuple[Any, ...], kwargs: dict[str, Any]) -> None:
+    """ Wrapper function to execute the target function and store the result in the queue.
+
+\tMust be at module level to be pickable on Windows (spawn context).
+
+\tArgs:
+\t\tresult_queue (multiprocessing.Queue):  Queue to store the result or exception.
+\t\tfunc         (Callable):               The target function to execute.
+\t\targs         (tuple):                  Positional arguments for the function.
+\t\tkwargs       (dict):                   Keyword arguments for the function.
+\t"""
+def _starmap[T, R](args: tuple[Callable[[T], R], list[T]]) -> R:
+    """ Private function to use starmap using args[0](\\*args[1])
+
+\tArgs:
+\t\targs (tuple): Tuple containing the function and the arguments list to pass to the function
+\tReturns:
+\t\tobject: Result of the function execution
+\t"""
+def _delayed_call[T, R](args: tuple[Callable[[T], R], float, T]) -> R:
+    """ Private function to apply delay before calling the target function
+
+\tArgs:
+\t\targs (tuple): Tuple containing the function, delay in seconds, and the argument to pass to the function
+\tReturns:
+\t\tobject: Result of the function execution
+\t"""
+def _handle_parameters[T, R](func: Callable[[T], R] | list[Callable[[T], R]], args: list[T], use_starmap: bool, delay_first_calls: float, max_workers: int, desc: str, color: str) -> tuple[str, Callable[[T], R], list[T]]:
+    ''' Private function to handle the parameters for multiprocessing or multithreading functions
+
+\tArgs:
+\t\tfunc\t\t\t\t(Callable | list[Callable]):\tFunction to execute, or list of functions (one per argument)
+\t\targs\t\t\t\t(list):\t\t\t\tList of arguments to pass to the function(s)
+\t\tuse_starmap\t\t\t(bool):\t\t\t\tWhether to use starmap or not (Defaults to False):
+\t\t\tTrue means the function will be called like func(\\*args[i]) instead of func(args[i])
+\t\tdelay_first_calls\t(int):\t\t\t\tApply i*delay_first_calls seconds delay to the first "max_workers" calls.
+\t\t\tFor instance, the first process will be delayed by 0 seconds, the second by 1 second, etc. (Defaults to 0):
+\t\t\tThis can be useful to avoid functions being called in the same second.
+\t\tmax_workers\t\t\t(int):\t\t\t\tNumber of workers to use (Defaults to CPU_COUNT)
+\t\tdesc\t\t\t\t(str):\t\t\t\tDescription of the function execution displayed in the progress bar
+\t\tcolor\t\t\t\t(str):\t\t\t\tColor of the progress bar
+
+\tReturns:
+\t\ttuple[str, Callable[[T], R], list[T]]:\tTuple containing the description, function, and arguments
+\t'''

stouputils/stouputils/print.pyi

@@ -0,0 +1,136 @@
+from collections.abc import Callable as Callable, Iterable, Iterator
+from typing import Any, IO, TextIO, TypeVar
+
+RESET: str
+RED: str
+GREEN: str
+YELLOW: str
+BLUE: str
+MAGENTA: str
+CYAN: str
+LINE_UP: str
+BAR_FORMAT: str
+T = TypeVar('T')
+previous_args_kwards: tuple[Any, Any]
+nb_values: int
+import_time: float
+
+def colored_for_loop[T](iterable: Iterable[T], desc: str = 'Processing', color: str = ..., bar_format: str = ..., ascii: bool = False, smooth_tqdm: bool = True, **kwargs: Any) -> Iterator[T]:
+    ''' Function to iterate over a list with a colored TQDM progress bar like the other functions in this module.
+
+\tArgs:
+\t\titerable\t(Iterable):\t\t\tList to iterate over
+\t\tdesc\t\t(str):\t\t\t\tDescription of the function execution displayed in the progress bar
+\t\tcolor\t\t(str):\t\t\t\tColor of the progress bar (Defaults to MAGENTA)
+\t\tbar_format\t(str):\t\t\t\tFormat of the progress bar (Defaults to BAR_FORMAT)
+\t\tascii\t\t(bool):\t\t\t\tWhether to use ASCII or Unicode characters for the progress bar (Defaults to False)
+\t\tsmooth_tqdm\t(bool):\t\t\t\tWhether to enable smooth progress bar updates by setting miniters=1 and mininterval=0.0 (Defaults to True)
+\t\t**kwargs:\t\t\t\t\t\tAdditional arguments to pass to the TQDM progress bar
+
+\tYields:
+\t\tT: Each item of the iterable
+
+\tExamples:
+\t\t>>> for i in colored_for_loop(range(10), desc="Time sleeping loop"):
+\t\t...     time.sleep(0.01)
+\t\t>>> # Time sleeping loop: 100%|██████████████████| 10/10 [ 95.72it/s, 00:00<00:00]
+\t'''
+def info(*values: Any, color: str = ..., text: str = 'INFO ', prefix: str = '', file: TextIO | list[TextIO] | None = None, **print_kwargs: Any) -> None:
+    ''' Print an information message looking like "[INFO HH:MM:SS] message" in green by default.
+
+\tArgs:
+\t\tvalues\t\t\t(Any):\t\t\t\t\tValues to print (like the print function)
+\t\tcolor\t\t\t(str):\t\t\t\t\tColor of the message (default: GREEN)
+\t\ttext\t\t\t(str):\t\t\t\t\tText of the message (default: "INFO ")
+\t\tprefix\t\t\t(str):\t\t\t\t\tPrefix to add to the values
+\t\tfile\t\t\t(TextIO|list[TextIO]):\tFile(s) to write the message to (default: sys.stdout)
+\t\tprint_kwargs\t(dict):\t\t\t\t\tKeyword arguments to pass to the print function
+\t'''
+def debug(*values: Any, **print_kwargs: Any) -> None:
+    ''' Print a debug message looking like "[DEBUG HH:MM:SS] message" in cyan by default. '''
+def alt_debug(*values: Any, **print_kwargs: Any) -> None:
+    ''' Print a debug message looking like "[DEBUG HH:MM:SS] message" in blue by default. '''
+def suggestion(*values: Any, **print_kwargs: Any) -> None:
+    ''' Print a suggestion message looking like "[SUGGESTION HH:MM:SS] message" in cyan by default. '''
+def progress(*values: Any, **print_kwargs: Any) -> None:
+    ''' Print a progress message looking like "[PROGRESS HH:MM:SS] message" in magenta by default. '''
+def warning(*values: Any, **print_kwargs: Any) -> None:
+    ''' Print a warning message looking like "[WARNING HH:MM:SS] message" in yellow by default and in sys.stderr. '''
+def error(*values: Any, exit: bool = False, **print_kwargs: Any) -> None:
+    """ Print an error message (in sys.stderr and in red by default)
+\tand optionally ask the user to continue or stop the program.
+
+\tArgs:
+\t\tvalues\t\t\t(Any):\t\tValues to print (like the print function)
+\t\texit\t\t\t(bool):\t\tWhether to ask the user to continue or stop the program,
+\t\t\tfalse to ignore the error automatically and continue
+\t\tprint_kwargs\t(dict):\t\tKeyword arguments to pass to the print function
+\t"""
+def whatisit(*values: Any, print_function: Callable[..., None] = ..., max_length: int = 250, color: str = ..., **print_kwargs: Any) -> None:
+    ''' Print the type of each value and the value itself, with its id and length/shape.
+
+\tThe output format is: "type, <id id_number>:\t(length/shape) value"
+
+\tArgs:
+\t\tvalues\t\t\t(Any):\t\tValues to print
+\t\tprint_function\t(Callable):\tFunction to use to print the values (default: debug())
+\t\tmax_length\t\t(int):\t\tMaximum length of the value string to print (default: 250)
+\t\tcolor\t\t\t(str):\t\tColor of the message (default: CYAN)
+\t\tprint_kwargs\t(dict):\t\tKeyword arguments to pass to the print function
+\t'''
+def breakpoint(*values: Any, print_function: Callable[..., None] = ..., **print_kwargs: Any) -> None:
+    """ Breakpoint function, pause the program and print the values.
+
+\tArgs:
+\t\tvalues\t\t\t(Any):\t\tValues to print
+\t\tprint_function\t(Callable):\tFunction to use to print the values (default: warning())
+\t\tprint_kwargs\t(dict):\t\tKeyword arguments to pass to the print function
+\t"""
+
+class TeeMultiOutput:
+    ''' File-like object that duplicates output to multiple file-like objects.
+
+\tArgs:
+\t\t*files         (IO[Any]):  One or more file-like objects that have write and flush methods
+\t\tstrip_colors   (bool):     Strip ANSI color codes from output sent to non-stdout/stderr files
+\t\tascii_only     (bool):     Replace non-ASCII characters with their ASCII equivalents for non-stdout/stderr files
+\t\tignore_lineup  (bool):     Ignore lines containing LINE_UP escape sequence in non-terminal outputs
+
+\tExamples:
+\t\t>>> f = open("logfile.txt", "w")
+\t\t>>> sys.stdout = TeeMultiOutput(sys.stdout, f)
+\t\t>>> print("Hello World")  # Output goes to both console and file
+\t\tHello World
+\t\t>>> f.close()\t# TeeMultiOutput will handle any future writes to closed files gracefully
+\t'''
+    files: tuple[IO[Any], ...]
+    strip_colors: bool
+    ascii_only: bool
+    ignore_lineup: bool
+    def __init__(self, *files: IO[Any], strip_colors: bool = True, ascii_only: bool = True, ignore_lineup: bool = True) -> None: ...
+    @property
+    def encoding(self) -> str:
+        ''' Get the encoding of the first file, or "utf-8" as fallback.
+
+\t\tReturns:
+\t\t\tstr: The encoding, ex: "utf-8", "ascii", "latin1", etc.
+\t\t'''
+    def write(self, obj: str) -> int:
+        """ Write the object to all files while stripping colors if needed.
+
+\t\tArgs:
+\t\t\tobj (str): String to write
+\t\tReturns:
+\t\t\tint: Number of characters written to the first file
+\t\t"""
+    def flush(self) -> None:
+        """ Flush all files. """
+    def fileno(self) -> int:
+        """ Return the file descriptor of the first file. """
+
+def remove_colors(text: str) -> str:
+    """ Remove the colors from a text """
+def is_same_print(*args: Any, **kwargs: Any) -> bool:
+    """ Checks if the current print call is the same as the previous one. """
+def current_time() -> str:
+    ''' Get the current time as "HH:MM:SS" if less than 24 hours since import, else "YYYY-MM-DD HH:MM:SS" '''

stouputils/stouputils/version_pkg.pyi

@@ -0,0 +1,15 @@
+from .print import CYAN as CYAN, GREEN as GREEN, RESET as RESET, YELLOW as YELLOW
+
+def show_version(main_package: str = 'stouputils', primary_color: str = ..., secondary_color: str = ..., max_depth: int = 2) -> None:
+    ''' Print the version of the main package and its dependencies.
+
+\tUsed by the "stouputils --version" command.
+
+\tArgs:
+\t\tmain_package\t(str):\tName of the main package to show version for
+\t\tprimary_color\t(str):\tColor to use for the primary package name
+\t\tsecondary_color\t(str):\tColor to use for the secondary package names
+\t\tmax_depth\t\t(int):\tMaximum depth for dependency tree (<= 2 for flat, >=3 for tree)
+\t'''
+def show_version_cli() -> None:
+    ''' Handle the "stouputils --version" CLI command '''