winiutils 2.3.12__py3-none-any.whl

winiutils/src/iterating/concurrent/multiprocessing.py

@@ -0,0 +1,186 @@
+"""Multiprocessing utilities for CPU-bound parallel execution.
+
+This module provides functions for parallel processing using Python's
+multiprocessing module. It includes utilities for handling timeouts,
+managing process pools, and organizing parallel execution of CPU-bound
+functions.
+
+Use multiprocessing for CPU-bound tasks that benefit from true parallelism
+by bypassing Python's Global Interpreter Lock (GIL).
+
+Example:
+    >>> from winiutils.src.iterating.concurrent.multiprocessing import (
+    ...     multiprocess_loop,
+    ... )
+    >>> def square(x):
+    ...     return x * x
+    >>> results = multiprocess_loop(
+    ...     process_function=square,
+    ...     process_args=[[1], [2], [3]],
+    ...     process_args_len=3,
+    ... )
+    >>> results
+    [1, 4, 9]
+"""
+
+import logging
+import multiprocessing
+from collections.abc import Callable, Iterable
+from functools import wraps
+from multiprocessing.pool import Pool
+from typing import Any
+
+from winiutils.src.iterating.concurrent.concurrent import concurrent_loop
+
+logger = logging.getLogger(__name__)
+
+
+def get_spwan_pool(*args: Any, **kwargs: Any) -> Pool:
+    """Create a multiprocessing pool with the spawn context.
+
+    Uses the 'spawn' start method which creates a fresh Python interpreter
+    process. This is safer than 'fork' as it avoids issues with inherited
+    file descriptors and locks.
+
+    Args:
+        *args: Positional arguments passed to ``Pool`` constructor.
+        **kwargs: Keyword arguments passed to ``Pool`` constructor.
+
+    Returns:
+        A multiprocessing Pool configured with the spawn context.
+
+    Example:
+        >>> pool = get_spwan_pool(processes=4)
+        >>> with pool:
+        ...     results = pool.map(square, [1, 2, 3])
+    """
+    return multiprocessing.get_context("spawn").Pool(*args, **kwargs)
+
+
+def cancel_on_timeout(seconds: float, message: str) -> Callable[..., Any]:
+    """Create a decorator that cancels function execution on timeout.
+
+    Creates a wrapper that executes the decorated function in a separate
+    process and terminates it if execution time exceeds the specified
+    timeout.
+
+    Args:
+        seconds: Maximum execution time in seconds before timeout.
+        message: Error message to include in the warning log when timeout
+            occurs.
+
+    Returns:
+        A decorator function that wraps the target function with timeout
+        functionality.
+
+    Raises:
+        multiprocessing.TimeoutError: When function execution exceeds the
+            timeout.
+
+    Warning:
+        Only works with functions that are pickle-able. This means it may
+        not work as a decorator on methods or closures. Instead, use it as
+        a wrapper function::
+
+            my_func = cancel_on_timeout(
+                seconds=2,
+                message="Test timeout",
+            )(my_func)
+
+    Example:
+        >>> def slow_function():
+        ...     import time
+        ...     time.sleep(10)
+        ...     return "done"
+        >>> timed_func = cancel_on_timeout(
+        ...     seconds=1,
+        ...     message="Function took too long",
+        ... )(slow_function)
+        >>> timed_func()  # Raises TimeoutError after 1 second
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(func)
+        def wrapper(*args: object, **kwargs: object) -> object:
+            spawn_pool = get_spwan_pool(processes=1)
+            with spawn_pool as pool:
+                async_result = pool.apply_async(func, args, kwargs)
+                try:
+                    return async_result.get(timeout=seconds)
+                except multiprocessing.TimeoutError:
+                    logger.warning(
+                        "%s -> Execution exceeded %s seconds: %s",
+                        func,
+                        seconds,
+                        message,
+                    )
+                    raise
+                finally:
+                    pool.terminate()  # Ensure the worker process is killed
+                    pool.join()  # Wait for cleanup
+
+        return wrapper
+
+    return decorator
+
+
+def multiprocess_loop(
+    process_function: Callable[..., Any],
+    process_args: Iterable[Iterable[Any]],
+    process_args_static: Iterable[Any] | None = None,
+    deepcopy_static_args: Iterable[Any] | None = None,
+    process_args_len: int = 1,
+) -> list[Any]:
+    """Execute a function in parallel using multiprocessing Pool.
+
+    Executes the given function with the provided arguments in parallel
+    using multiprocessing Pool, which is suitable for CPU-bound tasks.
+
+    Args:
+        process_function: The function to execute in parallel. Must be
+            pickle-able.
+        process_args: Iterable of argument lists for each parallel call.
+            Each inner iterable contains the arguments for one function
+            call. Example: ``[(1, 2), (3, 4), (5, 6)]``
+        process_args_static: Optional constant arguments to append to each
+            call. These are shared across all calls without copying.
+            Defaults to None.
+        deepcopy_static_args: Optional arguments that should be deep-copied
+            for each process. Use this for mutable objects that should not
+            be shared between processes. Defaults to None.
+        process_args_len: Length of ``process_args``. Used for progress bar
+            and worker pool sizing. Defaults to 1.
+
+    Returns:
+        List of results from the function executions, in the original
+        submission order.
+
+    Note:
+        - Use multiprocessing for CPU-bound tasks as it bypasses Python's
+          GIL by creating separate processes.
+        - Multiprocessing is not safe for mutable objects; use
+          ``deepcopy_static_args`` for mutable data.
+        - If ConnectionErrors occur during debugging, try reducing the
+          number of processes.
+        - All functions and arguments must be pickle-able.
+
+    Example:
+        >>> def add(a, b, c):
+        ...     return a + b + c
+        >>> results = multiprocess_loop(
+        ...     process_function=add,
+        ...     process_args=[[1, 2], [3, 4]],
+        ...     process_args_static=[10],
+        ...     process_args_len=2,
+        ... )
+        >>> results
+        [13, 17]
+    """
+    return concurrent_loop(
+        threading=False,
+        process_function=process_function,
+        process_args=process_args,
+        process_args_static=process_args_static,
+        deepcopy_static_args=deepcopy_static_args,
+        process_args_len=process_args_len,
+    )

winiutils/src/iterating/concurrent/multithreading.py

@@ -0,0 +1,132 @@
+"""Multithreading utilities for I/O-bound parallel execution.
+
+This module provides functions for parallel processing using thread pools.
+It includes utilities for handling thread pools, managing futures, and
+organizing parallel execution of I/O-bound tasks.
+
+Use multithreading for I/O-bound tasks such as network requests, file
+operations, or database queries where threads spend most of their time
+waiting for external resources.
+
+Example:
+    >>> from winiutils.src.iterating.concurrent.multithreading import (
+    ...     multithread_loop,
+    ... )
+    >>> def fetch_url(url):
+    ...     import requests
+    ...     return requests.get(url).status_code
+    >>> results = multithread_loop(
+    ...     process_function=fetch_url,
+    ...     process_args=[["https://example.com"], ["https://google.com"]],
+    ...     process_args_len=2,
+    ... )
+"""
+
+from collections.abc import Callable, Generator, Iterable
+from concurrent.futures import Future, ThreadPoolExecutor, as_completed
+from typing import Any
+
+from winiutils.src.iterating.concurrent.concurrent import concurrent_loop
+
+
+def get_future_results_as_completed(
+    futures: Iterable[Future[Any]],
+) -> Generator[Any, None, None]:
+    """Yield future results as they complete.
+
+    Yields results from futures in the order they complete, not in the
+    order they were submitted. This allows processing results as soon as
+    they're available.
+
+    Args:
+        futures: Iterable of Future objects to get results from.
+
+    Yields:
+        The result of each completed future.
+
+    Example:
+        >>> with ThreadPoolExecutor() as executor:
+        ...     futures = [executor.submit(square, i) for i in range(3)]
+        ...     for result in get_future_results_as_completed(futures):
+        ...         print(result)
+    """
+    for future in as_completed(futures):
+        yield future.result()
+
+
+def multithread_loop(
+    process_function: Callable[..., Any],
+    process_args: Iterable[Iterable[Any]],
+    process_args_static: Iterable[Any] | None = None,
+    process_args_len: int = 1,
+) -> list[Any]:
+    """Execute a function in parallel using ThreadPoolExecutor.
+
+    Executes the given function with the provided arguments in parallel
+    using ThreadPoolExecutor, which is suitable for I/O-bound tasks.
+
+    Args:
+        process_function: The function to execute in parallel.
+        process_args: Iterable of argument lists for each parallel call.
+            Each inner iterable contains the arguments for one function
+            call. Example: ``[["url1"], ["url2"], ["url3"]]``
+        process_args_static: Optional constant arguments to append to each
+            call. These are shared across all calls. Defaults to None.
+        process_args_len: Length of ``process_args``. Used for progress bar
+            and worker pool sizing. Defaults to 1.
+
+    Returns:
+        List of results from the function executions, in the original
+        submission order.
+
+    Note:
+        Use ThreadPoolExecutor for I/O-bound tasks (network requests, file
+        I/O, database queries). For CPU-bound tasks, use
+        ``multiprocess_loop()`` instead.
+
+    Example:
+        >>> def download(url, timeout):
+        ...     import requests
+        ...     return requests.get(url, timeout=timeout).text
+        >>> results = multithread_loop(
+        ...     process_function=download,
+        ...     process_args=[["https://example.com"], ["https://google.com"]],
+        ...     process_args_static=[30],  # 30 second timeout for all
+        ...     process_args_len=2,
+        ... )
+    """
+    return concurrent_loop(
+        threading=True,
+        process_function=process_function,
+        process_args=process_args,
+        process_args_static=process_args_static,
+        process_args_len=process_args_len,
+    )
+
+
+def imap_unordered(
+    executor: ThreadPoolExecutor,
+    func: Callable[..., Any],
+    iterable: Iterable[Any],
+) -> Generator[Any, None, None]:
+    """Apply a function to each item in an iterable in parallel.
+
+    Similar to ``multiprocessing.Pool.imap_unordered()``, this function
+    submits all items to the executor and yields results as they complete.
+
+    Args:
+        executor: ThreadPoolExecutor to use for parallel execution.
+        func: Function to apply to each item in the iterable.
+        iterable: Iterable of items to apply the function to.
+
+    Yields:
+        Results of applying the function to each item, in completion order
+        (not submission order).
+
+    Example:
+        >>> with ThreadPoolExecutor(max_workers=4) as executor:
+        ...     for result in imap_unordered(executor, square, [1, 2, 3]):
+        ...         print(result)
+    """
+    results = [executor.submit(func, item) for item in iterable]
+    yield from get_future_results_as_completed(results)

winiutils/src/iterating/iterate.py

@@ -0,0 +1,45 @@
+"""Iterating utilities for handling iterables.
+
+This module provides utility functions for working with iterables,
+including getting the length of an iterable with a default value.
+These utilities help with iterable operations and manipulations.
+"""
+
+from collections.abc import Iterable
+from typing import Any
+
+
+def get_len_with_default(iterable: Iterable[Any], default: int | None = None) -> int:
+    """Get the length of an iterable, falling back to a default value.
+
+    Attempts to get the length of an iterable using ``len()``. If the
+    iterable doesn't support ``len()`` (e.g., generators), returns the
+    provided default value instead.
+
+    Args:
+        iterable: The iterable to get the length of.
+        default: Default value to return if the iterable doesn't support
+            ``len()``. If None and the iterable doesn't support ``len()``,
+            a TypeError is raised.
+
+    Returns:
+        The length of the iterable, or the default value if the iterable
+        doesn't support ``len()``.
+
+    Raises:
+        TypeError: If the iterable doesn't support ``len()`` and no default
+            value is provided.
+
+    Example:
+        >>> get_len_with_default([1, 2, 3])
+        3
+        >>> get_len_with_default((x for x in range(10)), default=10)
+        10
+    """
+    try:
+        return len(iterable)  # type: ignore[arg-type]
+    except TypeError as e:
+        if default is None:
+            msg = "Can't get length of iterable and no default value provided"
+            raise TypeError(msg) from e
+        return default

winiutils/src/oop/__init__.py

@@ -0,0 +1,7 @@
+"""Object-oriented programming utilities package.
+
+This package provides utilities for OOP patterns and class behavior modification:
+
+Modules:
+    mixins: Metaclasses and mixins for automatic method logging and instrumentation.
+"""

winiutils/src/oop/mixins/__init__.py

@@ -0,0 +1,8 @@
+"""Mixins and metaclasses package.
+
+This package provides metaclasses and mixins for class behavior modification:
+
+Modules:
+    meta: Metaclasses for automatic method logging and instrumentation.
+    mixin: Mixin classes that provide composable behavior extensions.
+"""

winiutils/src/oop/mixins/meta.py

@@ -0,0 +1,217 @@
+"""Metaclass utilities for class behavior modification and enforcement.
+
+This module provides metaclasses that can be used to modify class behavior
+at creation time. These metaclasses can be used individually or combined
+to create classes with enhanced capabilities and stricter implementation
+requirements.
+
+Example:
+    >>> from winiutils.src.oop.mixins.meta import ABCLoggingMeta
+    >>> class MyClass(metaclass=ABCLoggingMeta):
+    ...     def my_method(self, x):
+    ...         return x * 2
+    >>> obj = MyClass()
+    >>> obj.my_method(5)  # Logs: "MyClass - Calling my_method with ..."
+    10
+"""
+
+import logging
+import time
+from abc import ABCMeta
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+from pyrig.src.modules.function import is_func
+
+from winiutils.src.data.structures.text.string import value_to_truncated_string
+
+logger = logging.getLogger(__name__)
+
+
+class ABCLoggingMeta(ABCMeta):
+    """Metaclass that automatically adds logging to class methods.
+
+    Wraps non-magic methods with a logging decorator that tracks method
+    calls, arguments, execution time, and return values. Includes rate
+    limiting to prevent log flooding.
+
+    This metaclass extends ``ABCMeta``, so classes using it can also define
+    abstract methods.
+
+    Attributes:
+        Inherits all attributes from ``ABCMeta``.
+
+    Example:
+        >>> class Calculator(metaclass=ABCLoggingMeta):
+        ...     def add(self, a, b):
+        ...         return a + b
+        >>> calc = Calculator()
+        >>> calc.add(2, 3)  # Logs method call and result
+        5
+
+    Note:
+        - Magic methods (``__init__``, ``__str__``, etc.) are not logged.
+        - Properties are not logged.
+        - Logging is rate-limited to once per second per method to prevent
+          log flooding.
+    """
+
+    def __new__(
+        mcs: type["ABCLoggingMeta"],
+        name: str,
+        bases: tuple[type, ...],
+        dct: dict[str, Any],
+    ) -> "ABCLoggingMeta":
+        """Create a new class with logging-wrapped methods.
+
+        Intercepts class creation to wrap all non-magic methods with logging
+        functionality. Handles regular methods, class methods, and static
+        methods.
+
+        Args:
+            mcs: The metaclass instance.
+            name: The name of the class being created.
+            bases: The base classes of the class being created.
+            dct: The attribute dictionary of the class being created.
+
+        Returns:
+            A new class with logging functionality added to its methods.
+        """
+        # Wrap all callables of the class with a logging wrapper
+
+        for attr_name, attr_value in dct.items():
+            if mcs.is_loggable_method(attr_value):
+                if isinstance(attr_value, classmethod):
+                    wrapped_method = mcs.wrap_with_logging(
+                        func=attr_value.__func__, class_name=name, call_times={}
+                    )
+                    dct[attr_name] = classmethod(wrapped_method)
+                elif isinstance(attr_value, staticmethod):
+                    wrapped_method = mcs.wrap_with_logging(
+                        func=attr_value.__func__, class_name=name, call_times={}
+                    )
+                    dct[attr_name] = staticmethod(wrapped_method)
+                else:
+                    dct[attr_name] = mcs.wrap_with_logging(
+                        func=attr_value, class_name=name, call_times={}
+                    )
+
+        return super().__new__(mcs, name, bases, dct)
+
+    @staticmethod
+    def is_loggable_method(method: Callable[..., Any]) -> bool:
+        """Determine if a method should have logging applied.
+
+        Checks whether a method is a valid candidate for logging. Methods
+        are logged if they are callable, have a name, and are not magic
+        methods (those starting with ``__``).
+
+        Args:
+            method: The method to check.
+
+        Returns:
+            True if the method should be wrapped with logging, False
+            otherwise.
+
+        Note:
+            Properties are not logged as they are not callable in the
+            traditional sense and cause issues with the wrapping mechanism.
+        """
+        return (
+            is_func(method)  # must be a method-like attribute
+            and not getattr(method, "__name__", "__").startswith(
+                "__"
+            )  # must not be a magic method
+        )
+
+    @staticmethod
+    def wrap_with_logging(
+        func: Callable[..., Any],
+        class_name: str,
+        call_times: dict[str, float],
+    ) -> Callable[..., Any]:
+        """Wrap a function with logging functionality.
+
+        Creates a wrapper that logs method calls, arguments, execution time,
+        and return values. Includes rate limiting to prevent excessive
+        logging (once per second per method).
+
+        Args:
+            func: The function to wrap with logging.
+            class_name: The name of the class containing the function. Used
+                in log messages.
+            call_times: Dictionary to track when methods were last called.
+                Used for rate limiting. This dictionary is mutated by the
+                wrapper.
+
+        Returns:
+            A wrapped function with logging capabilities.
+
+        Note:
+            Arguments and return values are truncated to 20 characters in
+            log messages to prevent excessively long log lines.
+        """
+        time_time = time.time  # Cache the time.time function for performance
+
+        @wraps(func)
+        def wrapper(*args: object, **kwargs: object) -> object:
+            # call_times as a dictionary to store the call times of the function
+            # we only log if the time since the last call is greater than the threshold
+            # this is to avoid spamming the logs
+
+            func_name = func.__name__  # ty:ignore[unresolved-attribute]
+
+            threshold = 1
+
+            last_call_time = call_times.get(func_name, 0)
+
+            current_time = time_time()
+
+            do_logging = (current_time - last_call_time) > threshold
+
+            max_log_length = 20
+
+            if do_logging:
+                args_str = value_to_truncated_string(
+                    value=args, max_length=max_log_length
+                )
+
+                kwargs_str = value_to_truncated_string(
+                    value=kwargs, max_length=max_log_length
+                )
+
+                logger.info(
+                    "%s - Calling %s with %s and %s",
+                    class_name,
+                    func_name,
+                    args_str,
+                    kwargs_str,
+                )
+
+            # Execute the function and return the result
+
+            result = func(*args, **kwargs)
+
+            if do_logging:
+                duration = time_time() - current_time
+
+                result_str = value_to_truncated_string(
+                    value=result, max_length=max_log_length
+                )
+
+                logger.info(
+                    "%s - %s finished with %s seconds -> returning %s",
+                    class_name,
+                    func_name,
+                    duration,
+                    result_str,
+                )
+
+            # save the call time for the next call
+
+            call_times[func_name] = current_time
+
+            return result
+
+        return wrapper

winiutils/src/oop/mixins/mixin.py

@@ -0,0 +1,58 @@
+"""Mixin utilities for class composition and behavior extension.
+
+This module provides mixin classes that facilitate class composition through
+the mixin pattern. It includes utilities for automatic method logging with
+performance tracking.
+
+These utilities help create robust class hierarchies with built-in logging
+capabilities without requiring explicit decorator usage.
+
+Example:
+    >>> from winiutils.src.oop.mixins.mixin import ABCLoggingMixin
+    >>> class MyService(ABCLoggingMixin):
+    ...     def process(self, data):
+    ...         return data.upper()
+    >>> service = MyService()
+    >>> service.process("hello")  # Logs method call automatically
+    'HELLO'
+"""
+
+import logging
+
+from winiutils.src.oop.mixins.meta import ABCLoggingMeta
+
+logger = logging.getLogger(__name__)
+
+
+class ABCLoggingMixin(metaclass=ABCLoggingMeta):
+    """Mixin class that provides automatic method logging.
+
+    This mixin can be used as a base class for any class that needs
+    automatic method logging with performance tracking. All non-magic
+    methods will be automatically wrapped with logging functionality.
+
+    The logging includes:
+        - Method name and class name
+        - Arguments passed to the method (truncated)
+        - Execution time
+        - Return value (truncated)
+
+    Inheriting from this class is equivalent to using ``ABCLoggingMeta``
+    as the metaclass, but provides a cleaner inheritance syntax.
+
+    Example:
+        >>> class DataProcessor(ABCLoggingMixin):
+        ...     def transform(self, data):
+        ...         return [x * 2 for x in data]
+        >>> processor = DataProcessor()
+        >>> processor.transform([1, 2, 3])
+        [2, 4, 6]
+        # Logs: "DataProcessor - Calling transform with ..."
+        # Logs: "DataProcessor - transform finished with 0.001 seconds -> ..."
+
+    Note:
+        - Magic methods (``__init__``, ``__str__``, etc.) are not logged.
+        - Logging is rate-limited to once per second per method.
+        - This class can be combined with abstract methods since it uses
+          ``ABCLoggingMeta`` which extends ``ABCMeta``.
+    """

winiutils/src/security/__init__.py

@@ -0,0 +1,8 @@
+"""Security utilities package.
+
+This package provides utilities for encryption and secure storage:
+
+Modules:
+    cryptography: AES-GCM encryption and decryption utilities.
+    keyring: OS keyring integration for secure key storage and retrieval.
+"""