lsst-utils 25.2023.600__py3-none-any.whl → 29.2025.4800__py3-none-any.whl

lsst/utils/logging.py

@@ -14,26 +14,39 @@ from __future__ import annotations
 __all__ = (
     "TRACE",
     "VERBOSE",
-    "getLogger",
-    "getTraceLogger",
     "LsstLogAdapter",
+    "LsstLoggers",
     "PeriodicLogger",
+    "getLogger",
+    "getTraceLogger",
     "trace_set_at",
 )
 
 import logging
+import sys
 import time
+from collections.abc import Generator
 from contextlib import contextmanager
 from logging import LoggerAdapter
-from typing import Any, Generator, List, Optional, Union
-
-from deprecated.sphinx import deprecated
+from typing import TYPE_CHECKING, Any, TypeAlias, TypeGuard
 
 try:
     import lsst.log.utils as logUtils
 except ImportError:
     logUtils = None
 
+try:
+    from structlog import get_context as get_structlog_context
+except ImportError:
+    get_structlog_context = None  # type: ignore[assignment]
+
+
+if TYPE_CHECKING:
+    try:
+        from structlog.typing import BindableLogger
+    except ImportError:
+        BindableLogger: TypeAlias = Any  # type: ignore[no-redef]
+
 # log level for trace (verbose debug).
 TRACE = 5
 logging.addLevelName(TRACE, "TRACE")
@@ -43,6 +56,56 @@ VERBOSE = (logging.INFO + logging.DEBUG) // 2
 logging.addLevelName(VERBOSE, "VERBOSE")
 
 
+def _is_structlog_logger(
+    logger: logging.Logger | LsstLogAdapter | BindableLogger,
+) -> TypeGuard[BindableLogger]:
+    """Check if the given logger is a structlog logger."""
+    if get_structlog_context is None:
+        return False  # type: ignore[unreachable]
+
+    try:
+        # Returns a dict for structlog loggers; raises for stdlib logger
+        # objects.
+        get_structlog_context(logger)  # type: ignore[arg-type]
+        return True
+    except Exception:
+        # In practice this is usually ValueError or AttributeError.
+        return False
+
+
+def _calculate_base_stacklevel(default: int, offset: int) -> int:
+    """Calculate the default logging stacklevel to use.
+
+    Parameters
+    ----------
+    default : `int`
+        The stacklevel to use in Python 3.11 and newer where the only
+        thing to take into account is the number of levels above the core
+        Python logging infrastructure.
+    offset : `int`
+        The offset to apply for older Python implementations that need to
+        take into account internal call stacks.
+
+    Returns
+    -------
+    stacklevel : `int`
+        The stack level to pass to internal logging APIs that should result
+        in the log messages being reported in caller lines.
+
+    Notes
+    -----
+    In Python 3.11 the logging infrastructure was fixed such that we no
+    longer need to understand that a LoggerAdapter log messages need to
+    have a stack level one higher than a Logger would need. ``stacklevel=1``
+    now always means "log from the caller's line" without the caller having
+    to understand internal implementation details.
+    """
+    stacklevel = default
+    if sys.version_info < (3, 11, 0):
+        stacklevel += offset
+    return stacklevel
+
+
 def trace_set_at(name: str, number: int) -> None:
     """Adjust logging level to display messages with the trace number being
     less than or equal to the provided value.
@@ -132,8 +195,14 @@ class LsstLogAdapter(LoggerAdapter):
     TRACE = TRACE
     VERBOSE = VERBOSE
 
+    # The stack level to use when issuing log messages. For Python 3.11
+    # this is generally 2 (this method and the internal infrastructure).
+    # For older python we need one higher because of the extra indirection
+    # via LoggingAdapter internals.
+    _stacklevel = _calculate_base_stacklevel(2, 1)
+
     @contextmanager
-    def temporary_log_level(self, level: Union[int, str]) -> Generator:
+    def temporary_log_level(self, level: int | str) -> Generator:
         """Temporarily set the level of this logger.
 
         Parameters
