DM-31722: Migrate utility code from other packages

doc/changes/DM-29370.feature.rst

@@ -0,0 +1 @@
+Add option to ignore NaNs in ``lsst.utils.tests.assertFloatsAlmostEqual``.

doc/changes/DM-29701.api.rst

@@ -0,0 +1,2 @@
+``deprecate_pybind11`` now requires a ``version`` parameter.
+This matches the upstream requirement from ``deprecated.deprecated`` 

doc/changes/DM-31141.feature.rst

@@ -0,0 +1 @@
+Add test decorators to operate on cartesian product.

doc/changes/DM-31722.feature.rst

@@ -0,0 +1,8 @@
+* Several new packages added from ``pipe_base`` and ``daf_butler``:
+  * ``lsst.utils.timer``
+  * ``lsst.utils.classes``
+  * ``lsst.utils.introspection``
+  * ``lsst.utils.iteration``
+  * ``lsst.utils.logging``
+* Added ``lsst.utils.doImportType`` to import a python type from a string and guaranteeing it is not a module.
+* ``lsst.utils.get_caller_name`` is now deprecated in its current location and has been relocated to ``lsst.utils.introspection``.

doc/lsst.utils/CHANGES.rst

@@ -0,0 +1,20 @@
+lsst.utils v22.0 (2021-07-09)
+=============================
+
+Bug fix
+-------
+
+* Error reporting in `~lsst.utils.doImport` has been improved. [DM-27638]
+
+lsst.utils v21.0 (2020-12-08)
+=============================
+
+New Features
+------------
+
+* Added a temporary directory context manager `lsst.utils.tests.temporaryDirectory`. [DM-26774]
+
+API Change
+----------
+
+* Add an optional ``version`` parameter to `lsst.utils.deprecate_pybind11`. [DM-26285]

doc/lsst.utils/index.rst

@@ -36,3 +36,13 @@ Python API reference
 .. automodapi:: lsst.utils.tests
    :no-main-docstr:
    :no-inherited-members:
+.. automodapi:: lsst.utils.logging
+   :no-main-docstr:
+.. automodapi:: lsst.utils.iteration
+   :no-main-docstr:
+.. automodapi:: lsst.utils.classes
+   :no-main-docstr:
+.. automodapi:: lsst.utils.introspection
+   :no-main-docstr:
+.. automodapi:: lsst.utils.timer
+   :no-main-docstr:

python/lsst/utils/classes.py

@@ -0,0 +1,135 @@
+# This file is part of utils.
+#
+# Developed for the LSST Data Management System.
+# This product includes software developed by the LSST Project
+# (https://www.lsst.org).
+# See the COPYRIGHT file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# Use of this source code is governed by a 3-clause BSD-style
+# license that can be found in the LICENSE file.
+#
+
+"""Utilities to help with class creation.
+"""
+
+from __future__ import annotations
+
+__all__ = ["Singleton", "cached_getter", "immutable"]
+
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Type,
+    TypeVar,
+)
+import functools
+
+
+class Singleton(type):
+    """Metaclass to convert a class to a Singleton.
+
+    If this metaclass is used the constructor for the singleton class must
+    take no arguments. This is because a singleton class will only accept
+    the arguments the first time an instance is instantiated.
+    Therefore since you do not know if the constructor has been called yet it
+    is safer to always call it with no arguments and then call a method to
+    adjust state of the singleton.
+    """
+
+    _instances: Dict[Type, Any] = {}
+
+    # Signature is intentionally not substitutable for type.__call__ (no *args,
+    # **kwargs) to require classes that use this metaclass to have no
+    # constructor arguments.
+    def __call__(cls) -> Any:  # type: ignore
+        if cls not in cls._instances:
+            cls._instances[cls] = super(Singleton, cls).__call__()
+        return cls._instances[cls]
+
+
+_T = TypeVar("_T", bound="Type")
+
+
+def immutable(cls: _T) -> _T:
+    """Decorate a class to simulates a simple form of immutability.
+
+    A class decorated as `immutable` may only set each of its attributes once;
+    any attempts to set an already-set attribute will raise `AttributeError`.
+
+    Notes
+    -----
+    Subclasses of classes marked with ``@immutable`` are also immutable.
+
+    Because this behavior interferes with the default implementation for the
+    ``pickle`` modules, `immutable` provides implementations of
+    ``__getstate__`` and ``__setstate__`` that override this behavior.
+    Immutable classes can then implement pickle via ``__reduce__`` or
+    ``__getnewargs__``.
+
+    Following the example of Python's built-in immutable types, such as `str`
+    and `tuple`, the `immutable` decorator provides a ``__copy__``
+    implementation that just returns ``self``, because there is no reason to
+    actually copy an object if none of its shared owners can modify it.
+
+    Similarly, objects that are recursively (i.e. are themselves immutable and
+    have only recursively immutable attributes) should also reimplement
+    ``__deepcopy__`` to return ``self``.  This is not done by the decorator, as
+    it has no way of checking for recursive immutability.
+    """
+    def __setattr__(self: _T, name: str, value: Any) -> None:  # noqa: N807
+        if hasattr(self, name):
+            raise AttributeError(f"{cls.__name__} instances are immutable.")
+        object.__setattr__(self, name, value)
+    # mypy says the variable here has signature (str, Any) i.e. no "self";
+    # I think it's just confused by descriptor stuff.
+    cls.__setattr__ = __setattr__  # type: ignore
+
+    def __getstate__(self: _T) -> dict:  # noqa: N807
+        # Disable default state-setting when unpickled.
+        return {}
+    cls.__getstate__ = __getstate__
+
+    def __setstate__(self: _T, state: Any) -> None:  # noqa: N807
+        # Disable default state-setting when copied.
+        # Sadly what works for pickle doesn't work for copy.
+        assert not state
+    cls.__setstate__ = __setstate__
+
+    def __copy__(self: _T) -> _T:  # noqa: N807
+        return self
+    cls.__copy__ = __copy__
+    return cls
+
+
+_S = TypeVar("_S")
+_R = TypeVar("_R")
+
+
+def cached_getter(func: Callable[[_S], _R]) -> Callable[[_S], _R]:
+    """Decorate a method to caches the result.
+
+    Only works on methods that take only ``self``
+    as an argument, and returns the cached result on subsequent calls.
+
+    Notes
+    -----
+    This is intended primarily as a stopgap for Python 3.8's more sophisticated
+    ``functools.cached_property``, but it is also explicitly compatible with
+    the `immutable` decorator, which may not be true of ``cached_property``.
+
+    `cached_getter` guarantees that the cached value will be stored in
+    an attribute named ``_cached_{name-of-decorated-function}``.  Classes that
+    use `cached_getter` are responsible for guaranteeing that this name is not
+    otherwise used, and is included if ``__slots__`` is defined.
+    """
+    attribute = f"_cached_{func.__name__}"
+
+    @functools.wraps(func)
+    def inner(self: _S) -> _R:
+        if not hasattr(self, attribute):
+            object.__setattr__(self, attribute, func(self))
+        return getattr(self, attribute)
+
+    return inner

