lsst.pex.config.configDictField.ConfigDictField Class Reference

Inheritance diagram for lsst.pex.config.configDictField.ConfigDictField:

Public Member Functions
	__init__ (self, doc, keytype, itemtype, default=None, optional=False, dictCheck=None, itemCheck=None, deprecated=None)
	rename (self, instance)
	validate (self, instance)
	toDict (self, instance)
	save (self, outfile, instance)
	freeze (self, instance)

Public Attributes
	keytype
	itemtype
	dictCheck
	itemCheck
	name

Static Public Attributes
	DictClass = ConfigDict

Protected Member Functions
	_collectImports (self, instance, imports)
	_compare (self, instance1, instance2, shortcut, rtol, atol, output)

Detailed Description

A configuration field (`~lsst.pex.config.Field` subclass) that is a
mapping of keys to `~lsst.pex.config.Config` instances.

``ConfigDictField`` behaves like `DictField` except that the
``itemtype`` must be a `~lsst.pex.config.Config` subclass.

Parameters
----------
doc : `str`
    A description of the configuration field.
keytype : {`int`, `float`, `complex`, `bool`, `str`}
    The type of the mapping keys. All keys must have this type.
itemtype : `lsst.pex.config.Config`-type
    The type of the values in the mapping. This must be
    `~lsst.pex.config.Config` or a subclass.
default : optional
    Unknown.
default : ``itemtype``-dtype, optional
    Default value of this field.
optional : `bool`, optional
    If `True`, this configuration `~lsst.pex.config.Field` is *optional*.
    Default is `True`.
dictCheck : `~collections.abc.Callable` or `None`, optional
    Callable to check a dict.
itemCheck : `~collections.abc.Callable` or `None`, optional
    Callable to check an item.
deprecated : None or `str`, optional
    A description of why this Field is deprecated, including removal date.
    If not None, the string is appended to the docstring for this Field.

Raises
------
ValueError
    Raised if the inputs are invalid:

    - ``keytype`` or ``itemtype`` arguments are not supported types
      (members of `ConfigDictField.supportedTypes`.
    - ``dictCheck`` or ``itemCheck`` is not a callable function.

See Also
--------
ChoiceField
ConfigChoiceField
ConfigField
ConfigurableField
DictField
Field
ListField
RangeField
RegistryField

Notes
-----
You can use ``ConfigDictField`` to create name-to-config mappings. One use
case is for configuring mappings for dataset types in a Butler. In this
case, the dataset type names are arbitrary and user-selected while the
mapping configurations are known and fixed.

Definition at line 109 of file configDictField.py.

Constructor & Destructor Documentation

__init__()

lsst.pex.config.configDictField.ConfigDictField.__init__	(		self,
			doc,
			keytype,
			itemtype,
			default = None,
			optional = False,
			dictCheck = None,
			itemCheck = None,
			deprecated = None )

Reimplemented from lsst.pex.config.dictField.DictField.

Definition at line 171 of file configDictField.py.

    ):
        source = getStackFrame()
        self._setup(
            doc=doc,
            dtype=ConfigDict,
            default=default,
            check=None,
            optional=optional,
            source=source,
            deprecated=deprecated,
        )
        if keytype not in self.supportedTypes:
            raise ValueError("'keytype' %s is not a supported type" % _typeStr(keytype))
        elif not issubclass(itemtype, Config):
            raise ValueError("'itemtype' %s is not a supported type" % _typeStr(itemtype))
        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")
 
        self.keytype = keytype
        self.itemtype = itemtype
        self.dictCheck = dictCheck
        self.itemCheck = itemCheck
 

Member Function Documentation

_collectImports()

lsst.pex.config.configDictField.ConfigDictField._collectImports ( self, instance, imports )

protected

Call the _collectImports method on all config
objects the field may own, and union them with the supplied imports
set.

Parameters
----------
instance : instance or subclass of `lsst.pex.config.Config`
    A config object that has this field defined on it
imports : `set`
    Set of python modules that need imported after persistence

Reimplemented from lsst.pex.config.config.Field.

