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

stouputils/stouputils/parallel.pyi

@@ -1,216 +0,0 @@
-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 | None):  Queue to store the result or exception (None if detached).
-\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

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

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