lsst-pex-config 27.2024.3500__py3-none-any.whl → 29.2025.4900__py3-none-any.whl

lsst/pex/config/callStack.py

@@ -25,7 +25,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-__all__ = ["getCallerFrame", "getStackFrame", "StackFrame", "getCallStack"]
+__all__ = ["StackFrame", "getCallStack", "getCallerFrame", "getStackFrame"]
 
 import inspect
 import linecache
@@ -50,7 +50,7 @@ def getCallerFrame(relative=0):
     This function is excluded from the frame.
     """
     frame = inspect.currentframe().f_back.f_back  # Our caller's caller
-    for ii in range(relative):
+    for _ in range(relative):
         frame = frame.f_back
     return frame
 

lsst/pex/config/comparison.py

@@ -32,7 +32,7 @@ or `lsst.pex.config.Field._compare` implementation, as they take care of
 writing messages as well as floating-point comparisons and shortcuts.
 """
 
-__all__ = ("getComparisonName", "compareScalars", "compareConfigs")
+__all__ = ("compareConfigs", "compareScalars", "getComparisonName")
 
 import numpy
 
@@ -68,7 +68,8 @@ def compareScalars(name, v1, v2, output, rtol=1e-8, atol=1e-8, dtype=None):
     ----------
     name : `str`
         Name to use when reporting differences, typically created by
-        `getComparisonName`.
+        `getComparisonName`.  This will always appear as the beginning of any
+        messages reported via ``output``.
     v1 : object
         Left-hand side value to compare.
     v2 : object
@@ -104,7 +105,7 @@ def compareScalars(name, v1, v2, output, rtol=1e-8, atol=1e-8, dtype=None):
     else:
         result = v1 == v2
     if not result and output is not None:
-        output(f"Inequality in {name}: {v1!r} != {v2!r}")
+        output(f"{name}: {v1!r} != {v2!r}")
     return result
 
 