Definition at line 235 of file configDictField.py.

    def _collectImports(self, instance, imports):
        # docstring inherited from Field
        configDict = self.__get__(instance)
        if configDict is not None:
            for v in configDict.values():
                v._collectImports()
                imports |= v._imports
 

_compare()

lsst.pex.config.configDictField.ConfigDictField._compare ( self, instance1, instance2, shortcut, rtol, atol, output )

protected

Compare two fields for equality.

Used by `lsst.pex.ConfigDictField.compare`.

Parameters
----------
instance1 : `lsst.pex.config.Config`
    Left-hand side config instance to compare.
instance2 : `lsst.pex.config.Config`
    Right-hand side config instance to compare.
shortcut : `bool`
    If `True`, this function returns as soon as an inequality if found.
rtol : `float`
    Relative tolerance for floating point comparisons.
atol : `float`
    Absolute tolerance for floating point comparisons.
output : callable
    A callable that takes a string, used (possibly repeatedly) to
    report inequalities.

Returns
-------
isEqual : bool
    `True` if the fields are equal, `False` otherwise.

Notes
-----
Floating point comparisons are performed by `numpy.allclose`.

Reimplemented from lsst.pex.config.dictField.DictField.

Definition at line 261 of file configDictField.py.

    def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
        """Compare two fields for equality.
 
        Used by `lsst.pex.ConfigDictField.compare`.
 
        Parameters
        ----------
        instance1 : `lsst.pex.config.Config`
            Left-hand side config instance to compare.
        instance2 : `lsst.pex.config.Config`
            Right-hand side config instance to compare.
        shortcut : `bool`
            If `True`, this function returns as soon as an inequality if found.
        rtol : `float`
            Relative tolerance for floating point comparisons.
        atol : `float`
            Absolute tolerance for floating point comparisons.
        output : callable
            A callable that takes a string, used (possibly repeatedly) to
            report inequalities.
 
        Returns
        -------
        isEqual : bool
            `True` if the fields are equal, `False` otherwise.
 
        Notes
        -----
        Floating point comparisons are performed by `numpy.allclose`.
        """
        d1 = getattr(instance1, self.name)
        d2 = getattr(instance2, self.name)
        name = getComparisonName(
            _joinNamePath(instance1._name, self.name), _joinNamePath(instance2._name, self.name)
        )
        if not compareScalars("keys for %s" % name, set(d1.keys()), set(d2.keys()), output=output):
            return False
        equal = True
        for k, v1 in d1.items():
            v2 = d2[k]
            result = compareConfigs(
                f"{name}[{k!r}]", v1, v2, shortcut=shortcut, rtol=rtol, atol=atol, output=output
            )
            if not result and shortcut:
                return False
            equal = equal and result
        return equal

freeze()

lsst.pex.config.configDictField.ConfigDictField.freeze	(		self,
			instance )

Make this field read-only (for internal use only).

Parameters
----------
instance : `lsst.pex.config.Config`
    The config instance that contains this field.

Notes
-----
Freezing is only relevant for fields that hold subconfigs. Fields which
hold subconfigs should freeze each subconfig.

**Subclasses should implement this method.**

Reimplemented from lsst.pex.config.config.Field.

Definition at line 255 of file configDictField.py.

    def freeze(self, instance):
        configDict = self.__get__(instance)
        if configDict is not None:
            for k in configDict:
                configDict[k].freeze()
 

rename()

lsst.pex.config.configDictField.ConfigDictField.rename	(		self,
			instance )

Rename the field in a `~lsst.pex.config.Config` (for internal use
only).

Parameters
----------
instance : `lsst.pex.config.Config`
    The config instance that contains this field.

Notes
-----
This method is invoked by the `lsst.pex.config.Config` object that
contains this field and should not be called directly.

Renaming is only relevant for `~lsst.pex.config.Field` instances that
hold subconfigs. `~lsst.pex.config.Field`\s that hold subconfigs should
rename each subconfig with the full field name as generated by
`lsst.pex.config.config._joinNamePath`.

Reimplemented from lsst.pex.config.config.Field.

Definition at line 206 of file configDictField.py.

    def rename(self, instance):
        configDict = self.__get__(instance)
        if configDict is not None:
            for k in configDict:
                fullname = _joinNamePath(instance._name, self.name, k)
                configDict[k]._rename(fullname)
 

