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

lsst/utils/tests.py

@@ -9,22 +9,22 @@
 # Use of this source code is governed by a 3-clause BSD-style
 # license that can be found in the LICENSE file.
 
-"""Support code for running unit tests"""
+"""Support code for running unit tests."""
 
 from __future__ import annotations
 
 __all__ = [
-    "init",
-    "MemoryTestCase",
     "ExecutablesTestCase",
     "ImportTestCase",
-    "getTempFilePath",
+    "MemoryTestCase",
     "TestCase",
     "assertFloatsAlmostEqual",
-    "assertFloatsNotEqual",
     "assertFloatsEqual",
-    "debugger",
+    "assertFloatsNotEqual",
     "classParameters",
+    "debugger",
+    "getTempFilePath",
+    "init",
     "methodParameters",
     "temporaryDirectory",
 ]
@@ -32,7 +32,6 @@ __all__ = [
 import contextlib
 import functools
 import gc
-import importlib.resources as resources
 import inspect
 import itertools
 import os
@@ -43,7 +42,8 @@ import sys
 import tempfile
 import unittest
 import warnings
-from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
+from collections.abc import Callable, Container, Iterable, Iterator, Mapping, Sequence
+from importlib import resources
 from typing import Any, ClassVar
 
 import numpy
@@ -129,12 +129,12 @@ unittest.defaultTestLoader.suiteClass = _suiteClassWrapper
 class MemoryTestCase(unittest.TestCase):
     """Check for resource leaks."""
 
-    ignore_regexps: list[str] = []
+    ignore_regexps: ClassVar[list[str]] = []
     """List of regexps to ignore when checking for open files."""
 
     @classmethod
     def tearDownClass(cls) -> None:
-        """Reset the leak counter when the tests have been completed"""
+        """Reset the leak counter when the tests have been completed."""
         init()
 
     def testFileDescriptorLeaks(self) -> None:
@@ -153,6 +153,7 @@ class MemoryTestCase(unittest.TestCase):
             for f in now_open
             if not f.endswith(".car")
             and not f.startswith("/proc/")
+            and not f.startswith("/sys/")
             and not f.endswith(".ttf")
             and not (f.startswith("/var/lib/") and f.endswith("/passwd"))
             and not f.endswith("astropy.log")
@@ -165,7 +166,7 @@ class MemoryTestCase(unittest.TestCase):
         if diff:
             for f in diff:
                 print(f"File open: {f}")
-            self.fail("Failed to close %d file%s" % (len(diff), "s" if len(diff) != 1 else ""))
+            self.fail(f"Failed to close {len(diff)} file{'s' if len(diff) != 1 else ''}")
 
 
 class ExecutablesTestCase(unittest.TestCase):
@@ -346,6 +347,16 @@ class ImportTestCase(unittest.TestCase):
     PACKAGES: ClassVar[Iterable[str]] = ()
     """Packages to be imported."""
 
+    SKIP_FILES: ClassVar[Mapping[str, Container[str]]] = {}
+    """Files to be skipped importing; specified as key-value pairs.
+
+    The key is the package name and the value is a set of files names in that
+    package to skip.
+
+    Note: Files with names not ending in .py or beginning with leading double
+    underscores are always skipped.
+    """
+
     _n_registered = 0
     """Number of packages registered for testing by this class."""
 
@@ -367,7 +378,7 @@ class ImportTestCase(unittest.TestCase):
         for mod in cls.PACKAGES:
             test_name = "test_import_" + mod.replace(".", "_")
 
-            def test_import(*args: Any) -> None:
+            def test_import(*args: Any, mod=mod) -> None:
                 self = args[0]
                 self.assertImport(mod)
 
@@ -378,15 +389,19 @@ class ImportTestCase(unittest.TestCase):
         # If there are no packages listed that is likely a mistake and
         # so register a failing test.
         if cls._n_registered == 0:
-            setattr(cls, "test_no_packages_registered", cls._test_no_packages_registered_for_import_testing)
+            cls.test_no_packages_registered = cls._test_no_packages_registered_for_import_testing
 
     def assertImport(self, root_pkg):
         for file in resources.files(root_pkg).iterdir():
             file = file.name
+            # When support for python 3.9 is dropped, this could be updated to
+            # use match case construct.
             if not file.endswith(".py"):
                 continue
             if file.startswith("__"):
                 continue
+            if file in self.SKIP_FILES.get(root_pkg, ()):
+                continue
             root, _ = os.path.splitext(file)
             module_name = f"{root_pkg}.{root}"
             with self.subTest(module=module_name):
@@ -399,7 +414,7 @@ class ImportTestCase(unittest.TestCase):
 @contextlib.contextmanager
 def getTempFilePath(ext: str, expectOutput: bool = True) -> Iterator[str]:
     """Return a path suitable for a temporary file and try to delete the
-    file on success
+    file on success.
 
     If the with block completes successfully then the file is deleted,
     if possible; failure results in a printed warning.
@@ -419,11 +434,11 @@ def getTempFilePath(ext: str, expectOutput: bool = True) -> Iterator[str]:
         If `False`, a file should not be present when the context manager
         exits.
 
-    Returns
-    -------
+    Yields
+    ------
     path : `str`
         Path for a temporary file. The path is a combination of the caller's
-        file path and the name of the top-level function
+        file path and the name of the top-level function.
 
     Examples
     --------
@@ -432,6 +447,8 @@ def getTempFilePath(ext: str, expectOutput: bool = True) -> Iterator[str]:
         # file tests/testFoo.py
         import unittest
         import lsst.utils.tests
+
+
         class FooTestCase(unittest.TestCase):
             def testBasics(self):
                 self.runTest()
@@ -445,6 +462,8 @@ def getTempFilePath(ext: str, expectOutput: bool = True) -> Iterator[str]:
                     # at the end of this "with" block the path tmpFile will be
                     # deleted, but only if the file exists and the "with"
                     # block terminated normally (rather than with an exception)
+
+
         ...
     """
     stack = inspect.stack()
@@ -464,7 +483,11 @@ def getTempFilePath(ext: str, expectOutput: bool = True) -> Iterator[str]:
     callerFileName = os.path.splitext(callerFileNameWithExt)[0]
     outDir = os.path.join(callerDir, ".tests")
     if not os.path.isdir(outDir):
-        outDir = ""
+        # No .tests directory implies we are not running with sconsUtils.
+        # Need to use the current working directory, the callerDir, or
+        # /tmp equivalent. If cwd is used if must be as an absolute path
+        # in case the test code changes cwd.
+        outDir = os.path.abspath(os.path.curdir)
     prefix = f"{callerFileName}_{callerFuncName}-"
     outPath = tempfile.mktemp(dir=outDir, suffix=ext, prefix=prefix)
     if os.path.exists(outPath):
@@ -473,10 +496,8 @@ def getTempFilePath(ext: str, expectOutput: bool = True) -> Iterator[str]:
         # Use stacklevel 3 so that the warning is reported from the end of the
         # with block
         warnings.warn(f"Unexpectedly found pre-existing tempfile named {outPath!r}", stacklevel=3)
-        try:
+        with contextlib.suppress(OSError):
             os.remove(outPath)
-        except OSError:
-            pass
 
     yield outPath
 
@@ -506,13 +527,23 @@ class TestCase(unittest.TestCase):
 def inTestCase(func: Callable) -> Callable:
     """Add a free function to our custom TestCase class, while
     also making it available as a free function.
+
+    Parameters
+    ----------
+    func : `~collections.abc.Callable`
+        Function to be added to `unittest.TestCase` class.
+
+    Returns
+    -------
+    func : `~collections.abc.Callable`
+        The given function.
     """
     setattr(TestCase, func.__name__, func)
     return func
 
 
 def debugger(*exceptions):
-    """Enter the debugger when there's an uncaught exception
+    """Enter the debugger when there's an uncaught exception.
 
     To use, just slap a ``@debugger()`` on your function.
 
@@ -525,6 +556,12 @@ def debugger(*exceptions):
     Code provided by "Rosh Oxymoron" on StackOverflow:
     http://stackoverflow.com/questions/4398967/python-unit-testing-automatically-running-the-debugger-when-a-test-fails
 
+    Parameters
+    ----------
+    *exceptions : `Exception`
+        Specific exception classes to catch. Default is to catch
+        `AssertionError`.
+
     Notes
     -----
     Consider using ``pytest --pdb`` instead of this decorator.
@@ -560,13 +597,13 @@ def plotImageDiff(
     Parameters
     ----------
     lhs : `numpy.ndarray`
-        LHS values to compare; a 2-d NumPy array
+        LHS values to compare; a 2-d NumPy array.
     rhs : `numpy.ndarray`
-        RHS values to compare; a 2-d NumPy array
+        RHS values to compare; a 2-d NumPy array.
     bad : `numpy.ndarray`
-        A 2-d boolean NumPy array of values to emphasize in the plots
+        A 2-d boolean NumPy array of values to emphasize in the plots.
     diff : `numpy.ndarray`
-        difference array; a 2-d NumPy array, or None to show lhs-rhs
+        Difference array; a 2-d NumPy array, or None to show lhs-rhs.
     plotFileName : `str`
         Filename to save the plot to.  If None, the plot will be displayed in
         a window.
@@ -577,11 +614,20 @@ def plotImageDiff(
     wrapped in a try/except block within packages that do not depend on
     `matplotlib` (including `~lsst.utils`).
     """
-    from matplotlib import pyplot
+    if plotFileName is None:
+        # We need to create an interactive plot with pyplot.
+        from matplotlib import pyplot
+
+        fig = pyplot.figure()
+    else:
+        # We can create a non-interactive figure.
+        from .plotting import make_figure
+
+        fig = make_figure()
 
     if diff is None:
         diff = lhs - rhs
-    pyplot.figure()
+
     if bad is not None:
         # make an rgba image that's red and transparent where not bad
         badImage = numpy.zeros(bad.shape + (4,), dtype=numpy.uint8)
@@ -594,29 +640,29 @@ def plotImageDiff(
     vmin2 = numpy.min(diff)
     vmax2 = numpy.max(diff)
     for n, (image, title) in enumerate([(lhs, "lhs"), (rhs, "rhs"), (diff, "diff")]):
-        pyplot.subplot(2, 3, n + 1)
-        im1 = pyplot.imshow(
+        ax = fig.add_subplot(2, 3, n + 1)
+        im1 = ax.imshow(
             image, cmap=pyplot.cm.gray, interpolation="nearest", origin="lower", vmin=vmin1, vmax=vmax1
         )
         if bad is not None:
-            pyplot.imshow(badImage, alpha=0.2, interpolation="nearest", origin="lower")
-        pyplot.axis("off")
-        pyplot.title(title)
-        pyplot.subplot(2, 3, n + 4)
-        im2 = pyplot.imshow(
+            ax.imshow(badImage, alpha=0.2, interpolation="nearest", origin="lower")
+        ax.axis("off")
+        ax.set_title(title)
+        ax = fig.add_subplot(2, 3, n + 4)
+        im2 = ax.imshow(
             image, cmap=pyplot.cm.gray, interpolation="nearest", origin="lower", vmin=vmin2, vmax=vmax2
         )
         if bad is not None:
-            pyplot.imshow(badImage, alpha=0.2, interpolation="nearest", origin="lower")
-        pyplot.axis("off")
-        pyplot.title(title)
-    pyplot.subplots_adjust(left=0.05, bottom=0.05, top=0.92, right=0.75, wspace=0.05, hspace=0.05)
-    cax1 = pyplot.axes([0.8, 0.55, 0.05, 0.4])
-    pyplot.colorbar(im1, cax=cax1)
-    cax2 = pyplot.axes([0.8, 0.05, 0.05, 0.4])
-    pyplot.colorbar(im2, cax=cax2)
+            ax.imshow(badImage, alpha=0.2, interpolation="nearest", origin="lower")
+        ax.axis("off")
+        ax.set_title(title)
+    fig.subplots_adjust(left=0.05, bottom=0.05, top=0.92, right=0.75, wspace=0.05, hspace=0.05)
+    cax1 = fig.add_subplot([0.8, 0.55, 0.05, 0.4])
+    fig.colorbar(im1, cax=cax1)
+    cax2 = fig.add_subplot([0.8, 0.05, 0.05, 0.4])
+    fig.colorbar(im2, cax=cax2)
     if plotFileName:
-        pyplot.savefig(plotFileName)
+        fig.savefig(plotFileName)
     else:
         pyplot.show()
 
@@ -812,6 +858,8 @@ def assertFloatsNotEqual(
     rhs : scalar or array-like
         RHS value(s) to compare; may be a scalar or array-like of any
         dimension.
+    **kwds : `~typing.Any`
+        Keyword parameters forwarded to `assertFloatsAlmostEqual`.
 
     Raises
     ------
@@ -844,6 +892,8 @@ def assertFloatsEqual(
     rhs : scalar or array-like
         RHS value(s) to compare; may be a scalar or array-like of any
         dimension.
+    **kwargs : `~typing.Any`
+        Keyword parameters forwarded to `assertFloatsAlmostEqual`.
 
     Raises
     ------
@@ -887,7 +937,7 @@ def _settingsIterator(settings: dict[str, Sequence[Any]]) -> Iterator[dict[str,
 
 
 def classParameters(**settings: Sequence[Any]) -> Callable:
-    """Class decorator for generating unit tests
+    """Class decorator for generating unit tests.
 
     This decorator generates classes with class variables according to the
     supplied ``settings``.
@@ -903,8 +953,7 @@ def classParameters(**settings: Sequence[Any]) -> Callable:
     ::
 
         @classParameters(foo=[1, 2], bar=[3, 4])
-        class MyTestCase(unittest.TestCase):
-            ...
+        class MyTestCase(unittest.TestCase): ...
 
     will generate two classes, as if you wrote::
 
@@ -913,6 +962,7 @@ def classParameters(**settings: Sequence[Any]) -> Callable:
             bar = 3
             ...
 
+
         class MyTestCase_2_4(unittest.TestCase):
             foo = 2
             bar = 4
@@ -949,8 +999,7 @@ def methodParameters(**settings: Sequence[Any]) -> Callable:
     .. code-block:: python
 
         @methodParameters(foo=[1, 2], bar=[3, 4])
-        def testSomething(self, foo, bar):
-            ...
+        def testSomething(self, foo, bar): ...
 
     will run:
 
@@ -965,7 +1014,7 @@ def methodParameters(**settings: Sequence[Any]) -> Callable:
         def wrapper(self: unittest.TestCase, *args: Any, **kwargs: Any) -> None:
             for params in _settingsIterator(settings):
                 kwargs.update(params)
-                with self.subTest(**params):
+                with self.subTest(**{k: repr(v) for k, v in params.items()}):
                     func(self, *args, **kwargs)
 
         return wrapper
@@ -974,7 +1023,7 @@ def methodParameters(**settings: Sequence[Any]) -> Callable:
 
 
 def _cartesianProduct(settings: Mapping[str, Sequence[Any]]) -> Mapping[str, Sequence[Any]]:
-    """Return the cartesian product of the settings
+    """Return the cartesian product of the settings.
 
     Parameters
     ----------
@@ -1007,7 +1056,7 @@ def _cartesianProduct(settings: Mapping[str, Sequence[Any]]) -> Mapping[str, Seq
 
 
 def classParametersProduct(**settings: Sequence[Any]) -> Callable:
-    """Class decorator for generating unit tests
+    """Class decorator for generating unit tests.
 
     This decorator generates classes with class variables according to the
     cartesian product of the supplied ``settings``.
@@ -1023,8 +1072,7 @@ def classParametersProduct(**settings: Sequence[Any]) -> Callable:
     .. code-block:: python
 
         @classParametersProduct(foo=[1, 2], bar=[3, 4])
-        class MyTestCase(unittest.TestCase):
-            ...
+        class MyTestCase(unittest.TestCase): ...
 
     will generate four classes, as if you wrote::
 
@@ -1035,16 +1083,19 @@ def classParametersProduct(**settings: Sequence[Any]) -> Callable:
             bar = 3
             ...
 
+
         class MyTestCase_1_4(unittest.TestCase):
             foo = 1
             bar = 4
             ...
 
+
         class MyTestCase_2_3(unittest.TestCase):
             foo = 2
             bar = 3
             ...
 
+
         class MyTestCase_2_4(unittest.TestCase):
             foo = 2
             bar = 4
@@ -1067,9 +1118,8 @@ def methodParametersProduct(**settings: Sequence[Any]) -> Callable:
     **settings : `dict` (`str`: iterable)
         The parameter combinations to test. Each should be an iterable.
 
-    Example
-    -------
-
+    Examples
+    --------
         @methodParametersProduct(foo=[1, 2], bar=["black", "white"])
         def testSomething(self, foo, bar):
             ...
@@ -1090,6 +1140,11 @@ def temporaryDirectory() -> Iterator[str]:
 
     The difference from `tempfile.TemporaryDirectory` is that this ignores
     errors when deleting a directory, which may happen with some filesystems.
+
+    Yields
+    ------
+    `str`
+        Name of the temporary directory.
     """
     tmpdir = tempfile.mkdtemp()
     yield tmpdir

lsst/utils/threads.py

@@ -13,7 +13,7 @@
 
 from __future__ import annotations
 
-__all__ = ["set_thread_envvars", "disable_implicit_threading"]
+__all__ = ["disable_implicit_threading", "set_thread_envvars"]
 
 import os