lsst.pex.config gba4ed39666+1ac82b564f
Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | List of all members
lsst.pex.config.dictField.DictField Class Reference
Inheritance diagram for lsst.pex.config.dictField.DictField:
lsst.pex.config.config.Field lsst.pex.config.dictField.Dict lsst.pex.config.configDictField.ConfigDictField

Public Member Functions

 __init__ (self, doc, keytype=None, itemtype=None, default=None, optional=False, dictCheck=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)
 
 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")
 
 __delete__ (self, instance, at=None, label="deletion")
 
- Public Member Functions inherited from lsst.pex.config.dictField.Dict
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
 
 itemtype
 
 dictCheck
 
 itemCheck
 
 name
 
- Public Attributes inherited from lsst.pex.config.config.Field
 dtype
 
 doc
 
 deprecated
 
 default
 
 check
 
 optional
 
 source
 
 name
 

Static Public Attributes

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

Protected Member Functions

 _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)
 

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
 
 _config_
 
 _dict
 
 _history
 
 _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 : callable
    A function that validates the dictionary as a whole.
itemCheck : 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}

Constructor & Destructor Documentation

◆ __init__()

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

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

Member Function Documentation

◆ __set__()

None lsst.pex.config.dictField.DictField.__set__ ( self,
Config instance,
Mapping[KeyTypeVar, ItemTypeVar] | None value,
Any at = None,
str label = "assignment" )
Set an attribute on the config instance.

Parameters
----------
instance : `lsst.pex.config.Config`
    The config instance that contains this field.
value : obj
    Value to set on this field.
at : `list` of `~lsst.pex.config.callStack.StackFrame` or `None`,\
        optional
    The call stack (created by
    `lsst.pex.config.callStack.getCallStack`).
label : `str`, optional
    Event label for the history.

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

Derived `~lsst.pex.config.Field` classes may need to override the
behavior. When overriding ``__set__``, `~lsst.pex.config.Field` authors
should follow the following rules:

- Do not allow modification of frozen configs.
- Validate the new value **before** modifying the field. Except if the
  new value is `None`. `None` is special and no attempt should be made
  to validate it until `lsst.pex.config.Config.validate` is called.
- Do not modify the `~lsst.pex.config.Config` instance to contain
  invalid values.
- If the field is modified, update the history of the
  `lsst.pex.config.field.Field` to reflect the changes.

In order to decrease the need to implement this method in derived
`~lsst.pex.config.Field` types, value validation is performed in the
`lsst.pex.config.Field._validateValue`. If only the validation step
differs in the derived `~lsst.pex.config.Field`, it is simpler to
implement `lsst.pex.config.Field._validateValue` than to reimplement
``__set__``. More complicated behavior, however, may require
reimplementation.

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

◆ _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 : 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.

◆ _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.

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.config.Field.

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


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