python-utils 3.8.2__py2.py3-none-any.whl → 3.9.1__py2.py3-none-any.whl

python_utils/generators.py

@@ -1,10 +1,22 @@
+"""
+This module provides generator utilities for batching items from
+iterables and async iterables.
+
+Functions:
+    abatcher(generator, batch_size=None, interval=None):
+        Asyncio generator wrapper that returns items with a given batch
+        size or interval (whichever is reached first).
+
+    batcher(iterable, batch_size=10):
+        Generator wrapper that returns items with a given batch size.
+"""
+
 import asyncio
 import time
 
 import python_utils
 from python_utils import types
 
-
 _T = types.TypeVar('_T')
 
 
@@ -16,10 +28,21 @@ async def abatcher(
     batch_size: types.Optional[int] = None,
     interval: types.Optional[types.delta_type] = None,
 ) -> types.AsyncGenerator[types.List[_T], None]:
-    '''
+    """
     Asyncio generator wrapper that returns items with a given batch size or
     interval (whichever is reached first).
-    '''
+
+    Args:
+        generator: The async generator or iterator to batch.
+        batch_size (types.Optional[int], optional): The number of items per
+            batch. Defaults to None.
+        interval (types.Optional[types.delta_type], optional): The time
+            interval to wait before yielding a batch. Defaults to None.
+
+    Yields:
+        types.AsyncGenerator[types.List[_T], None]: A generator that yields
+        batches of items.
+    """
     batch: types.List[_T] = []
 
     assert batch_size or interval, 'Must specify either batch_size or interval'
@@ -80,9 +103,18 @@ def batcher(
     iterable: types.Iterable[_T],
     batch_size: int = 10,
 ) -> types.Generator[types.List[_T], None, None]:
-    '''
-    Generator wrapper that returns items with a given batch size
-    '''
+    """
+    Generator wrapper that returns items with a given batch size.
+
+    Args:
+        iterable (types.Iterable[_T]): The iterable to batch.
+        batch_size (int, optional): The number of items per batch. Defaults
+            to 10.
+
+    Yields:
+        types.Generator[types.List[_T], None, None]: A generator that yields
+        batches of items.
+    """
     batch: types.List[_T] = []
     for item in iterable:
         batch.append(item)

python_utils/import_.py

@@ -1,33 +1,51 @@
+"""
+This module provides utilities for importing modules and handling exceptions.
+
+Classes:
+    DummyError(Exception):
+        A custom exception class used as a default for exception handling.
+
+Functions:
+    import_global(name, modules=None, exceptions=DummyError, locals_=None,
+        globals_=None, level=-1):
+        Imports the requested items into the global scope, with support for
+        relative imports and custom exception handling.
+"""
+
 from . import types
 
 
-class DummyException(Exception):
-    pass
+class DummyError(Exception):
+    """A custom exception class used as a default for exception handling."""
+
+
+# Legacy alias for DummyError
+DummyException = DummyError
 
 
-def import_global(
+def import_global(  # noqa: C901
     name: str,
     modules: types.Optional[types.List[str]] = None,
-    exceptions: types.ExceptionsType = DummyException,
+    exceptions: types.ExceptionsType = DummyError,
     locals_: types.OptionalScope = None,
     globals_: types.OptionalScope = None,
     level: int = -1,
-) -> types.Any:
-    '''Import the requested items into the global scope
+) -> types.Any:  # sourcery skip: hoist-if-from-if
+    """Import the requested items into the global scope.
 
     WARNING! this method _will_ overwrite your global scope
-    If you have a variable named "path" and you call import_global('sys')
-    it will be overwritten with sys.path
+    If you have a variable named `path` and you call `import_global('sys')`
+    it will be overwritten with `sys.path`
 
     Args:
         name (str): the name of the module to import, e.g. sys
         modules (str): the modules to import, use None for everything
-        exception (Exception): the exception to catch, e.g. ImportError
-        `locals_`: the `locals()` method (in case you need a different scope)
-        `globals_`: the `globals()` method (in case you need a different scope)
+        exceptions (Exception): the exception to catch, e.g. ImportError
+        locals_: the `locals()` method (in case you need a different scope)
+        globals_: the `globals()` method (in case you need a different scope)
         level (int): the level to import from, this can be used for
         relative imports
