ConfigChoiceField¶

class lsst.pex.config.ConfigChoiceField(doc, typemap, default=None, optional=False, multi=False, deprecated=None)¶

Bases: Field[ConfigInstanceDict]

A configuration field (Field subclass) that allows a user to choose from a set of Config types.

Parameters:

docstr

Documentation string for the field.

typemapdict-like

A mapping between keys and Config-types as values. See Examples for details.

defaultstr, optional

The default configuration name.

optionalbool, optional

When False, lsst.pex.config.Config.validate will fail if the field’s value is None.

multibool, optional

If True, the field allows multiple selections. In this case, set the selections by assigning a sequence to the names 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 the typemap to the field’s name attribute (see Examples).

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.

See also

ChoiceField
ConfigDictField
ConfigField
ConfigurableField
DictField
Field
ListField
RangeField
RegistryField

Notes

ConfigChoiceField instances can allow either single selections or multiple selections, depending on the multi parameter. For single-selection fields, set the selection with the name attribute. For multi-selection fields, set the selection though the names attribute.

This field is validated only against the active selection. If the active attribute is None 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 a ConfigChoiceField field called choice that maps the AaaConfig 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 the choice field:

>>> instance.choice["AAA"].somefield = 5

Selecting the active configuration

Make the "AAA" key the active configuration value for the choice 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

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 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 'float'>, <class 'bool'>, <class 'complex'>, <class 'str'>, <class 'int'>}¶: Supported data types for field values (set of types).

Methods Documentation

freeze(instance)¶

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

Parameters:

instancelsst.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.

rename(instance)¶

Rename the field in a Config (for internal use only).

Parameters:

instancelsst.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 by lsst.pex.config.config._joinNamePath.

save(outfile, instance)¶

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

Parameters:

outfilefile-like object: A writeable field handle.
instanceConfig: The Config instance that contains this field.

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:

instanceConfig: The Config that contains this field.

Returns:

valueobject: 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 a dict 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:

instancelsst.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 call lsst.pex.config.Field.validate if they re-implement validate.

Navigation

ConfigChoiceField¶