save()

lsst.pex.config.configDictField.ConfigDictField.save	(		self,
			outfile,
			instance )

Save this field to a file (for internal use only).

Parameters
----------
outfile : file-like object
    A writeable field handle.
instance : `~lsst.pex.config.Config`
    The `~lsst.pex.config.Config` instance that contains this field.

Notes
-----
This method is invoked by the `~lsst.pex.config.Config` object that
contains this field and should not be called directly.

The output consists of the documentation string
(`lsst.pex.config.Field.doc`) formatted as a Python comment. The second
line is formatted as an assignment: ``{fullname}={value}``.

This output can be executed with Python.

Reimplemented from lsst.pex.config.config.Field.

Definition at line 243 of file configDictField.py.

    def save(self, outfile, instance):
        configDict = self.__get__(instance)
        fullname = _joinNamePath(instance._name, self.name)
        if configDict is None:
            outfile.write(f"{fullname}={configDict!r}\n")
            return
 
        outfile.write(f"{fullname}={{}}\n")
        for v in configDict.values():
            outfile.write(f"{v._name}={_typeStr(v)}()\n")
            v._save(outfile)
 

toDict()

lsst.pex.config.configDictField.ConfigDictField.toDict	(		self,
			instance )

Convert this field's key-value pairs into a regular `dict`.

Parameters
----------
instance : `lsst.pex.config.Config`
    The configuration that contains this field.

Returns
-------
result : `dict` or `None`
    If this field has a value of `None`, then this method returns
    `None`. Otherwise, this method returns the field's value as a
    regular Python `dict`.

Reimplemented from lsst.pex.config.dictField.DictField.

Definition at line 224 of file configDictField.py.

    def toDict(self, instance):
        configDict = self.__get__(instance)
        if configDict is None:
            return None
 
        dict_ = {}
        for k in configDict:
            dict_[k] = configDict[k].toDict()
 
        return dict_
 

validate()

lsst.pex.config.configDictField.ConfigDictField.validate	(		self,
			instance )

Validate the field's value (for internal use only).

Parameters
----------
instance : `lsst.pex.config.Config`
    The configuration that contains this field.

Returns
-------
isValid : `bool`
    `True` is returned if the field passes validation criteria (see
    *Notes*). Otherwise `False`.

Notes
-----
This method validates values according to the following criteria:

- A non-optional field is not `None`.
- If a value is not `None`, is must pass the `ConfigField.dictCheck`
  user callback functon.

Individual item checks by the `ConfigField.itemCheck` user callback
function are done immediately when the value is set on a key. Those
checks are not repeated by this method.

Reimplemented from lsst.pex.config.dictField.DictField.

Definition at line 213 of file configDictField.py.

    def validate(self, instance):
        value = self.__get__(instance)
        if value is not None:
            for k in value:
                item = value[k]
                item.validate()
                if self.itemCheck is not None and not self.itemCheck(item):
                    msg = f"Item at key {k!r} is not a valid value: {item}"
                    raise FieldValidationError(self, instance, msg)
        DictField.validate(self, instance)
 

Member Data Documentation

dictCheck

lsst.pex.config.configDictField.ConfigDictField.dictCheck

Definition at line 203 of file configDictField.py.

DictClass

lsst.pex.config.configDictField.ConfigDictField.DictClass = ConfigDict

static

Definition at line 169 of file configDictField.py.

itemCheck

lsst.pex.config.configDictField.ConfigDictField.itemCheck

Definition at line 204 of file configDictField.py.

itemtype

lsst.pex.config.configDictField.ConfigDictField.itemtype

Definition at line 202 of file configDictField.py.

keytype

lsst.pex.config.configDictField.ConfigDictField.keytype

Definition at line 201 of file configDictField.py.

name

lsst.pex.config.configDictField.ConfigDictField.name

Definition at line 294 of file configDictField.py.

---

The documentation for this class was generated from the following file:

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-8.0.0/Linux64/pex_config/gba4ed39666+c2a2e4ac27/python/lsst/pex/config/configDictField.py