-    '''
+    """
     frame = None
     name_parts: types.List[str] = name.split('.')
     modules_set: types.Set[str] = set()
@@ -65,8 +83,10 @@ def import_global(
             try:
                 for attr in name_parts[1:]:
                     module = getattr(module, attr)
-            except AttributeError:
-                raise ImportError('No module named ' + '.'.join(name_parts))
+            except AttributeError as e:
+                raise ImportError(
+                    'No module named ' + '.'.join(name_parts)
+                ) from e
 
             # If no list of modules is given, autodetect from either __all__
             # or a dir() of the module

python_utils/logger.py

@@ -1,3 +1,30 @@
+"""
+This module provides a base class `LoggerBase` and a derived class `Logged`
+for adding logging capabilities to classes. The `LoggerBase` class expects
+a `logger` attribute to be a `logging.Logger` or compatible instance and
+provides methods for logging at various levels. The `Logged` class
+automatically adds a named logger to the class.
+
+Classes:
+    LoggerBase:
+        A base class that adds logging utilities to a class.
+    Logged:
+        A derived class that automatically adds a named logger to a class.
+
+Example:
+    >>> class MyClass(Logged):
+    ...     def __init__(self):
+    ...         Logged.__init__(self)
+
+    >>> my_class = MyClass()
+    >>> my_class.debug('debug')
+    >>> my_class.info('info')
+    >>> my_class.warning('warning')
+    >>> my_class.error('error')
+    >>> my_class.exception('exception')
+    >>> my_class.log(0, 'log')
+"""
+
 import abc
 import logging
 
@@ -24,8 +51,81 @@ _P = types.ParamSpec('_P')
 _T = types.TypeVar('_T', covariant=True)
 
 
+class LoggerProtocol(types.Protocol):
+    def debug(
+        self,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: types.Union[types.Mapping[str, object], None] = None,
+    ) -> None: ...
+
+    def info(
+        self,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: types.Union[types.Mapping[str, object], None] = None,
+    ) -> None: ...
+
+    def warning(
+        self,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: types.Union[types.Mapping[str, object], None] = None,
+    ) -> None: ...
+
+    def error(
+        self,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: types.Union[types.Mapping[str, object], None] = None,
+    ) -> None: ...
+
+    def critical(
+        self,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: types.Union[types.Mapping[str, object], None] = None,
+    ) -> None: ...
+
+    def exception(
+        self,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: types.Union[types.Mapping[str, object], None] = None,
+    ) -> None: ...
+
+    def log(
+        self,
+        level: int,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: types.Union[types.Mapping[str, object], None] = None,
+    ) -> None: ...
+
+
 class LoggerBase(abc.ABC):
-    '''Class which automatically adds logging utilities to your class when
+    """Class which automatically adds logging utilities to your class when
     interiting. Expects `logger` to be a logging.Logger or compatible instance.
 
     Adds easy access to debug, info, warning, error, exception and log methods
@@ -43,11 +143,13 @@ class LoggerBase(abc.ABC):
     >>> my_class.error('error')
     >>> my_class.exception('exception')
     >>> my_class.log(0, 'log')
-    '''
+    """
 
-    # Being a tad lazy here and not creating a Protocol.
-    # The actual classes define the correct type anyway
+    # I've tried using a protocol to properly type the logger but it gave all
+    # sorts of issues with mypy so we're using the lazy solution for now. The
+    # actual classes define the correct type anyway
     logger: types.Any
+    # logger: LoggerProtocol
 
     @classmethod
     def __get_name(  # pyright: ignore[reportUnusedFunction]
@@ -66,7 +168,7 @@ class LoggerBase(abc.ABC):
         stacklevel: int = 1,
         extra: types.Union[types.Mapping[str, object], None] = None,
     ) -> None:
