python-utils 2.5.6__py3-none-any.whl → 4.0.0__py3-none-any.whl

python_utils/logger.py

@@ -1,18 +1,165 @@
+"""
+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')
+"""
+
+from __future__ import annotations
+
+import abc
+import collections.abc
 import logging
-import functools
+import types
+import typing
+
+if typing.TYPE_CHECKING:
+    import typing_extensions
+
+from . import decorators
 
 __all__ = ['Logged']
 
+#: Accepted values for the logging ``exc_info`` parameter: a bool, an
+#: ``(type, value, traceback)`` triple, a bare exception instance, or ``None``.
+# From the logging typeshed, converted to be compatible with Python 3.8
+# https://github.com/python/typeshed/blob/main/stdlib/logging/__init__.pyi
+_ExcInfoType: typing.TypeAlias = (
+    bool
+    | tuple[
+        type[BaseException],
+        BaseException,
+        types.TracebackType | None,
+    ]
+    | tuple[None, None, None]
+    | BaseException
+    | None
+)
+#: Parameter specification capturing a wrapped logger method's arguments.
+_P = typing.ParamSpec('_P')
+#: Covariant return-type variable for wrapped logger methods.
+_T = typing.TypeVar('_T', covariant=True)
+
+
+class LoggerProtocol(typing.Protocol):
+    """Structural type for any ``logging.Logger``-compatible logger.
+
+    Objects that provide these methods (such as a ``logging.Logger`` or a
+    ``loguru`` logger) can be used as the ``logger`` attribute of a
+    ``LoggerBase`` subclass. Only the shape matters; no inheritance required.
+    """
+
+    def debug(
+        self,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at ``DEBUG`` level."""
+
+    def info(
+        self,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at ``INFO`` level."""
 
-class Logged(object):
-    '''Class which automatically adds a named logger to your class when
-    interiting
+    def warning(
+        self,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at ``WARNING`` level."""
+
+    def error(
+        self,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at ``ERROR`` level."""
+
+    def critical(
+        self,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at ``CRITICAL`` level."""
+
+    def exception(
+        self,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at ``ERROR`` level, including exception information."""
+
+    def log(
+        self,
+        level: int,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at the integer ``level``."""
+
+
+class LoggerBase(abc.ABC):
+    """Class which automatically adds logging utilities to your class when
+    inheriting. Expects `logger` to be a logging.Logger or compatible instance.
 
     Adds easy access to debug, info, warning, error, exception and log methods
 
-    >>> class MyClass(Logged):
+    >>> class MyClass(LoggerBase):
+    ...     logger = logging.getLogger(__name__)
+    ...
     ...     def __init__(self):
     ...         Logged.__init__(self)
+
     >>> my_class = MyClass()
     >>> my_class.debug('debug')
     >>> my_class.info('info')
@@ -20,43 +167,219 @@ class Logged(object):
     >>> my_class.error('error')
     >>> my_class.exception('exception')
     >>> my_class.log(0, 'log')
-    '''
-    def __new__(cls, *args, **kwargs):
-        cls.logger = logging.getLogger(
-            cls.__get_name(cls.__module__, cls.__name__))
-        return super(Logged, cls).__new__(cls)
+    """
+
+    # 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: typing.Any
+    # logger: LoggerProtocol
 
     @classmethod
-    def __get_name(cls, *name_parts):
+    def __get_name(  # pyright: ignore[reportUnusedFunction]
+        cls, *name_parts: str
+    ) -> str:
+        """Join the non-empty, stripped ``name_parts`` into a dotted name."""
         return '.'.join(n.strip() for n in name_parts if n.strip())
 
+    @decorators.wraps_classmethod(logging.Logger.debug)
+    @classmethod
+    def debug(
+        cls,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at ``DEBUG`` level on the class logger."""
+        return cls.logger.debug(  # type: ignore[no-any-return]
+            msg,
+            *args,
+            exc_info=exc_info,
+            stack_info=stack_info,
+            stacklevel=stacklevel,
+            extra=extra,
+        )
+
+    @decorators.wraps_classmethod(logging.Logger.info)
     @classmethod
-    @functools.wraps(logging.debug)
-    def debug(cls, msg, *args, **kwargs):
-        cls.logger.debug(msg, *args, **kwargs)
+    def info(
+        cls,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at ``INFO`` level on the class logger."""
+        return cls.logger.info(  # type: ignore[no-any-return]
+            msg,
+            *args,
+            exc_info=exc_info,
+            stack_info=stack_info,
+            stacklevel=stacklevel,
+            extra=extra,
+        )
 
+    @decorators.wraps_classmethod(logging.Logger.warning)
     @classmethod
-    @functools.wraps(logging.info)
-    def info(cls, msg, *args, **kwargs):
-        cls.logger.info(msg, *args, **kwargs)
+    def warning(
+        cls,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at ``WARNING`` level on the class logger."""
+        return cls.logger.warning(  # type: ignore[no-any-return]
+            msg,
+            *args,
+            exc_info=exc_info,
+            stack_info=stack_info,
+            stacklevel=stacklevel,
+            extra=extra,
+        )
 
+    @decorators.wraps_classmethod(logging.Logger.error)
     @classmethod
-    @functools.wraps(logging.warning)
-    def warning(cls, msg, *args, **kwargs):
-        cls.logger.warning(msg, *args, **kwargs)
+    def error(
+        cls,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at ``ERROR`` level on the class logger."""
+        return cls.logger.error(  # type: ignore[no-any-return]
+            msg,
+            *args,
+            exc_info=exc_info,
+            stack_info=stack_info,
+            stacklevel=stacklevel,
+            extra=extra,
+        )
 
+    @decorators.wraps_classmethod(logging.Logger.critical)
     @classmethod
-    @functools.wraps(logging.error)
-    def error(cls, msg, *args, **kwargs):
-        cls.logger.error(msg, *args, **kwargs)
+    def critical(
+        cls,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at ``CRITICAL`` level on the class logger."""
+        return cls.logger.critical(  # type: ignore[no-any-return]
+            msg,
+            *args,
+            exc_info=exc_info,
+            stack_info=stack_info,
+            stacklevel=stacklevel,
+            extra=extra,
+        )
 
+    @decorators.wraps_classmethod(logging.Logger.exception)
     @classmethod
-    @functools.wraps(logging.exception)
-    def exception(cls, msg, *args, **kwargs):
-        cls.logger.exception(msg, *args, **kwargs)
+    def exception(
+        cls,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at ``ERROR`` level with exception info attached."""
+        return cls.logger.exception(  # type: ignore[no-any-return]
+            msg,
+            *args,
+            exc_info=exc_info,
+            stack_info=stack_info,
+            stacklevel=stacklevel,
+            extra=extra,
+        )
 
+    @decorators.wraps_classmethod(logging.Logger.log)
     @classmethod
-    @functools.wraps(logging.log)
-    def log(cls, lvl, msg, *args, **kwargs):
-        cls.logger.log(lvl, msg, *args, **kwargs)
+    def log(
+        cls,
+        level: int,
+        msg: object,
+        *args: object,
+        exc_info: _ExcInfoType = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        extra: collections.abc.Mapping[str, object] | None = None,
+    ) -> None:
+        """Log ``msg`` at the integer ``level`` on the class logger."""
+        return cls.logger.log(  # type: ignore[no-any-return]
+            level,
+            msg,
+            *args,
+            exc_info=exc_info,
+            stack_info=stack_info,
+            stacklevel=stacklevel,
+            extra=extra,
+        )
+
 
+class Logged(LoggerBase):
+    """Class which automatically adds a named logger to your class when
+    inheriting.
+
+    Adds easy access to debug, info, warning, error, exception and log methods
+
+    >>> 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')
+
+    >>> my_class._Logged__get_name('spam')
+    'spam'
+    """
+
+    logger: logging.Logger  # pragma: no cover
+
+    @classmethod
+    def __get_name(cls, *name_parts: str) -> str:
+        """Build the dotted logger name via ``LoggerBase``'s joiner."""
+        return typing.cast(
+            str,
+            LoggerBase._LoggerBase__get_name(*name_parts),  # type: ignore[attr-defined]  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType, reportAttributeAccessIssue]
+        )
+
+    def __new__(
+        cls, *args: typing.Any, **kwargs: typing.Any
+    ) -> typing_extensions.Self:
+        """
+        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.
+
+        Returns:
+            An instance of the class.
+        """
+        cls.logger = logging.getLogger(
+            cls.__get_name(cls.__module__, cls.__name__)
+        )
+        return super().__new__(cls)

python_utils/loguru.py

@@ -0,0 +1,53 @@
+"""
+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
+
+from . import logger as logger_module
+
+__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) -> 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`.
+        """
+        # `logger` is already declared at class scope; assign without
+        # re-annotating to avoid an obscured-declaration error.
+        cls.logger = loguru.logger.opt(depth=1)
+        return super().__new__(cls)