@@ -117,7 +118,8 @@ def compareConfigs(name, c1, c2, shortcut=True, rtol=1e-8, atol=1e-8, output=Non
     ----------
     name : `str`
         Name to use when reporting differences, typically created by
-        `getComparisonName`.
+        `getComparisonName`.  This will always appear as the beginning of any
+        messages reported via ``output``.
     c1 : `lsst.pex.config.Config`
         Left-hand side config to compare.
     c2 : `lsst.pex.config.Config`
@@ -150,22 +152,24 @@ def compareConfigs(name, c1, c2, shortcut=True, rtol=1e-8, atol=1e-8, output=Non
     `~lsst.pex.config.ConfigChoiceField` instances, *unselected*
     `~lsst.pex.config.Config` instances will not be compared.
     """
+    from .config import _typeStr
+
     assert name is not None
     if c1 is None:
         if c2 is None:
             return True
         else:
             if output is not None:
-                output(f"LHS is None for {name}")
+                output(f"{name}: None != {c2!r}.")
             return False
     else:
         if c2 is None:
             if output is not None:
-                output(f"RHS is None for {name}")
+                output(f"{name}: {c1!r} != None.")
             return False
     if type(c1) is not type(c2):
         if output is not None:
-            output(f"Config types do not match for {name}: {type(c1)} != {type(c2)}")
+            output(f"{name}: config types do not match; {_typeStr(c1)} != {_typeStr(c2)}.")
         return False
     equal = True
     for field in c1._fields.values():

lsst/pex/config/config.py

@@ -30,15 +30,16 @@ __all__ = (
     "Config",
     "ConfigMeta",
     "Field",
+    "FieldTypeVar",
     "FieldValidationError",
     "UnexpectedProxyUsageError",
-    "FieldTypeVar",
 )
 
 import copy
 import importlib
 import io
 import math
+import numbers
 import os
 import re
 import shutil
@@ -134,9 +135,15 @@ def _autocast(x, dtype):
         If appropriate, the returned value is ``x`` cast to the given type
         ``dtype``. If the cast cannot be performed the original value of
         ``x`` is returned.
+
+    Notes
+    -----
+    Will convert numpy scalar types to the standard Python equivalents.
     """
-    if dtype is float and isinstance(x, int):
+    if dtype is float and isinstance(x, numbers.Real):
         return float(x)
+    if dtype is int and isinstance(x, numbers.Integral):
+        return int(x)
     return x
 
 
@@ -383,7 +390,6 @@ class Field(Generic[FieldTypeVar]):
     >>> class Example(Config):
     ...     myInt = Field("An integer field.", int, default=0)
     ...     name = Field[str](doc="A string Field")
-    ...
     >>> print(config.myInt)
     0
     >>> config.myInt = 5
@@ -694,6 +700,14 @@ class Field(Generic[FieldTypeVar]):
         """
         return self.__get__(instance)
 
+    def _copy_storage(self, old: Config, new: Config) -> Any:
+        """Copy the storage for this field in the given field into an object
+        suitable for storage in a new copy of that config.
+
+        Any frozen storage should be unfrozen.
+        """
+        return copy.deepcopy(old._storage[self.name])
+
     @overload
     def __get__(
         self, instance: None, owner: Any = None, at: Any = None, label: str = "default"
@@ -729,7 +743,7 @@ class Field(Generic[FieldTypeVar]):
                 else:
                     raise AttributeError(
                         f"Config {instance} is missing _storage attribute, likely incorrectly initialized"
-                    )
+                    ) from None
 
     def __set__(
         self, instance: Config, value: FieldTypeVar | None, at: Any = None, label: str = "assignment"
@@ -784,7 +798,7 @@ class Field(Generic[FieldTypeVar]):
             try:
                 self._validateValue(value)
             except BaseException as e:
-                raise FieldValidationError(self, instance, str(e))
+                raise FieldValidationError(self, instance, str(e)) from e
 
         instance._storage[self.name] = value
         if at is None:
@@ -936,23 +950,25 @@ class Config(metaclass=ConfigMeta):  # type: ignore
     >>> from lsst.pex.config import Config, Field, ListField
     >>> class DemoConfig(Config):
     ...     intField = Field(doc="An integer field", dtype=int, default=42)
-    ...     listField = ListField(doc="List of favorite beverages.", dtype=str,
-    ...                           default=['coffee', 'green tea', 'water'])
-    ...
+    ...     listField = ListField(
+    ...         doc="List of favorite beverages.",
+    ...         dtype=str,
+    ...         default=["coffee", "green tea", "water"],
+    ...     )
     >>> config = DemoConfig()
 
     Configs support many `dict`-like APIs:
 
     >>> config.keys()
     ['intField', 'listField']
-    >>> 'intField' in config
+    >>> "intField" in config
     True
 
     Individual fields can be accessed as attributes of the configuration:
 
     >>> config.intField
     42
-    >>> config.listField.append('earl grey tea')
+    >>> config.listField.append("earl grey tea")
     >>> print(config.listField)
     ['coffee', 'green tea', 'water', 'earl grey tea']
     """
@@ -1047,6 +1063,30 @@ class Config(metaclass=ConfigMeta):  # type: ignore
         instance.update(__at=at, **kw)
         return instance
 
+    def copy(self) -> Config:
+        """Return a deep copy of this config.
+
+        Notes
+        -----
+        The returned config object is not frozen, even if the original was.
+        If a nested config object is copied, it retains the name from its
+        original hierarchy.
+
+        Nested objects are only shared between the new and old configs if they
+        are not possible to modify via the config's interfaces (e.g. entries
+        in the the history list are not copied, but the lists themselves are,
+        so modifications to one copy do not modify the other).
+        """
+        instance = object.__new__(type(self))
+        instance._frozen = False
+        instance._name = self._name
+        instance._history = {k: list(v) for k, v in self._history.items()}
+        instance._imports = set(self._imports)
+        # Important to set up storage last, since fields sometimes store
+        # proxy objects that reference their parent (especially for history).
+        instance._storage = {k: self._fields[k]._copy_storage(self, instance) for k in self._storage}
+        return instance
+
     def __reduce__(self):
         """Reduction for pickling (function with arguments to reproduce).
 
@@ -1095,30 +1135,27 @@ class Config(metaclass=ConfigMeta):  # type: ignore
 
         >>> from lsst.pex.config import Config, Field
         >>> class DemoConfig(Config):
-        ...     fieldA = Field(doc='Field A', dtype=int, default=42)
-        ...     fieldB = Field(doc='Field B', dtype=bool, default=True)
-        ...     fieldC = Field(doc='Field C', dtype=str, default='Hello world')
-        ...
+        ...     fieldA = Field(doc="Field A", dtype=int, default=42)
+        ...     fieldB = Field(doc="Field B", dtype=bool, default=True)
+        ...     fieldC = Field(doc="Field C", dtype=str, default="Hello world")
         >>> config = DemoConfig()
 
         These are the default values of each field:
 
         >>> for name, value in config.iteritems():
         ...     print(f"{name}: {value}")
-        ...
         fieldA: 42
         fieldB: True
         fieldC: 'Hello world'
 
         Using this method to update ``fieldA`` and ``fieldC``:
 
-        >>> config.update(fieldA=13, fieldC='Updated!')
+        >>> config.update(fieldA=13, fieldC="Updated!")
 
         Now the values of each field are:
 
         >>> for name, value in config.iteritems():
         ...     print(f"{name}: {value}")
-        ...
         fieldA: 13
         fieldB: True
         fieldC: 'Updated!'
@@ -1130,8 +1167,9 @@ class Config(metaclass=ConfigMeta):  # type: ignore
             try:
                 field = self._fields[name]
                 field.__set__(self, value, at=at, label=label)
-            except KeyError:
-                raise KeyError(f"No field of name {name} exists in config type {_typeStr(self)}")
+            except KeyError as e:
+                e.add_note(f"No field of name {name} exists in config type {_typeStr(self)}")
+                raise
 
     def load(self, filename, root="config"):
         """Modify this config in place by executing the Python code in a
@@ -1408,7 +1446,7 @@ class Config(metaclass=ConfigMeta):  # type: ignore
         class.
         """
         self._imports.add(self.__module__)
-        for name, field in self._fields.items():
+        for field in self._fields.values():
             field._collectImports(self, self._imports)
 
     def toDict(self):

lsst/pex/config/configChoiceField.py

@@ -30,7 +30,6 @@ __all__ = ["ConfigChoiceField"]
 
 import collections.abc
 import copy
-import weakref
 from typing import Any, ForwardRef, overload
 
 from .callStack import getCallStack, getStackFrame
@@ -63,35 +62,34 @@ class SelectionSet(collections.abc.MutableSet):
     history.
     """
 
-    def __init__(self, dict_, value, at=None, label="assignment", setHistory=True):
+    def __init__(
+        self,
+        dict_: ConfigInstanceDict,
+        value: Any,
+        at=None,
+        label: str = "assignment",
+        setHistory: bool = True,
+    ):
         if at is None:
             at = getCallStack()
         self._dict = dict_
         self._field = self._dict._field
-        self._config_ = weakref.ref(self._dict._config)
-        self.__history = self._config._history.setdefault(self._field.name, [])
+        self._history = self._dict._config._history.setdefault(self._field.name, [])
         if value is not None:
             try:
                 for v in value:
                     if v not in self._dict:
                         # invoke __getitem__ to ensure it's present
                         self._dict.__getitem__(v, at=at)
-            except TypeError:
+            except TypeError as e:
                 msg = f"Value {value} is of incorrect type {_typeStr(value)}. Sequence type expected"
-                raise FieldValidationError(self._field, self._config, msg)
+                raise FieldValidationError(self._field, self._dict._config, msg) from e
             self._set = set(value)
         else:
             self._set = set()
 
         if setHistory:
-            self.__history.append((f"Set selection to {self}", at, label))
-
-    @property
-    def _config(self) -> Config:
-        # Config Fields should never outlive their config class instance
-        # assert that as such here
-        assert self._config_() is not None
-        return self._config_()
+            self._history.append((f"Set selection to {self}", at, label))
 
     def add(self, value, at=None):
         """Add a value to the selected set.
@@ -104,7 +102,7 @@ class SelectionSet(collections.abc.MutableSet):
                 optional
             Stack frames for history recording.
         """
-        if self._config._frozen:
+        if self._dict._config._frozen:
             raise FieldValidationError(self._field, self._config, "Cannot modify a frozen Config")
 
         if at is None:
@@ -114,7 +112,7 @@ class SelectionSet(collections.abc.MutableSet):
             # invoke __getitem__ to make sure it's present
             self._dict.__getitem__(value, at=at)
 
-        self.__history.append((f"added {value} to selection", at, "selection"))
+        self._history.append((f"added {value} to selection", at, "selection"))
         self._set.add(value)
 
     def discard(self, value, at=None):
@@ -128,8 +126,8 @@ class SelectionSet(collections.abc.MutableSet):
                 optional
             Stack frames for history recording.
         """
-        if self._config._frozen:
-            raise FieldValidationError(self._field, self._config, "Cannot modify a frozen Config")
+        if self._dict._config._frozen:
+            raise FieldValidationError(self._field, self._dict._config, "Cannot modify a frozen Config")
 
         if value not in self._dict:
             return
@@ -137,7 +135,7 @@ class SelectionSet(collections.abc.MutableSet):
         if at is None:
             at = getCallStack()
 
-        self.__history.append((f"removed {value} from selection", at, "selection"))
+        self._history.append((f"removed {value} from selection", at, "selection"))
         self._set.discard(value)
 
     def __len__(self):
@@ -177,9 +175,9 @@ class ConfigInstanceDict(collections.abc.Mapping[str, Config]):
         (that is, ``typemap[name]``).
     """
 
-    def __init__(self, config, field):
+    def __init__(self, config: Config, field: ConfigChoiceField):
         collections.abc.Mapping.__init__(self)
-        self._dict = {}
+        self._dict: dict[str, Config] = {}
         self._selection = None
         self._config = config
         self._field = field
@@ -187,6 +185,18 @@ class ConfigInstanceDict(collections.abc.Mapping[str, Config]):
         self.__doc__ = field.doc
         self._typemap = None
 
+    def _copy(self, config: Config) -> ConfigInstanceDict:
+        result = type(self)(config, self._field)
+        result._dict = {k: v.copy() for k, v in self._dict.items()}
+        result._history.extend(self._history)
+        result._typemap = self._typemap
+        if self._selection is not None:
+            if self._field.multi:
+                result._selection = SelectionSet(result._dict, self._selection._set)
+            else:
+                result._selection = self._selection
+        return result
+
     @property
     def types(self):
         return self._typemap if self._typemap is not None else self._field.typemap
@@ -293,10 +303,10 @@ class ConfigInstanceDict(collections.abc.Mapping[str, Config]):
         except KeyError:
             try:
                 dtype = self.types[k]
-            except Exception:
+            except Exception as e:
                 raise FieldValidationError(
                     self._field, self._config, f"Unknown key {k!r} in Registry/ConfigChoiceField"
-                )
+                ) from e
             name = _joinNamePath(self._config._name, self._field.name, k)
             if at is None:
                 at = getCallStack()
@@ -310,8 +320,8 @@ class ConfigInstanceDict(collections.abc.Mapping[str, Config]):
 
         try:
             dtype = self.types[k]
-        except Exception:
-            raise FieldValidationError(self._field, self._config, f"Unknown key {k!r}")
+        except Exception as e:
+            raise FieldValidationError(self._field, self._config, f"Unknown key {k!r}") from e
 
         if value != dtype and type(value) is not dtype:
             msg = (
@@ -443,7 +453,6 @@ class ConfigChoiceField(Field[ConfigInstanceDict]):
     >>> from lsst.pex.config import Config, ConfigChoiceField, Field
     >>> class AaaConfig(Config):
     ...     somefield = Field("doc", int)
-    ...
 
     The ``MyConfig`` config has a ``ConfigChoiceField`` field called ``choice``
     that maps the ``AaaConfig`` type to the ``"AAA"`` key:
@@ -451,7 +460,6 @@ class ConfigChoiceField(Field[ConfigInstanceDict]):
     >>> TYPEMAP = {"AAA", AaaConfig}
     >>> class MyConfig(Config):
     ...     choice = ConfigChoiceField("doc for choice", TYPEMAP)
-    ...
 
     Creating an instance of ``MyConfig``:
 
@@ -460,7 +468,7 @@ class ConfigChoiceField(Field[ConfigInstanceDict]):
     Setting value of the field ``somefield`` on the "AAA" key of the ``choice``
     field:
 
-    >>> instance.choice['AAA'].somefield = 5
+    >>> instance.choice["AAA"].somefield = 5
 
     **Selecting the active configuration**
 
@@ -546,6 +554,13 @@ class ConfigChoiceField(Field[ConfigInstanceDict]):
         else:
             instanceDict._setSelection(value, at=at, label=label)
 
+    def _copy_storage(self, old: Config, new: Config) -> Any:
+        instance_dict: ConfigInstanceDict | None = old._storage.get(self.name)
+        if instance_dict is not None:
+            return instance_dict._copy(new)
+        else:
+            return None
+
     def rename(self, instance):
         instanceDict = self.__get__(instance)
         fullname = _joinNamePath(instance._name, self.name)

lsst/pex/config/configDictField.py

@@ -24,10 +24,13 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+from __future__ import annotations
 
 __all__ = ["ConfigDictField"]
 
-from .callStack import getCallStack, getStackFrame
+from collections.abc import Mapping
+
+from .callStack import StackFrame, getCallStack, getStackFrame
 from .comparison import compareConfigs, compareScalars, getComparisonName
 from .config import Config, FieldValidationError, _autocast, _joinNamePath, _typeStr
 from .dictField import Dict, DictField
@@ -51,11 +54,33 @@ class ConfigDict(Dict[str, Config]):
         Stack frame for history recording. Will be calculated if `None`.
     label : `str`, optional
         Label to use for history recording.
+    setHistory : `bool`, optional
+        Whether to append to the history record.
     """
 
-    def __init__(self, config, field, value, at, label):
-        Dict.__init__(self, config, field, value, at, label, setHistory=False)
-        self.history.append(("Dict initialized", at, label))
+    def __init__(
+        self,
+        config: Config,
+        field: ConfigDictField,
+        value: Mapping[str, Config] | None,
+        *,
+        at: list[StackFrame] | None,
+        label: str,
+        setHistory: bool = True,
+    ):
+        Dict.__init__(self, config, field, value, at=at, label=label, setHistory=False)
+        if setHistory:
+            self.history.append(("Dict initialized", at, label))
+
+    def _copy(self, config: Config) -> Dict:
+        return type(self)(
+            config,
+            self._field,
+            {k: v._copy() for k, v in self._dict.items()},
+            at=None,
+            label="copy",
+            setHistory=False,
+        )
 
     def __setitem__(self, k, x, at=None, label="setitem", setHistory=True):
         if self._config._frozen:
@@ -77,6 +102,11 @@ class ConfigDict(Dict[str, Config]):
             )
             raise FieldValidationError(self._field, self._config, msg)
 
+        # validate key using keycheck
+        if self._field.keyCheck is not None and not self._field.keyCheck(k):
+            msg = f"Key {k!r} is not a valid key"
+            raise FieldValidationError(self._field, self._config, msg)
+
         if at is None:
             at = getCallStack()
         name = _joinNamePath(self._config._name, self._field.name, k)
@@ -127,6 +157,8 @@ class ConfigDictField(DictField):
         Default is `True`.
     dictCheck : `~collections.abc.Callable` or `None`, optional
         Callable to check a dict.
+    keyCheck : `~collections.abc.Callable` or `None`, optional
+        Callable to check a key.
     itemCheck : `~collections.abc.Callable` or `None`, optional
         Callable to check an item.
     deprecated : None or `str`, optional
@@ -140,7 +172,8 @@ class ConfigDictField(DictField):
 
         - ``keytype`` or ``itemtype`` arguments are not supported types
           (members of `ConfigDictField.supportedTypes`.
-        - ``dictCheck`` or ``itemCheck`` is not a callable function.
+        - ``dictCheck``, ``keyCheck`` or ``itemCheck`` is not a callable
+          function.
 
     See Also
     --------
@@ -172,6 +205,7 @@ class ConfigDictField(DictField):
         default=None,
         optional=False,
         dictCheck=None,
+        keyCheck=None,
         itemCheck=None,
         deprecated=None,
     ):
@@ -189,14 +223,18 @@ class ConfigDictField(DictField):
             raise ValueError(f"'keytype' {_typeStr(keytype)} is not a supported type")
         elif not issubclass(itemtype, Config):
             raise ValueError(f"'itemtype' {_typeStr(itemtype)} is not a supported type")
-        if dictCheck is not None and not hasattr(dictCheck, "__call__"):
-            raise ValueError("'dictCheck' must be callable")
-        if itemCheck is not None and not hasattr(itemCheck, "__call__"):
-            raise ValueError("'itemCheck' must be callable")
+
+        check_errors = []
+        for name, check in (("dictCheck", dictCheck), ("keyCheck", keyCheck), ("itemCheck", itemCheck)):
+            if check is not None and not callable(check):
+                check_errors.append(name)
+        if check_errors:
+            raise ValueError(f"{', '.join(check_errors)} must be callable")
 
         self.keytype = keytype
         self.itemtype = itemtype
         self.dictCheck = dictCheck
+        self.keyCheck = keyCheck
         self.itemCheck = itemCheck
 
     def rename(self, instance):
@@ -207,6 +245,23 @@ class ConfigDictField(DictField):
                 configDict[k]._rename(fullname)
 
     def validate(self, instance):
+        """Validate the field.
+
+        Parameters
+        ----------
+        instance : `lsst.pex.config.Config`
+            The config instance that contains this field.
+
+        Raises
+        ------
+        lsst.pex.config.FieldValidationError
+            Raised if validation fails for this field.
+
+        Notes
+        -----
+        Individual key checks (``keyCheck``) are applied when each key is added
+        and are not re-checked by this method.
+        """
         value = self.__get__(instance)
         if value is not None:
             for k in value:
@@ -289,7 +344,7 @@ class ConfigDictField(DictField):
         name = getComparisonName(
             _joinNamePath(instance1._name, self.name), _joinNamePath(instance2._name, self.name)
         )
-        if not compareScalars(f"keys for {name}", set(d1.keys()), set(d2.keys()), output=output):
+        if not compareScalars(f"{name} (keys)", set(d1.keys()), set(d2.keys()), output=output):
             return False
         equal = True
         for k, v1 in d1.items():

lsst/pex/config/configField.py

@@ -243,6 +243,13 @@ class ConfigField(Field[FieldTypeVar]):
         value = self.__get__(instance)
         return value.toDict()
 
+    def _copy_storage(self, old: Config, new: Config) -> Any:
+        value: Config | None = old._storage.get(self.name)
+        if value is not None:
+            return value.copy()
+        else:
+            return None
+
     def validate(self, instance):
         """Validate the field (for internal use only).
 

lsst/pex/config/configurableActions/_configurableAction.py

@@ -20,7 +20,7 @@
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 from __future__ import annotations
 
-__all__ = ["ConfigurableAction", "ActionTypeVar"]
+__all__ = ["ActionTypeVar", "ConfigurableAction"]
 
 from typing import Any, TypeVar
 
@@ -62,3 +62,8 @@ class ConfigurableAction(Config):
 
     def __call__(self, *args: Any, **kwargs: Any) -> Any:
         raise NotImplementedError("This method should be overloaded in subclasses")
+
+    def copy(self) -> ConfigurableAction:
+        result = super().copy()
+        result.identity = self.identity
+        return result