lsst-utils 29.2025.4000__py3-none-any.whl → 29.2025.4100__py3-none-any.whl

lsst/utils/logging.py

@@ -28,13 +28,24 @@ import time
 from collections.abc import Generator
 from contextlib import contextmanager
 from logging import LoggerAdapter
-from typing import Any, TypeAlias
+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
@@ -45,6 +56,23 @@ 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.
 

lsst/utils/timer.py

@@ -32,7 +32,7 @@ from typing import TYPE_CHECKING, Any, TypeVar, overload
 from astropy import units as u
 
 from .introspection import find_outside_stacklevel
-from .logging import LsstLoggers
+from .logging import LsstLoggers, _is_structlog_logger
 from .usage import _get_current_rusage, get_current_mem_usage, get_peak_mem_usage
 
 if TYPE_CHECKING:
@@ -374,9 +374,10 @@ def time_this(
     level: int = logging.DEBUG,
     prefix: str | None = "timer",
     args: Iterable[Any] = (),
+    kwargs: dict[str, Any] | None = None,
     mem_usage: bool = False,
     mem_child: bool = False,
-    mem_unit: u.Quantity = u.byte,
+    mem_unit: u.Unit = u.byte,
     mem_fmt: str = ".0f",
     force_mem_usage: bool = False,
 ) -> Iterator[_TimerResult]:
@@ -386,7 +387,8 @@ def time_this(
     ----------
     log : `logging.Logger`, optional
         Logger to use to report the timer message. The root logger will
-        be used if none is given.
+        be used if none is given. Is also allowed to be a `structlog` bound
+        logger.
     msg : `str`, optional
         Context to include in log message.
     level : `int`, optional
@@ -400,6 +402,11 @@ def time_this(
     args : iterable of any
         Additional parameters passed to the log command that should be
         written to ``msg``.
+    kwargs : `dict`, optional
+        Additional keyword parameters passed to the log command. If a Structlog
+        is used then these will be added to the structured data. Otherwise
+        they will be converted to a single string for inclusion in the log
+        message.
     mem_usage : `bool`, optional
         Flag indicating whether to include the memory usage in the report.
         Defaults, to False. Does nothing if the log message will not be
@@ -424,10 +431,17 @@ def time_this(
     """
     if log is None:
         log = logging.getLogger()
-    if prefix:
+    is_structlog = _is_structlog_logger(log)
+    if prefix and not is_structlog:
+        # Struct log loggers do not have a name property and so the prefix
+        # is not applied to them.
         log_name = f"{prefix}.{log.name}" if not isinstance(log, logging.RootLogger) else prefix
         log = logging.getLogger(log_name)
 
+    # Some structured data that can be used if we have been given a
+    # structlog logger.
+    structured_args: dict[str, Any] = {}
+
     start = time.time()
 
     if mem_usage and not log.isEnabledFor(level):
@@ -467,6 +481,7 @@ def time_this(
         # caller (1 is this file, 2 is contextlib, 3 is user)
         params += (": " if msg else "", duration)
         msg += "%sTook %.4f seconds"
+        structured_args["duration"] = duration
         if errmsg:
             params += (f" (timed code triggered exception of {errmsg!r})",)
             msg += "%s"
@@ -502,7 +517,20 @@ def time_this(
                 f", delta: {current_delta:{mem_fmt}}"
                 f", peak delta: {peak_delta:{mem_fmt}}"
             )
-        log.log(level, msg, *params, stacklevel=3)
+            structured_args["mem_current_usage"] = float(current_usage.value)
+            structured_args["mem_current_delta"] = float(current_delta.value)
+            structured_args["mem_peak_delta"] = float(peak_delta.value)
+        if not is_structlog:
+            # Can only use the structured content if we have structlog logger
+            # but stacklevel is only supported by standard loggers.
+            structured_args = {"stacklevel": 3}
+            if kwargs is not None:
+                msg += " %s"
+                params += ("; ".join(f"{k}={v!r}" for k, v in kwargs.items()),)
+        elif kwargs:
+            structured_args.update(kwargs)
+
+        log.log(level, msg, *params, **structured_args)
 
 
 @contextmanager

lsst/utils/version.py

@@ -1,2 +1,2 @@
 __all__ = ["__version__"]
-__version__ = "29.2025.4000"
+__version__ = "29.2025.4100"

{lsst_utils-29.2025.4000.dist-info → lsst_utils-29.2025.4100.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lsst-utils
-Version: 29.2025.4000
+Version: 29.2025.4100
 Summary: Utility functions from Rubin Observatory Data Management for the Legacy Survey of Space and Time (LSST).
 Author-email: Rubin Observatory Data Management <dm-admin@lists.lsst.org>
 License: BSD 3-Clause License
@@ -22,6 +22,7 @@ Requires-Dist: psutil>=5.7
 Requires-Dist: deprecated>=1.2
 Requires-Dist: pyyaml>=5.1
 Requires-Dist: astropy>=5.0
+Requires-Dist: structlog
 Requires-Dist: threadpoolctl
 Provides-Extra: test
 Requires-Dist: pytest>=3.2; extra == "test"

{lsst_utils-29.2025.4000.dist-info → lsst_utils-29.2025.4100.dist-info}/RECORD

@@ -9,24 +9,24 @@ lsst/utils/doImport.py,sha256=JbD_AR1GQ1PVdK--OJy5tVz1U2Kabe1ETyQoyaq6rpQ,4241
 lsst/utils/inheritDoc.py,sha256=doMsQKcDssZvsTAYJSmHxOWXM4D1wPrDSCTHiaRGUvw,2719
 lsst/utils/introspection.py,sha256=Y1ImDWl5i1O9iRbOoSJhr8Rz57y-_WMgwDtbGJBVxJk,14735
 lsst/utils/iteration.py,sha256=FHDGWcAbWzJdN1RVP-LdtatBfmCW9x_2MdQ5iwmT1sE,9278
-lsst/utils/logging.py,sha256=pNXLqeUkm5yBwzPCVFskoy11kEz-N9YXOOYItEPK8ds,15344
+lsst/utils/logging.py,sha256=TPtKK5ShYAEeIFlqhYkEGGSDeUwiMWWzOb1CQGHMBlU,16256
 lsst/utils/packages.py,sha256=D2eD2Qy3P_Os7RbUKsG2mPyLoSLjqejUX6lNhaC16wg,27455
 lsst/utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 lsst/utils/tests.py,sha256=1cjyXtEL2LNhnPKjtiTt9cdPmlaEWgaWBx9BfM-xSmA,39152
 lsst/utils/threads.py,sha256=WNl3uvbE7bx5UyxTX0fwN5AkU3Yty_m8y_pMKcMCdv8,2551
-lsst/utils/timer.py,sha256=N0XTE9-UN5ziKq_GP8x2xa0CZbXwMhF0hrTLc1z56sM,20545
+lsst/utils/timer.py,sha256=p_qOEQEIqfQubQJmaN4pK-3YUqZCocY08fBgpnSTXh0,21961
 lsst/utils/usage.py,sha256=qunydx-KlcbNp-vFcBtvBayWwZAa0tHtSWvz5BycvLA,4598
-lsst/utils/version.py,sha256=OZgl6BR-Rxy62NJlHO2yg_Rq4EhfmRSKDkEEnAyc-3Q,55
+lsst/utils/version.py,sha256=imQpc8l8n1Xj3guWKoFaXrBR3HnAY8jkMITBuZx-5DA,55
 lsst/utils/wrappers.py,sha256=KCvsrGXziLQ5pC8ytiFEXeDH9mBSo8eCZ8g08f7s404,19209
 lsst/utils/plotting/__init__.py,sha256=OEAZv2W12UAcUfDxH5H_k8v7cK4fVTOssuqNksZTuIs,507
 lsst/utils/plotting/figures.py,sha256=pLkD7MpYk1Zs2hozA2-6r_uUd1129Uoi9EAEkMvtCjk,4356
 lsst/utils/plotting/limits.py,sha256=6ilPmb4wg4aVtjlBgm75FPBrjDVSkW_ywZrj_QIQD2U,5839
 lsst/utils/plotting/publication_plots.py,sha256=-uOL2ptI3N52KxfhtJNsUt7SqeGdT78GF-_QjHKKmV8,5016
 lsst/utils/plotting/rubin.mplstyle,sha256=mjLPYzolUjeCXq8z4ltXLvEf8IuyT4TS0Nx8JJ05v6I,1063
-lsst_utils-29.2025.4000.dist-info/licenses/COPYRIGHT,sha256=I6Bxnp_LkIqDjafZNIXM8jfjYWC4XIlpNpZ7jkdeZK0,361
-lsst_utils-29.2025.4000.dist-info/licenses/LICENSE,sha256=7wrtgl8meQ0_RIuv2TjIKpAnNrl-ODH-QLwyHe9citI,1516
-lsst_utils-29.2025.4000.dist-info/METADATA,sha256=JFV1Vqs6mCL9e-rITM-qD2MEAi1ZWjCLVrSc--c5gCo,1691
-lsst_utils-29.2025.4000.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lsst_utils-29.2025.4000.dist-info/top_level.txt,sha256=eUWiOuVVm9wwTrnAgiJT6tp6HQHXxIhj2QSZ7NYZH80,5
-lsst_utils-29.2025.4000.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-lsst_utils-29.2025.4000.dist-info/RECORD,,
+lsst_utils-29.2025.4100.dist-info/licenses/COPYRIGHT,sha256=I6Bxnp_LkIqDjafZNIXM8jfjYWC4XIlpNpZ7jkdeZK0,361
+lsst_utils-29.2025.4100.dist-info/licenses/LICENSE,sha256=7wrtgl8meQ0_RIuv2TjIKpAnNrl-ODH-QLwyHe9citI,1516
+lsst_utils-29.2025.4100.dist-info/METADATA,sha256=cj8DGTjiJoiu4vsBTeqSyYkCVrcG7jg6nL9-nai87x4,1716
+lsst_utils-29.2025.4100.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lsst_utils-29.2025.4100.dist-info/top_level.txt,sha256=eUWiOuVVm9wwTrnAgiJT6tp6HQHXxIhj2QSZ7NYZH80,5
+lsst_utils-29.2025.4100.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+lsst_utils-29.2025.4100.dist-info/RECORD,,