Inheritance diagram for lsst.pex.config.dictField.DictField:

Public Member Functions
	__init__ (self, doc, keytype=None, itemtype=None, default=None, optional=False, dictCheck=None, keyCheck=None, itemCheck=None, deprecated=None)

	validate (self, instance)

None	__set__ (self, Config instance, Mapping[KeyTypeVar, ItemTypeVar]\|None value, Any at=None, str label="assignment")

	toDict (self, instance)

Public Member Functions inherited from lsst.pex.config.config.Field
	__class_getitem__ (cls, tuple[type,...]\|type\|ForwardRef params)

	__init__ (self, doc, dtype=None, default=None, check=None, optional=False, deprecated=None)

	rename (self, instance)

	freeze (self, instance)

	save (self, outfile, instance)

Field[FieldTypeVar]	__get__ (self, None instance, Any owner=None, Any at=None, str label="default")

FieldTypeVar	__get__ (self, Config instance, Any owner=None, Any at=None, str label="default")

	__get__ (self, instance, owner=None, at=None, label="default")

None	__set__ (self, Config instance, FieldTypeVar\|None value, Any at=None, str label="assignment")

	__delete__ (self, instance, at=None, label="deletion")

Public Member Functions inherited from lsst.pex.config.dictField.Dict
	__init__ (self, Config config, DictField field, Mapping[KeyTypeVar, ItemTypeVar] value, *, list[StackFrame]\|None at, str label, bool setHistory=True)

ItemTypeVar	__getitem__ (self, KeyTypeVar k)

int	__len__ (self)

Iterator[KeyTypeVar]	__iter__ (self)

bool	__contains__ (self, Any k)

None	__setitem__ (self, KeyTypeVar k, ItemTypeVar x, Any at=None, str label="setitem", bool setHistory=True)

None	__delitem__ (self, KeyTypeVar k, Any at=None, str label="delitem", bool setHistory=True)

	__repr__ (self)

	__str__ (self)

	__setattr__ (self, attr, value, at=None, label="assignment")

	__reduce__ (self)

Public Attributes
	keytype = keytype

	itemtype = itemtype

	dictCheck = dictCheck

	keyCheck = keyCheck

	itemCheck = itemCheck

Public Attributes inherited from lsst.pex.config.config.Field
	dtype = dtype

	doc = doc

	deprecated = deprecated

	default = default

	check = check

	optional = optional

	source = source

Static Public Attributes
type	DictClass = Dict

Static Public Attributes inherited from lsst.pex.config.config.Field
dict	supportedTypes = {str, bool, float, int, complex}

Protected Member Functions
Dict[KeyTypeVar, ItemTypeVar]\|None	_copy_storage (self, Config old, Config new)

	_compare (self, instance1, instance2, shortcut, rtol, atol, output)

Protected Member Functions inherited from lsst.pex.config.config.Field
	_setup (self, doc, dtype, default, check, optional, source, deprecated)

	_validateValue (self, value)

	_collectImports (self, instance, imports)

Protected Member Functions inherited from lsst.pex.config.dictField.Dict
Config	_config (self)

Dict	_copy (self, Config config)

Static Protected Member Functions
Mapping[str, Any]	_parseTypingArgs (tuple[type,...]\|tuple[str,...] params, Mapping[str, Any] kwds)

Additional Inherited Members
Protected Attributes inherited from lsst.pex.config.dictField.Dict
	_field = field

	_config_ = weakref.ref(config)

dict	_dict = {}

Config	_history = self._config._history.setdefault(self._field.name, [])

	_config

Properties inherited from lsst.pex.config.dictField.Dict
	history = property(lambda x: x._history)

Detailed Description

A configuration field (`~lsst.pex.config.Field` subclass) that maps keys
and values.

The types of both items and keys are restricted to these builtin types:
`int`, `float`, `complex`, `bool`, and `str`). All keys share the same type
and all values share the same type. Keys can have a different type from
values.

Parameters
----------
doc : `str`
    A documentation string that describes the configuration field.
keytype : {`int`, `float`, `complex`, `bool`, `str`}, optional
    The type of the mapping keys. All keys must have this type. Optional
    if keytype and itemtype are supplied as typing arguments to the class.
itemtype : {`int`, `float`, `complex`, `bool`, `str`}, optional
    Type of the mapping values. Optional if keytype and itemtype are
    supplied as typing arguments to the class.
default : `dict`, optional
    The default mapping.
optional : `bool`, optional
    If `True`, the field doesn't need to have a set value.
dictCheck : `collections.abc.Callable`
    A function that validates the dictionary as a whole.
keyCheck : `collections.abc.Callable`
    A function that validates individual mapping keys.
itemCheck : `collections.abc.Callable`
    A function that validates individual mapping values.
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.

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

Examples
--------
This field maps has `str` keys and `int` values:

>>> from lsst.pex.config import Config, DictField
>>> class MyConfig(Config):
...     field = DictField(
...         doc="Example string-to-int mapping field.",
...         keytype=str,
...         itemtype=int,
...         default={},
...     )
>>> config = MyConfig()
>>> config.field["myKey"] = 42
>>> print(config.field)
{'myKey': 42}

Member Function Documentation

◆ _compare()

lsst.pex.config.dictField.DictField._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 : `collections.abc.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.config.Field.

Reimplemented in lsst.pex.config.configDictField.ConfigDictField.

◆ _copy_storage()

Dict[KeyTypeVar, ItemTypeVar] \| None lsst.pex.config.dictField.DictField._copy_storage	(		self,
		Config	old,
		Config	new )

protected

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.

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

◆ _parseTypingArgs()

Mapping[str, Any] lsst.pex.config.dictField.DictField._parseTypingArgs	(	tuple[type, ...] \| tuple[str, ...]	params,
		Mapping[str, Any]	kwds )

staticprotected

Parse type annotations into keyword constructor arguments.

This is a special private method that interprets type arguments (i.e.
Field[str]) into keyword arguments to be passed on to the constructor.

Subclasses of Field can implement this method to customize how they
handle turning type parameters into keyword arguments (see DictField
for an example)

Parameters
----------
params : `tuple` of `type` or `tuple` of str
    Parameters passed to the type annotation. These will either be
    types or strings. Strings are to interpreted as forward references
    and will be treated as such.
kwds : `MutableMapping` with keys of `str` and values of `Any`
    These are the user supplied keywords that are to be passed to the
    Field constructor.

Returns
-------
kwds : `MutableMapping` with keys of `str` and values of `Any`
    The mapping of keywords that will be passed onto the constructor
    of the Field. Should be filled in with any information gleaned
    from the input parameters.

Raises
------
ValueError
    Raised if params is of incorrect length.
    Raised if a forward reference could not be resolved
    Raised if there is a conflict between params and values in kwds

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

◆ toDict()

lsst.pex.config.dictField.DictField.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.config.Field.

Reimplemented in lsst.pex.config.configDictField.ConfigDictField.

◆ validate()

lsst.pex.config.dictField.DictField.validate	(		self,
			instance )

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

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

Raises
------
lsst.pex.config.FieldValidationError
    Raised if validation fails for this field (see *Notes*).

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

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

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

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

Reimplemented in lsst.pex.config.configDictField.ConfigDictField.

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

python/lsst/pex/config/dictField.py

Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ _compare()

◆ _copy_storage()

◆ _parseTypingArgs()

◆ toDict()

◆ validate()