Merge pull request #181 from lsst/tickets/DM-40441

DM-40441: annotate more timer functions as accepting LsstLogAdapter

.github/workflows/build.yaml

@@ -16,12 +16,12 @@ jobs:
         python-version: ["3.10", "3.11", "3.12"]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           # Need to clone everything to determine version from git.
           fetch-depth: 0
 
-      - uses: conda-incubator/setup-miniconda@v2
+      - uses: conda-incubator/setup-miniconda@v3
         with:
           python-version: ${{ matrix.python-version }}
           channels: conda-forge,defaults
@@ -53,7 +53,8 @@ jobs:
       - name: Install dependencies
         shell: bash -l {0}
         run: |
-          pip install -r requirements.txt
+          pip install uv
+          uv pip install --system -r requirements.txt
 
       - name: List installed packages
         shell: bash -l {0}
@@ -63,7 +64,7 @@ jobs:
 
       - name: Build and install
         shell: bash -l {0}
-        run: pip install --no-deps -v -e .
+        run: uv pip install --system --no-deps -v -e .
 
       - name: Setup EUPS test package
         shell: bash -l {0}
@@ -94,13 +95,13 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/')
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           # Need to clone everything to embed the version.
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.10"
 

.github/workflows/build_docs.yaml

@@ -10,13 +10,13 @@ jobs:
   build_sphinx_docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           # Need to clone everything to determine version from git.
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.11"
           cache: "pip"
@@ -28,17 +28,18 @@ jobs:
       - name: Update pip/wheel infrastructure
         run: |
           python -m pip install --upgrade pip
-          pip install wheel
+          pip install uv
+          uv pip install --system wheel
 
       - name: Install documenteer
-        run: pip install 'documenteer[pipelines]==0.8.2'
+        run: uv pip install --system 'documenteer[pipelines]==0.8.2'
 
       - name: Install dependencies
         run: |
-          pip install -r requirements.txt
+          uv pip install --system -r requirements.txt
 
       - name: Build and install
-        run: pip install --no-deps -v .
+        run: uv pip install --system --no-deps -v -e .
 
       - name: Build documentation
         working-directory: ./doc

.github/workflows/do_not_merge.yaml

@@ -26,7 +26,7 @@ jobs:
             'DO NOT MERGE'. Remove this commit from the branch before merging
             or change the commit summary."
 
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Check requirements.txt for branches
         shell: bash

.github/workflows/docstyle.yaml

@@ -14,10 +14,10 @@ jobs:
   numpydoc:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
 
       - name: Install numpydoc
         run: |

.github/workflows/lint.yaml

@@ -12,5 +12,5 @@ jobs:
   ruff:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: chartboost/ruff-action@v1

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 23.11.0
+    rev: 24.3.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
@@ -17,16 +17,16 @@ repos:
         # https://pre-commit.com/#top_level-default_language_version
         language_version: python3.11
   - repo: https://github.com/pycqa/isort
-    rev: 5.13.0
+    rev: 5.13.2
     hooks:
       - id: isort
         name: isort (python)
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.1.7
+    rev: v0.3.4
     hooks:
       - id: ruff
   - repo: https://github.com/numpy/numpydoc
-    rev: "v1.6.0"
+    rev: "v1.7.0"
     hooks:
       - id: numpydoc-validation

doc/changes/DM-40441.misc.md

@@ -0,0 +1 @@
+Export type aliases for LSST log adapters for use in downstream static typing.

doc/conf.py

@@ -24,4 +24,5 @@
     ("py:obj", "logging.DEBUG"),  # Python 3 constant can not be found.
     ("py:class", "unittest.case.TestCase"),  # Sphinx can not see TestCase.
     ("py:obj", "deprecated.sphinx.deprecated"),  # No intersphinx for deprecated package.
+    ("py:class", "LsstLoggers"),  # Sphinx does not understand type aliases
 ]

pyproject.toml

@@ -126,9 +126,13 @@ exclude_lines = [
 ]
 
 [tool.ruff]
+line-length = 110
+target-version = "py311"
 exclude = [
     "__init__.py",
 ]
+
+[tool.ruff.lint]
 ignore = [
     "N802",
     "N803",
@@ -146,23 +150,21 @@ ignore = [
     "D205",
     "D400",
 ]
-line-length = 110
 select = [
     "E",  # pycodestyle
     "F",  # pyflakes
     "N",  # pep8-naming
     "W",  # pycodestyle
     "D",  # pydocstyle
 ]
-target-version = "py311"
 extend-select = [
     "RUF100", # Warn about unused noqa
 ]
 
-[tool.ruff.pycodestyle]
+[tool.ruff.lint.pycodestyle]
 max-doc-length = 79
 
-[tool.ruff.pydocstyle]
+[tool.ruff.lint.pydocstyle]
 convention = "numpy"
 
 [tool.numpydoc_validation]

python/lsst/utils/logging.py

@@ -17,6 +17,7 @@
     "getLogger",
     "getTraceLogger",
     "LsstLogAdapter",
+    "LsstLoggers",
     "PeriodicLogger",
     "trace_set_at",
 )