@@ -168,111 +237,71 @@ class LsstLogAdapter(LoggerAdapter):
         """
         return getLogger(name=name, logger=self.logger)
 
-    @deprecated(
-        reason="Use Python Logger compatible isEnabledFor Will be removed after v23.",
-        version="v23",
-        category=FutureWarning,
-    )
-    def isDebugEnabled(self) -> bool:
-        return self.isEnabledFor(self.DEBUG)
-
-    @deprecated(
-        reason="Use Python Logger compatible 'name' attribute. Will be removed after v23.",
-        version="v23",
-        category=FutureWarning,
-    )
-    def getName(self) -> str:
-        return self.name
-
-    @deprecated(
-        reason="Use Python Logger compatible .level property. Will be removed after v23.",
-        version="v23",
-        category=FutureWarning,
-    )
-    def getLevel(self) -> int:
-        return self.logger.level
+    def _process_stacklevel(self, kwargs: dict[str, Any], offset: int = 0) -> int:
+        # Return default stacklevel, taking into account kwargs[stacklevel].
+        stacklevel = self._stacklevel
+        if "stacklevel" in kwargs:
+            # External user expects stacklevel=1 to mean "report from their
+            # line" but the code here is already trying to achieve that by
+            # default. Therefore if an external stacklevel is specified we
+            # adjust their stacklevel request by 1.
+            stacklevel = stacklevel + kwargs.pop("stacklevel") - 1
+
+        # The offset can be used to indicate that we have to take into account
+        # additional internal layers before calling python logging.
+        return _calculate_base_stacklevel(stacklevel, offset)
 
     def fatal(self, msg: str, *args: Any, **kwargs: Any) -> None:
         # Python does not provide this method in LoggerAdapter but does
-        # not formally deprecated it in favor of critical() either.
+        # not formally deprecate it in favor of critical() either.
         # Provide it without deprecation message for consistency with Python.
-        # stacklevel=5 accounts for the forwarding of LoggerAdapter.
-        self.critical(msg, *args, **kwargs, stacklevel=4)
+        # Have to adjust stacklevel on Python 3.10 and older to account
+        # for call through self.critical.
+        stacklevel = self._process_stacklevel(kwargs, offset=1)
+        self.critical(msg, *args, **kwargs, stacklevel=stacklevel)
 
     def verbose(self, fmt: str, *args: Any, **kwargs: Any) -> None:
         """Issue a VERBOSE level log message.
 
         Arguments are as for `logging.info`.
         ``VERBOSE`` is between ``DEBUG`` and ``INFO``.
+
+        Parameters
+        ----------
+        fmt : `str`
+            Log message.
+        *args : `~typing.Any`
+            Parameters references by log message.
+        **kwargs : `~typing.Any`
+            Parameters forwarded to `log`.
         """
         # There is no other way to achieve this other than a special logger
         # method.
         # Stacklevel is passed in so that the correct line is reported
-        # in the log record and not this line. 3 is this method,
-        # 2 is the level from `self.log` and 1 is the log infrastructure
-        # itself.
-        self.log(VERBOSE, fmt, *args, stacklevel=3, **kwargs)
+        stacklevel = self._process_stacklevel(kwargs)
+        self.log(VERBOSE, fmt, *args, **kwargs, stacklevel=stacklevel)
 
-    def trace(self, fmt: str, *args: Any) -> None:
+    def trace(self, fmt: str, *args: Any, **kwargs: Any) -> None:
         """Issue a TRACE level log message.
 
         Arguments are as for `logging.info`.
         ``TRACE`` is lower than ``DEBUG``.
+
+        Parameters
+        ----------
+        fmt : `str`
+            Log message.
+        *args : `~typing.Any`
+            Parameters references by log message.
+        **kwargs : `~typing.Any`
+            Parameters forwarded to `log`.
         """
         # There is no other way to achieve this other than a special logger
-        # method. For stacklevel discussion see `verbose()`.
-        self.log(TRACE, fmt, *args, stacklevel=3)
-
-    @deprecated(
-        reason="Use Python Logger compatible method. Will be removed after v23.",
-        version="v23",
-        category=FutureWarning,
-    )
-    def tracef(self, fmt: str, *args: Any, **kwargs: Any) -> None:
-        # Stacklevel is 4 to account for the deprecation wrapper
-        self.log(TRACE, _F(fmt, *args, **kwargs), stacklevel=4)
-
-    @deprecated(
-        reason="Use Python Logger compatible method. Will be removed after v23.",
-        version="v23",
-        category=FutureWarning,
-    )
-    def debugf(self, fmt: str, *args: Any, **kwargs: Any) -> None:
-        self.log(logging.DEBUG, _F(fmt, *args, **kwargs), stacklevel=4)
-
-    @deprecated(
-        reason="Use Python Logger compatible method. Will be removed after v23.",
-        version="v23",
-        category=FutureWarning,
-    )
-    def infof(self, fmt: str, *args: Any, **kwargs: Any) -> None:
-        self.log(logging.INFO, _F(fmt, *args, **kwargs), stacklevel=4)
-
-    @deprecated(
-        reason="Use Python Logger compatible method. Will be removed after v23.",
-        version="v23",
-        category=FutureWarning,
-    )
-    def warnf(self, fmt: str, *args: Any, **kwargs: Any) -> None:
-        self.log(logging.WARNING, _F(fmt, *args, **kwargs), stacklevel=4)
-
-    @deprecated(
-        reason="Use Python Logger compatible method. Will be removed after v23.",
-        version="v23",
-        category=FutureWarning,
-    )
-    def errorf(self, fmt: str, *args: Any, **kwargs: Any) -> None:
-        self.log(logging.ERROR, _F(fmt, *args, **kwargs), stacklevel=4)
-
-    @deprecated(
-        reason="Use Python Logger compatible method. Will be removed after v23.",
-        version="v23",
-        category=FutureWarning,
-    )
-    def fatalf(self, fmt: str, *args: Any, **kwargs: Any) -> None:
-        self.log(logging.CRITICAL, _F(fmt, *args, **kwargs), stacklevel=4)
-
-    def setLevel(self, level: Union[int, str]) -> None:
+        # method.
+        stacklevel = self._process_stacklevel(kwargs)
+        self.log(TRACE, fmt, *args, **kwargs, stacklevel=stacklevel)
+
+    def setLevel(self, level: int | str) -> None:
         """Set the level for the logger, trapping lsst.log values.
 
         Parameters
