lsst.pex.config  19.0.0
Public Member Functions | Public Attributes | Static Public Attributes | List of all members
pex.config.configChoiceField.ConfigChoiceField Class Reference
Inheritance diagram for pex.config.configChoiceField.ConfigChoiceField:
pex.config.config.Field pex.config.registry.RegistryField

Public Member Functions

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)
 
- Public Member Functions inherited from pex.config.config.Field
def __init__ (self, doc, dtype, default=None, check=None, optional=False, deprecated=None)
 
def rename (self, instance)
 
def validate (self, instance)
 
def freeze (self, instance)
 
def save (self, outfile, instance)
 
def toDict (self, instance)
 
def __get__ (self, instance, owner=None, at=None, label="default")
 
def __set__ (self, instance, value, at=None, label='assignment')
 
def __delete__ (self, instance, at=None, label='deletion')
 

Public Attributes

 typemap
 
 multi
 
- Public Attributes inherited from pex.config.config.Field
 dtype
 
 doc
 
 deprecated
 
 default
 
 check
 
 optional
 
 source
 

Static Public Attributes

 instanceDictClass = ConfigInstanceDict
 
- Static Public Attributes inherited from pex.config.config.Field
 supportedTypes = set((str, bool, float, int, complex))
 

Detailed Description

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

Member Function Documentation

◆ __deepcopy__()

def pex.config.configChoiceField.ConfigChoiceField.__deepcopy__ (   self,
  memo 
)
Customize deep-copying, because we always want a reference to the
original typemap.

WARNING: this must be overridden by subclasses if they change the
constructor signature!

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