@@ -27,7 +28,7 @@
 from collections.abc import Generator
 from contextlib import contextmanager
 from logging import LoggerAdapter
-from typing import Any, Union
+from typing import Any, TypeAlias, Union
 
 try:
     import lsst.log.utils as logUtils
@@ -348,7 +349,7 @@ def getLogger(name: str | None = None, logger: logging.Logger | None = None) ->
     return LsstLogAdapter(logger, {})
 
 
-LsstLoggers = Union[logging.Logger, LsstLogAdapter]
+LsstLoggers: TypeAlias = Union[logging.Logger, LsstLogAdapter]
 
 
 def getTraceLogger(logger: str | LsstLoggers, trace_level: int) -> LsstLogAdapter:

python/lsst/utils/timer.py

@@ -76,7 +76,7 @@ def logPairs(
     pairs: Collection[tuple[str, Any]],
     logLevel: int = logging.DEBUG,
     metadata: MutableMapping | None = None,
-    logger: logging.Logger | None = None,
+    logger: LsstLoggers | None = None,
     stacklevel: int | None = None,
 ) -> None:
     """Log ``(name, value)`` pairs to ``obj.metadata`` and ``obj.log``.
@@ -99,7 +99,7 @@ def logPairs(
         Log level (an `logging` level constant, such as `logging.DEBUG`).
     metadata : `collections.abc.MutableMapping`, optional
         Metadata object to write entries to.  Ignored if `None`.
-    logger : `logging.Logger`
+    logger : `logging.Logger` or `lsst.utils.logging.LsstLogAdapter`
         Log object to write entries to.  Ignored if `None`.
     stacklevel : `int`, optional
         The stack level to pass to the logger to adjust which stack frame
@@ -141,7 +141,7 @@ def logInfo(
     prefix: str,
     logLevel: int = logging.DEBUG,
     metadata: MutableMapping | None = None,
-    logger: logging.Logger | None = None,
+    logger: LsstLoggers | None = None,
     stacklevel: int | None = None,
 ) -> None:
     """Log timer information to ``obj.metadata`` and ``obj.log``.
@@ -166,7 +166,7 @@ def logInfo(
         Log level (a `logging` level constant, such as `logging.DEBUG`).
     metadata : `collections.abc.MutableMapping`, optional
         Metadata object to write entries to, overriding ``obj.metadata``.
-    logger : `logging.Logger`
+    logger : `logging.Logger` or `lsst.utils.logging.LsstLogAdapter`
         Log object to write entries to, overriding ``obj.log``.
     stacklevel : `int`, optional
         The stack level to pass to the logger to adjust which stack frame
@@ -231,7 +231,7 @@ def timeMethod(
     _func: Any | None = None,
     *,
     metadata: MutableMapping | None = None,
-    logger: logging.Logger | None = None,
+    logger: LsstLoggers | None = None,
     logLevel: int = logging.DEBUG,
 ) -> Callable:
     """Measure duration of a method.
@@ -243,7 +243,7 @@ def timeMethod(
     metadata : `collections.abc.MutableMapping`, optional
         Metadata to use as override if the instance object attached
         to this timer does not support a ``metadata`` property.
-    logger : `logging.Logger`, optional
+    logger : `logging.Logger` or `lsst.utils.logging.LsstLogAdapter`, optional
         Logger to use when the class containing the decorated method does not
         have a ``log`` property.
     logLevel : `int`, optional
@@ -429,15 +429,15 @@ def time_this(
 
 
 @contextmanager
-def profile(filename: str | None, log: logging.Logger | None = None) -> Iterator[cProfile.Profile | None]:
+def profile(filename: str | None, log: LsstLoggers | None = None) -> Iterator[cProfile.Profile | None]:
     """Profile the enclosed code block and save the result to a file.
 
     Parameters
     ----------
     filename : `str` or `None`
         Filename to which to write profile (profiling disabled if `None` or
         empty string).
-    log : `logging.Logger`, optional
+    log : `logging.Logger` or `lsst.utils.logging.LsstLogAdapter`, optional
         Log object for logging the profile operations.
 
     Yields

tests/test_db_auth.py

@@ -233,19 +233,19 @@ def test_getUrl(self):
         self.assertEqual(
             auth.getUrl("postgresql://[email protected]:5432/my_database"),
             "postgresql://user:[email protected]:5432/my_database",
-        ),
+        )
         self.assertEqual(
             auth.getUrl("postgresql://[email protected]/my_database"),
             "postgresql://user:[email protected]/my_database",
-        ),
+        )
         self.assertEqual(
             auth.getUrl("postgresql://host.example.com/my_database"),
             "postgresql://foo:[email protected]/my_database",
-        ),
+        )
         self.assertEqual(
             auth.getUrl("postgresql://host.example.com:5432/my_database"),
             "postgresql://foo:[email protected]:5432/my_database",
-        ),
+        )
 
         filePath = os.path.join(TESTDIR, "db-auth.yaml")
         os.chmod(filePath, 0o600)