|
def | __init__ (self, doc, typemap, default=None, optional=False, multi=False, deprecated=None) |
|
def | __get__ (self, instance, owner=None) |
|
def | __set__ (self, instance, value, at=None, label="assignment") |
|
def | rename (self, instance) |
|
def | validate (self, instance) |
|
def | toDict (self, instance) |
|
def | freeze (self, instance) |
|
def | save (self, outfile, instance) |
|
def | __deepcopy__ (self, memo) |
|
def | __get__ (self, instance, owner=None, at=None, label="default") |
|
def | __delete__ (self, instance, at=None, label='deletion') |
|
A configuration field (`~lsst.pex.config.Field` subclass) that allows a
user to choose from a set of `~lsst.pex.config.Config` types.
Parameters
----------
doc : `str`
Documentation string for the field.
typemap : `dict`-like
A mapping between keys and `~lsst.pex.config.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 is `None`.
multi : `bool`, 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*).
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 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
Definition at line 306 of file configChoiceField.py.