Add logging compatibility layer.

Author: felixfontein

changelogs/fragments/188-logging.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - "Add logging wrapper classes to simplify switch from twiggy to the standard logging framework
+     (https://github.com/ansible-community/antsibull-core/issues/39, https://github.com/ansible-community/antsibull-core/pull/188)."

src/antsibull_core/ansible_core.py

@@ -21,7 +21,7 @@
 from packaging.version import Version as PypiVer
 
 from . import app_context
-from .logging import log
+from .logging import get_module_logger
 from .subprocess_util import async_log_run
 from .utils.http import retry_get
 
@@ -30,7 +30,7 @@
     from _typeshed import StrPath
 
 
-mlog = log.fields(mod=__name__)
+mlog = get_module_logger(__name__)
 
 
 class UnknownVersion(Exception):

src/antsibull_core/config.py

@@ -14,13 +14,13 @@
 import perky  # type: ignore[import]
 import pydantic as p
 
-from .logging import log
+from .logging import get_module_logger
 from .schemas.context import AppContext, LibContext
 
 if t.TYPE_CHECKING:
     from _typeshed import StrPath
 
-mlog = log.fields(mod=__name__)
+mlog = get_module_logger(__name__)
 
 #: System config file location.
 SYSTEM_CONFIG_FILE = "/etc/antsibull.cfg"

src/antsibull_core/logging.py

@@ -18,7 +18,7 @@
 
 .. seealso::
 
-    * :mod:`antsibull.config` to see how the antsibull scripts allow user defined configuration
+    * :mod:`antsibull_core.config` to see how the antsibull scripts allow user defined configuration
         to configure logging after the bootstrap phase is over.  This is the primary way that end
         users interact with the logging subsystem.
 
@@ -31,32 +31,31 @@
 logging output is disabled.  That way the library doesn't spam the user's screen with log messages.
 
 An application that wishes to use the log must import the log and then call
-antsibull.logging.initialize_app_logging() before any other parts of antsibull are imported.  See
-the :ref:`Application Logging <application_logging>`_ section for more details.
+antsibull_core.logging.initialize_app_logging() before any other parts of antsibull are imported.
+See the :ref:`Application Logging <application_logging>`_ section for more details.
 
 
 Usage within a module
 =====================
 
 Our convention for logging with twiggy is that the name field reflects the Python package that the
-code is coming from (in this case, it is already set to ``antsibull`` by :mod:`antsibull.logging`.)
+code is coming from (in this case, it is already set to ``antsibull`` by
+:mod:`antsibull_core.logging`.)
 At the toplevel of a module, set up a logger which has a field named ``mod`` which reflects the
 module name:
 
 .. code-block:: python
 
     # The antsibull log object with the name already set to `antsibull`.
-    from logging import log
+    from logging import get_module_logger
 
-    # mlog stands for module log.  It's our convention to create a logger from the
-    # antsibull.logging.log object in each module.  `fields()` takes an arbitrary set of keyword
-    # args and returns a new log object.  Any log messages we emit with this log object (or its
-    # children) will include the fields which were set on it.  Our convention is to create mlog with
-    # `fields(mod=__name__)` so that messages we make from mlog (or its children) have a field named
-    # `mod` containing the name of the module.
+    # mlog stands for module log.  It's our convention to create a logger in each module.
+    # The logger will containt the module name as the `mod` field.
+    mlog = get_module_logger(__name__)
 
-    # `mod` and the value set to the module name.
-    mlog = log.fields(mod=__name__)
+    # `fields()` takes an arbitrary set of keyword args and returns a new log object.
+    # Any log messages we emit with this log object (or its children) will include the fields
+    # which were set on it.
 
     TRICKY_COMPUTED_GLOBAL = [a**a for a in range(1, 4)]
     # Use mlog for logging interesting things that happen at the module level.  Notice that we send
@@ -74,31 +73,31 @@
 
 .. code-block:: python
 
-def test_function(argument1):
-    # flog stands for function log.  It's our convention to use this name.
-    # Create a new one in any function you want to log from.
-    # By creating this from mlog, we copy any fields and other settings that we made to mlog.
-    # Our convention is to use the `func` field to hold the name of the function we're in.
-    flog = mlog.fields(func='test_function')
+    def test_function(argument1):
+        # flog stands for function log.  It's our convention to use this name.
+        # Create a new one in any function you want to log from.
+        # By creating this from mlog, we copy any fields and other settings that we made to mlog.
+        # Our convention is to use the `func` field to hold the name of the function we're in.
+        flog = mlog.fields(func='test_function')
 
-    # This would output:
-    # DEBUG:antsibull:func=test_function:mod=__main__|Enter
-    flog.debug('Enter')
-    value = do_something(argument1)
+        # This would output:
+        # DEBUG:antsibull:func=test_function:mod=__main__|Enter
+        flog.debug('Enter')
+        value = do_something(argument1)
 
-    flog.debug('Leave')
+        flog.debug('Leave')
 
-class FooBar:
-    def __init__(self):
-        flog = mlog.fields(func='FooBar.__init__')
-        flog.debug('Enter')
+    class FooBar:
+        def __init__(self):
+            flog = mlog.fields(func='FooBar.__init__')
+            flog.debug('Enter')
 
-        self._x = initialize_x()
-        self._y = initialize_y()
+            self._x = initialize_x()
+            self._y = initialize_y()
 
-        self.position = self.calculate_position(self._x, self._y)
+            self.position = self.calculate_position(self._x, self._y)
 
-        flog.debug('Leave')
+            flog.debug('Leave')
 
 
 .. _logging_levels::
@@ -144,29 +143,28 @@ def __init__(self):
 Logging Setup
 =============
 
-An antsibull command (:file:`antsibull/cli/*.py`) should import the ``log`` object from this module.
+An antsibull command (:file:`antsibull_*/cli/*.py`) should import this module.
 The log object will be configured for use within the library at first (silent) so the application
-should call :func:`antsibull.logging.initialize_app_logging` as soon as possible to tell the ``log``
-that it is okay to emit messages.
+should call :func:`antsibull_core.logging.initialize_app_logging` as soon as possible to tell the
+``log`` that it is okay to emit messages.
 
 The initial application logging configuration will log to stderr at the ``WARNING`` level or
 higher.  If the :envvar:`ANTIBULL_EARLY_DEBUG` environment variable is set, then  it will log at
 the ``DEBUG`` level rather than ``WARNING``.
 
 The antsibull command should read the configuration settings, which may include user specified
-logging configuration and application defaults, and then call :twiggy:func:`twiggy.dict_config` to
-finish the setup.  At that point, logging calls will emit logs according to the user's
-configuration.
+logging configuration and application defaults, and then call
+:func:`antsibull_core.logging.configure_logger` to finish the setup.
+At that point, logging calls will emit logs according to the user's configuration.
 
 Here's a sample of the relevant portions of an antsibull command to show how this will look:
 
 .. code-block:: python
 
     # File is antsibull/cli/antsibull_command.py
-    import twiggy
     # log is the toplevel log object.  It is important to import this and initialize it prior to
     # using the log so that sane defaults can be set.
-    from ..logging import log, initialize_app_logging
+    from antsibull_core.logging import configure_logger, get_module_logger, initialize_app_logging
 
     # By default, the log is configured to be useful within a library where the user may not have
     # been given the chance to configure the log.  Calling initialize_app_logging() reconfigures
@@ -178,7 +176,7 @@ def __init__(self):
     from ..config import load_config
 
 
-    mlog = log.fields(mod=__name__)
+    mlog = get_module_logger(__name__)
 
     def run(args):
         flog = mlog.fields(func='run')
@@ -189,12 +187,12 @@ def run(args):
         with app_context.app_and_lib_context(context_data) as (app_ctx, dummy_):
             # initialize_app_logging() sets the log's configuration with defaults appropriate for
             # an application but this call takes that one step further. It takes the logging
-            # configuration from the user's config file and hands it to twiggy.dict_config() so
+            # configuration from the user's config file and hands it to configure_logger() so
             # that the user has ultimate control over what log level, what format, and which file
             # the log is output as.  See the twiggy documentation for information on the format of
-            # the logging config.  See the antsibull.app_context documentation if you want more
+            # the logging config.  See the antsibull_core.app_context documentation if you want more
             # information on the context object.
-            twiggy.dict_config(app_ctx.logging_cfg.model_dump())
+            configure_logger(app_ctx)
 
 
 Once those steps are taken, any further logging calls will obey the user's configuration.
@@ -203,11 +201,16 @@ def run(args):
 
 from __future__ import annotations
 
+import abc
 import os
+import typing as t
 
 import twiggy  # type: ignore[import]
 import twiggy.levels  # type: ignore[import]
 
+if t.TYPE_CHECKING:
+    from .schemas.context import AppContext
+
 #: The standard log to use everywhere.  The name of the logger for all of the antsibull libraries
 #: is antsibull so that it is easy to setup an emitter for all of antsibull.  For those used to
 #: using the module's __name__ field as the name, the idiom we use here is to set the module name
@@ -229,7 +232,7 @@ def initialize_app_logging() -> None:
     """
     Change log settings to make sense for an application.
 
-    Merely importing the :mod:`antsibull.logging` module sets up the logger for use as part of
+    Merely importing the :mod:`antsibull_core.logging` module sets up the logger for use as part of
     a library.  Calling this function will initialize the logger for use in an application.
     """
     # We want to see logs from the antsibull library, so the very first thing we do is turn the log
@@ -243,4 +246,75 @@ def initialize_app_logging() -> None:
     twiggy.quick_setup(min_level=_level)
 
 
-__all__ = ("log", "initialize_app_logging")
+class Logger(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def debug(self, format_spec: str, *args, **kwargs) -> None:
+        pass
+
+    @abc.abstractmethod
+    def info(self, format_spec: str, *args, **kwargs) -> None:
+        pass
+
+    @abc.abstractmethod
+    def notice(self, format_spec: str, *args, **kwargs) -> None:
+        pass
+
+    @abc.abstractmethod
+    def warning(self, format_spec: str, *args, **kwargs) -> None:
+        pass
+
+    @abc.abstractmethod
+    def error(self, format_spec: str, *args, **kwargs) -> None:
+        pass
+
+    @abc.abstractmethod
+    def critical(self, format_spec: str, *args, **kwargs) -> None:
+        pass
+
+    @abc.abstractmethod
+    def trace(self) -> None:
+        pass
+
+    @abc.abstractmethod
+    def fields(self, **kwargs) -> Logger:
+        pass
+
+
+class TwiggyLogger(Logger):
+    def __init__(self, logger: twiggy.logger.Logger) -> None:
+        self.logger = logger
+
+    def debug(self, format_spec: str, *args, **kwargs) -> None:
+        self.logger.debug(format_spec, *args, **kwargs)
+
+    def info(self, format_spec: str, *args, **kwargs) -> None:
+        self.logger.info(format_spec, *args, **kwargs)
+
+    def notice(self, format_spec: str, *args, **kwargs) -> None:
+        self.logger.notice(format_spec, *args, **kwargs)
+
+    def warning(self, format_spec: str, *args, **kwargs) -> None:
+        self.logger.warning(format_spec, *args, **kwargs)
+
+    def error(self, format_spec: str, *args, **kwargs) -> None:
+        self.logger.error(format_spec, *args, **kwargs)
+
+    def critical(self, format_spec: str, *args, **kwargs) -> None:
+        self.logger.critical(format_spec, *args, **kwargs)
+
+    def trace(self) -> None:
+        self.logger.trace()
+
+    def fields(self, **kwargs) -> Logger:
+        return TwiggyLogger(self.logger.fields(**kwargs))
+
+
+def get_module_logger(module_name: str) -> Logger:
+    return TwiggyLogger(log.fields(mod=module_name))
+
+
+def configure_logger(app_ctx: AppContext) -> None:
+    twiggy.dict_config(app_ctx.logging_cfg.model_dump())
+
+
+__all__ = ("log", "initialize_app_logging", "get_module_logger", "Logger")

src/antsibull_core/subprocess_util.py

@@ -21,7 +21,7 @@
 
 from twiggy.logger import Logger as TwiggyLogger  # type: ignore[import]
 
-from antsibull_core.logging import log
+from antsibull_core.logging import Logger, get_module_logger
 
 if TYPE_CHECKING:
     from _typeshed import StrOrBytesPath
@@ -30,7 +30,7 @@
     _T = TypeVar("_T")
     _P = ParamSpec("_P")
 
-mlog = log.fields(mod=__name__)
+mlog = get_module_logger(__name__)
 
 CalledProcessError = subprocess.CalledProcessError
 
@@ -99,7 +99,7 @@ def _get_log_func_and_prefix(
         else:
             # fmt: off
             func = getattr(logger, loglevel)
-            if isinstance(logger, TwiggyLogger):
+            if isinstance(logger, (TwiggyLogger, Logger)):
                 def logfunc(string: str, /):
                     func("{0}", string)
             elif isinstance(logger, StdLogger):
@@ -114,7 +114,7 @@ def logfunc(string: str, /):
 
 async def async_log_run(
     args: Sequence[StrOrBytesPath],
-    logger: TwiggyLogger | StdLogger | None = None,
+    logger: TwiggyLogger | StdLogger | Logger | None = None,
     stdout_loglevel: str | OutputCallbackType | None = None,
     stderr_loglevel: str | OutputCallbackType | None = "debug",
     check: bool = True,
@@ -187,7 +187,7 @@ async def async_log_run(
 
 def log_run(
     args: Sequence[StrOrBytesPath],
-    logger: TwiggyLogger | StdLogger | None = None,
+    logger: TwiggyLogger | StdLogger | Logger | None = None,
     stdout_loglevel: str | OutputCallbackType | None = None,
     stderr_loglevel: str | OutputCallbackType | None = "debug",
     check: bool = True,

src/antsibull_core/utils/http.py

@@ -17,9 +17,9 @@
 import aiohttp
 
 from .. import app_context
-from ..logging import log
+from ..logging import get_module_logger
 
-mlog = log.fields(mod=__name__)
+mlog = get_module_logger(__name__)
 
 
 # Since Python 3.11 asyncio.TimeoutError is a deprecated alias of TimeoutError

src/antsibull_core/utils/io.py

@@ -14,12 +14,12 @@
 from antsibull_fileutils.io import write_file as _write_file
 
 from .. import app_context
-from ..logging import log
+from ..logging import get_module_logger
 
 if t.TYPE_CHECKING:
     from _typeshed import StrOrBytesPath
 
-mlog = log.fields(mod=__name__)
+mlog = get_module_logger(__name__)
 
 
 async def copy_file(