ConfigChoiceField¶
-
class
lsst.pex.config.
ConfigChoiceField
(doc, typemap, default=None, optional=False, multi=False, deprecated=None)¶ Bases:
lsst.pex.config.Field
A configuration field (
Field
subclass) that allows a user to choose from a set ofConfig
types.Parameters: - doc :
str
Documentation string for the field.
- typemap :
dict
-like A mapping between keys and
Config
-types as values. See Examples for details.- default :
str
, optional The default configuration name.
- optional :
bool
, optional When
False
,lsst.pex.config.Config.validate
will fail if the field’s value isNone
.- multi :
bool
, optional If
True
, the field allows multiple selections. In this case, set the selections by assigning a sequence to thenames
attribute of the field.If
False
, the field allows only a single selection. In this case, set the active config by assigning the config’s key from thetypemap
to the field’sname
attribute (see Examples).- 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
,ConfigDictField
,ConfigField
,ConfigurableField
,DictField
,Field
,ListField
,RangeField
,RegistryField
Notes
ConfigChoiceField
instances can allow either single selections or multiple selections, depending on themulti
parameter. For single-selection fields, set the selection with thename
attribute. For multi-selection fields, set the selection though thenames
attribute.This field is validated only against the active selection. If the
active
attribute isNone
and the field is not optional, validation will fail.When saving a configuration with a
ConfigChoiceField
, the entire set is saved, as well as the active selection.Examples
While the
typemap
is shared by all instances of the field, each instance of the field has its own instance of a particular sub-config type.For example,
AaaConfig
is a config object>>> from lsst.pex.config import Config, ConfigChoiceField, Field >>> class AaaConfig(Config): ... somefield = Field("doc", int) ...
The
MyConfig
config has aConfigChoiceField
field calledchoice
that maps theAaaConfig
type to the"AAA"
key:>>> TYPEMAP = {"AAA", AaaConfig} >>> class MyConfig(Config): ... choice = ConfigChoiceField("doc for choice", TYPEMAP) ...
Creating an instance of
MyConfig
:>>> instance = MyConfig()
Setting value of the field
somefield
on the “AAA” key of thechoice
field:>>> instance.choice['AAA'].somefield = 5
Selecting the active configuration
Make the
"AAA"
key the active configuration value for thechoice
field:>>> instance.choice = "AAA"
Alternatively, the last line can be written:
>>> instance.choice.name = "AAA"
(If the config instance allows multiple selections, you’d assign a sequence to the
names
attribute instead.)ConfigChoiceField
instances also allow multiple values of the same type:>>> TYPEMAP["CCC"] = AaaConfig >>> TYPEMAP["BBB"] = AaaConfig
Attributes Summary
supportedTypes
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 the field value so that it can be set as the value of an item in a dict
(for internal use only).validate
(instance)Validate the field (for internal use only). Attributes Documentation
-
supportedTypes
= {<class 'str'>, <class 'int'>, <class 'bool'>, <class 'float'>, <class 'complex'>}¶
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.
Notes
Freezing is only relevant for fields that hold subconfigs. Fields which hold subconfigs should freeze each subconfig.
Subclasses should implement this method.
- instance :
-
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.
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.Fields
that hold subconfigs should rename each subconfig with the full field name as generated bylsst.pex.config.config._joinNamePath
.- instance :
-
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.
-
toDict
(instance)¶ Convert the field value so that it can be set as the value of an item in a
dict
(for internal use only).Parameters: Returns: - value : object
The field’s value. See Notes.
Notes
This method invoked by the owning
Config
object and should not be called directly.Simple values are passed through. Complex data structures must be manipulated. For example, a
Field
holding a subconfig should, instead of the subconfig object, return adict
where the keys are the field names in the subconfig, and the values are the field values in the subconfig.
-
validate
(instance)¶ Validate the field (for internal use only).
Parameters: - instance :
lsst.pex.config.Config
The config instance that contains this field.
Raises: - lsst.pex.config.FieldValidationError
Raised if verification fails.
Notes
This method provides basic validation:
- Ensures that the value is not
None
if the field is not optional. - Ensures type correctness.
- Ensures that the user-provided
check
function is valid.
Most
Field
subclasses should calllsst.pex.config.field.Field.validate
if they re-implementvalidate
.- instance :
- doc :