-        return cls.logger.debug(
+        return cls.logger.debug(  # type: ignore[no-any-return]
             msg,
             *args,
             exc_info=exc_info,
@@ -86,7 +188,7 @@ class LoggerBase(abc.ABC):
         stacklevel: int = 1,
         extra: types.Union[types.Mapping[str, object], None] = None,
     ) -> None:
-        return cls.logger.info(
+        return cls.logger.info(  # type: ignore[no-any-return]
             msg,
             *args,
             exc_info=exc_info,
@@ -106,7 +208,7 @@ class LoggerBase(abc.ABC):
         stacklevel: int = 1,
         extra: types.Union[types.Mapping[str, object], None] = None,
     ) -> None:
-        return cls.logger.warning(
+        return cls.logger.warning(  # type: ignore[no-any-return]
             msg,
             *args,
             exc_info=exc_info,
@@ -126,7 +228,7 @@ class LoggerBase(abc.ABC):
         stacklevel: int = 1,
         extra: types.Union[types.Mapping[str, object], None] = None,
     ) -> None:
-        return cls.logger.error(
+        return cls.logger.error(  # type: ignore[no-any-return]
             msg,
             *args,
             exc_info=exc_info,
@@ -146,7 +248,7 @@ class LoggerBase(abc.ABC):
         stacklevel: int = 1,
         extra: types.Union[types.Mapping[str, object], None] = None,
     ) -> None:
-        return cls.logger.critical(
+        return cls.logger.critical(  # type: ignore[no-any-return]
             msg,
             *args,
             exc_info=exc_info,
@@ -166,7 +268,7 @@ class LoggerBase(abc.ABC):
         stacklevel: int = 1,
         extra: types.Union[types.Mapping[str, object], None] = None,
     ) -> None:
-        return cls.logger.exception(
+        return cls.logger.exception(  # type: ignore[no-any-return]
             msg,
             *args,
             exc_info=exc_info,
@@ -187,7 +289,7 @@ class LoggerBase(abc.ABC):
         stacklevel: int = 1,
         extra: types.Union[types.Mapping[str, object], None] = None,
     ) -> None:
-        return cls.logger.log(
+        return cls.logger.log(  # type: ignore[no-any-return]
             level,
             msg,
             *args,
@@ -199,8 +301,8 @@ class LoggerBase(abc.ABC):
 
 
 class Logged(LoggerBase):
-    '''Class which automatically adds a named logger to your class when
-    interiting
+    """Class which automatically adds a named logger to your class when
+    interiting.
 
     Adds easy access to debug, info, warning, error, exception and log methods
 
@@ -218,16 +320,31 @@ class Logged(LoggerBase):
 
     >>> my_class._Logged__get_name('spam')
     'spam'
-    '''
+    """
 
     logger: logging.Logger  # pragma: no cover
 
     @classmethod
     def __get_name(cls, *name_parts: str) -> str:
-        return LoggerBase._LoggerBase__get_name(*name_parts)  # type: ignore
+        return types.cast(
+            str,
+            LoggerBase._LoggerBase__get_name(*name_parts),  # type: ignore[attr-defined]  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType, reportAttributeAccessIssue]
+        )
+
+    def __new__(cls, *args: types.Any, **kwargs: types.Any) -> 'Logged':
+        """
+        Create a new instance of the class and initialize the logger.
+
+        The logger is named using the module and class name.
+
+        Args:
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
 
-    def __new__(cls, *args: types.Any, **kwargs: types.Any):
+        Returns:
+            An instance of the class.
+        """
         cls.logger = logging.getLogger(
             cls.__get_name(cls.__module__, cls.__name__)
         )
-        return super(Logged, cls).__new__(cls)
+        return super().__new__(cls)

python_utils/loguru.py

@@ -1,4 +1,21 @@
+"""
+This module provides a `Logurud` class that integrates the `loguru` logger
+with the base logging functionality defined in `logger_module.LoggerBase`.
+
+Classes:
+    Logurud: A class that extends `LoggerBase` and uses `loguru` for logging.
+
+Usage example:
+    >>> from python_utils.loguru import Logurud
+    >>> class MyClass(Logurud):
+    ...     def __init__(self):
+    ...         Logurud.__init__(self)
+    >>> my_class = MyClass()
+    >>> my_class.logger.info('This is an info message')
+"""
+
 from __future__ import annotations
+
 import typing
 
 import loguru
@@ -9,8 +26,26 @@ __all__ = ['Logurud']
 
 
 class Logurud(logger_module.LoggerBase):
+    """
+    A class that extends `LoggerBase` and uses `loguru` for logging.
+
+    Attributes:
+        logger (loguru.Logger): The `loguru` logger instance.
+    """
+
     logger: loguru.Logger
 
-    def __new__(cls, *args: typing.Any, **kwargs: typing.Any):
+    def __new__(cls, *args: typing.Any, **kwargs: typing.Any) -> Logurud:
+        """
+        Creates a new instance of `Logurud` and initializes the `loguru`
+        logger.
+
+        Args:
+            *args (typing.Any): Variable length argument list.
+            **kwargs (typing.Any): Arbitrary keyword arguments.
+
+        Returns:
+            Logurud: A new instance of `Logurud`.
+        """
         cls.logger: loguru.Logger = loguru.logger.opt(depth=1)
         return super().__new__(cls)

python_utils/terminal.py

@@ -1,15 +1,33 @@
+"""
+This module provides functions to get the terminal size across different
+platforms.
+
+Functions:
+    get_terminal_size: Get the current size of the terminal.
+    _get_terminal_size_windows: Get terminal size on Windows.
+    _get_terminal_size_tput: Get terminal size using `tput`.
+    _get_terminal_size_linux: Get terminal size on Linux.
+
+Usage example:
+    >>> width, height = get_terminal_size()
+"""
+
+from __future__ import annotations
+
 import contextlib
 import os
 import typing
 
 from . import converters
 
-Dimensions = typing.Tuple[int, int]
+Dimensions = tuple[int, int]
 OptionalDimensions = typing.Optional[Dimensions]
+_StrDimensions = tuple[str, str]
+_OptionalStrDimensions = typing.Optional[_StrDimensions]
 
 
 def get_terminal_size() -> Dimensions:  # pragma: no cover
-    '''Get the current size of your terminal
+    """Get the current size of your terminal.
 
     Multiple returns are not always a good idea, but in this case it greatly
     simplifies the code so I believe it's justified. It's not the prettiest
@@ -17,16 +35,16 @@ def get_terminal_size() -> Dimensions:  # pragma: no cover
 
     Returns:
         width, height: Two integers containing width and height
-    '''
-    w: typing.Optional[int]
-    h: typing.Optional[int]
+    """
+    w: int | None
+    h: int | None
 
     with contextlib.suppress(Exception):
         # Default to 79 characters for IPython notebooks
-        from IPython import get_ipython  # type: ignore
+        from IPython import get_ipython  # type: ignore[attr-defined]
 
-        ipython = get_ipython()
-        from ipykernel import zmqshell  # type: ignore
+        ipython = get_ipython()  # type: ignore[no-untyped-call]
+        from ipykernel import zmqshell  # type: ignore[import-not-found]
 
         if isinstance(ipython, zmqshell.ZMQInteractiveShell):
             return 79, 24
@@ -46,7 +64,7 @@ def get_terminal_size() -> Dimensions:  # pragma: no cover
         if w and h:
             return w, h
     with contextlib.suppress(Exception):
-        import blessings  # type: ignore
+        import blessings  # type: ignore[import-untyped]
 
         terminal = blessings.Terminal()
         w = terminal.width
@@ -77,7 +95,10 @@ def get_terminal_size() -> Dimensions:  # pragma: no cover
 def _get_terminal_size_windows() -> OptionalDimensions:  # pragma: no cover
     res = None
     try:
-        from ctypes import windll, create_string_buffer  # type: ignore
+        from ctypes import (  # type: ignore[attr-defined]
+            create_string_buffer,
+            windll,
+        )
 
         # stdin handle is -10
         # stdout handle is -11
@@ -93,7 +114,7 @@ def _get_terminal_size_windows() -> OptionalDimensions:  # pragma: no cover
         import struct
 
         (_, _, _, _, _, left, top, right, bottom, _, _) = struct.unpack(
-            "hhhhHhhhhhh", csbi.raw
+            'hhhhHhhhhhh', csbi.raw
         )
         w = right - left
         h = bottom - top
@@ -123,31 +144,36 @@ def _get_terminal_size_tput() -> OptionalDimensions:  # pragma: no cover
         )
         output = proc.communicate(input=None)
         h = int(output[0])
-        return w, h
     except Exception:
         return None
+    else:
+        return w, h
 
 
 def _get_terminal_size_linux() -> OptionalDimensions:  # pragma: no cover
-    def ioctl_GWINSZ(fd):
+    def ioctl_gwinsz(fd: int) -> tuple[str, str] | None:
         try:
             import fcntl
-            import termios
             import struct
+            import termios
 
-            return struct.unpack(
-                'hh',
-                fcntl.ioctl(fd, termios.TIOCGWINSZ, '1234'),  # type: ignore
+            return typing.cast(
+                _OptionalStrDimensions,
+                struct.unpack(
+                    'hh',
+                    fcntl.ioctl(fd, termios.TIOCGWINSZ, '1234'),  # type: ignore[call-overload]
+                ),
             )
         except Exception:
             return None
 
-    size = ioctl_GWINSZ(0) or ioctl_GWINSZ(1) or ioctl_GWINSZ(2)
+    size: _OptionalStrDimensions
+    size = ioctl_gwinsz(0) or ioctl_gwinsz(1) or ioctl_gwinsz(2)
 
     if not size:
         with contextlib.suppress(Exception):
-            fd = os.open(os.ctermid(), os.O_RDONLY)  # type: ignore
-            size = ioctl_GWINSZ(fd)
+            fd = os.open(os.ctermid(), os.O_RDONLY)
+            size = ioctl_gwinsz(fd)
             os.close(fd)
     if not size:
         try: