DictField¶
- class lsst.pex.config.DictField(doc, keytype=None, itemtype=None, default=None, optional=False, dictCheck=None, itemCheck=None, deprecated=None)¶
Bases:
Field
[Dict
[KeyTypeVar
,ItemTypeVar
]],Generic
[KeyTypeVar
,ItemTypeVar
]A configuration field (
Field
subclass) that maps keys and values.The types of both items and keys are restricted to these builtin types:
int
,float
,complex
,bool
, andstr
). 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.- dictCheckcallable
A function that validates the dictionary as a whole.
- itemCheckcallable
A function that validates individual mapping values.
- deprecatedNone 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.
- doc
See also
Examples
This field maps has
str
keys andint
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}
Attributes Summary
Supported data types for field values (
set
of types).Methods Summary
freeze
(instance)Make this field read-only (for internal use only).
rename
(instance)Rename the field in a
Config
(for internal use only).save
(outfile, instance)Save this field to a file (for internal use only).
toDict
(instance)Convert this field's key-value pairs into a regular
dict
.validate
(instance)Validate the field's value (for internal use only).
Attributes Documentation
- supportedTypes = {<class 'float'>, <class 'complex'>, <class 'bool'>, <class 'int'>, <class 'str'>}¶
Supported data types for field values (
set
of types).
Methods Documentation
- freeze(instance)¶
Make this field read-only (for internal use only).
- Parameters:
- instance
lsst.pex.config.Config
The config instance that contains this field.
- instance
Notes
Freezing is only relevant for fields that hold subconfigs. Fields which hold subconfigs should freeze each subconfig.
Subclasses should implement this method.
- rename(instance)¶
Rename the field in a
Config
(for internal use only).- Parameters:
- instance
lsst.pex.config.Config
The config instance that contains this field.
- instance
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
Field
instances that hold subconfigs.Field
s that hold subconfigs should rename each subconfig with the full field name as generated bylsst.pex.config.config._joinNamePath
.
- save(outfile, instance)¶
Save this field to a file (for internal use only).
- Parameters:
Notes
This method is invoked by the
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.
- validate(instance)¶
Validate the field’s value (for internal use only).
- Parameters:
- instance
lsst.pex.config.Config
The configuration that contains this field.
- instance
- Returns:
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 theConfigField.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.