@@ -291,23 +320,32 @@ class LsstLogAdapter(LoggerAdapter):
         self.logger.setLevel(level)
 
     @property
-    def handlers(self) -> List[logging.Handler]:
+    def handlers(self) -> list[logging.Handler]:
         """Log handlers associated with this logger."""
         return self.logger.handlers
 
     def addHandler(self, handler: logging.Handler) -> None:
         """Add a handler to this logger.
 
-        The handler is forwarded to the underlying logger.
+        Parameters
+        ----------
+        handler : `logging.Handler`
+           Handler to add. The handler is forwarded to the underlying logger.
         """
         self.logger.addHandler(handler)
 
     def removeHandler(self, handler: logging.Handler) -> None:
-        """Remove the given handler from the underlying logger."""
+        """Remove the given handler from the underlying logger.
+
+        Parameters
+        ----------
+        handler : `logging.Handler`
+            Handler to remove.
+        """
         self.logger.removeHandler(handler)
 
 
-def getLogger(name: Optional[str] = None, logger: Optional[logging.Logger] = None) -> LsstLogAdapter:
+def getLogger(name: str | None = None, logger: logging.Logger | None = None) -> LsstLogAdapter:
     """Get a logger compatible with LSST usage.
 
     Parameters
@@ -330,7 +368,7 @@ def getLogger(name: Optional[str] = None, logger: Optional[logging.Logger] = Non
     uniform interface than when using `logging.setLoggerClass`. An adapter
     can be wrapped around the root logger and the `~logging.setLoggerClass`
     will return the logger first given that name even if the name was
-    used before the `Task` was created.
+    used before the `~lsst.pipe.base.Task` was created.
     """
     if not logger:
         logger = logging.getLogger(name)
@@ -339,10 +377,10 @@ def getLogger(name: Optional[str] = None, logger: Optional[logging.Logger] = Non
     return LsstLogAdapter(logger, {})
 
 
-LsstLoggers = Union[logging.Logger, LsstLogAdapter]
+LsstLoggers: TypeAlias = logging.Logger | LsstLogAdapter
 
 
-def getTraceLogger(logger: Union[str, LsstLoggers], trace_level: int) -> LsstLogAdapter:
+def getTraceLogger(logger: str | LsstLoggers, trace_level: int) -> LsstLogAdapter:
     """Get a logger with the appropriate TRACE name.
 
     Parameters
@@ -372,22 +410,28 @@ class PeriodicLogger:
     be useful to issue a log message periodically to show that the
     algorithm is progressing.
 
+    The first time threshold is counted from object construction, so in general
+    the first call to `log` does not log.
+
     Parameters
     ----------
     logger : `logging.Logger` or `LsstLogAdapter`
         Logger to use when issuing a message.
     interval : `float`
-        The minimum interval between log messages. If `None` the class
-        default will be used.
+        The minimum interval in seconds between log messages. If `None`,
+        `LOGGING_INTERVAL` will be used.
     level : `int`, optional
-        Log level to use when issuing messages.
+        Log level to use when issuing messages, default is
+        `~logging.INFO`.
     """
 
     LOGGING_INTERVAL = 600.0
-    """Default interval between log messages."""
+    """Default interval between log messages in seconds."""
 
-    def __init__(self, logger: LsstLoggers, interval: Optional[float] = None, level: int = VERBOSE):
+    def __init__(self, logger: LsstLoggers, interval: float | None = None, level: int = logging.INFO):
         self.logger = logger
+        # None -> LOGGING_INTERVAL conversion done so that unit tests (e.g., in
+        # pipe_base) can tweak log interval without access to the constructor.
         self.interval = interval if interval is not None else self.LOGGING_INTERVAL
         self.level = level
         self.next_log_time = time.time() + self.interval
@@ -395,18 +439,24 @@ class PeriodicLogger:
 
         # The stacklevel we need to issue logs is determined by the type
         # of logger we have been given. A LoggerAdapter has an extra
-        # level of indirection.
-        self._stacklevel = 3 if isinstance(self.logger, LoggerAdapter) else 2
+        # level of indirection. In Python 3.11 the logging infrastructure
+        # takes care to check for internal logging stack frames so there
+        # is no need for a difference.
+        self._stacklevel = _calculate_base_stacklevel(2, 1 if isinstance(self.logger, LoggerAdapter) else 0)
 
     def log(self, msg: str, *args: Any) -> bool:
         """Issue a log message if the interval has elapsed.
 
+        The interval is measured from the previous call to ``log``, or from the
+        creation of this object.
+
         Parameters
         ----------
         msg : `str`
             Message to issue if the time has been exceeded.
         *args : Any
-            Parameters to be passed to the log system.
+            Arguments to be merged into the message string, as described under
+            `logging.Logger.debug`.
 
         Returns
         -------