python/lsst/utils/doImport.py

@@ -9,7 +9,7 @@
 # Use of this source code is governed by a 3-clause BSD-style
 # license that can be found in the LICENSE file.
 
-__all__ = ("doImport",)
+__all__ = ("doImport", "doImportType")
 
 import importlib
 import types
@@ -81,3 +81,33 @@ def tryImport(module: str, fromlist: List[str],
             infileComponents.insert(0, moduleComponents.pop())
 
     raise ModuleNotFoundError(f"Unable to import {importable}")
+
+
+def doImportType(importable: str) -> Type:
+    """Import a python type given an importable string and return it.
+
+    Parameters
+    ----------
+    importable : `str`
+        String containing dot-separated path of a Python class,
+        or member function.
+
+    Returns
+    -------
+    type : `type`
+        Type object. Can not return a module.
+
+    Raises
+    ------
+    TypeError
+        ``importable`` is not a `str` or the imported type is a module.
+    ModuleNotFoundError
+        No module in the supplied import string could be found.
+    ImportError
+        ``importable`` is found but can not be imported or the requested
+        item could not be retrieved from the imported module.
+    """
+    imported = doImport(importable)
+    if isinstance(imported, types.ModuleType):
+        raise TypeError(f"Import of {importable} returned a module and not a type.")
+    return imported

python/lsst/utils/get_caller_name.py

@@ -11,9 +11,13 @@
 
 __all__ = ["get_caller_name"]
 
-import inspect
+from deprecated.sphinx import deprecated
+from .introspection import get_caller_name as caller_name
 
 
+@deprecated(reason="get_caller_name has moved to `lsst.utils.introspection.get_caller_name`."
+            " Will be removed in v26.",
+            version="v24", category=FutureWarning)
 def get_caller_name(skip: int = 2) -> str:
     """Get the name of the caller method.
 
@@ -32,28 +36,6 @@ def get_caller_name(skip: int = 2) -> str:
     name : `str`
         Name of the caller as a string in the form ``module.class.method``.
         An empty string is returned if ``skip`` exceeds the stack height.
-
-    Notes
-    -----
-    Adapted from from http://stackoverflow.com/a/9812105
-    by adding support to get the class from ``parentframe.f_locals['cls']``
     """
-    stack = inspect.stack()
-    start = 0 + skip
-    if len(stack) < start + 1:
-        return ''
-    parentframe = stack[start][0]
-
-    name = []
-    module = inspect.getmodule(parentframe)
-    if module:
-        name.append(module.__name__)
-    # add class name, if any
-    if 'self' in parentframe.f_locals:
-        name.append(type(parentframe.f_locals['self']).__name__)
-    elif 'cls' in parentframe.f_locals:
-        name.append(parentframe.f_locals['cls'].__name__)
-    codename = parentframe.f_code.co_name
-    if codename != '<module>':  # top level usually
-        name.append(codename)  # function or a method
-    return ".".join(name)
+    # Offset the stack level to account for redirect and deprecated wrapper.
+    return caller_name(stacklevel=skip + 2)