lsst.pex.config.configChoiceField.ConfigChoiceField Class Reference

Inheritance diagram for lsst.pex.config.configChoiceField.ConfigChoiceField:

Public Member Functions
def	__init__ (self, doc, typemap, default=None, optional=False, multi=False, deprecated=None)
def	__class_getitem__ (cls, Union[tuple[type,...], type, ForwardRef] params)
"ConfigChoiceField"	__get__ (self, None instance, Any owner=None, Any at=None, str label="default")
ConfigInstanceDict	__get__ (self, Config instance, Any owner=None, Any at=None, str label="default")
def	__get__ (self, instance, owner=None, at=None, label="default")
None	__set__ (self, Config instance, Optional[ConfigInstanceDict] value, Any at=None, str 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 lsst.pex.config.config.Field
def	__class_getitem__ (cls, Union[tuple[type,...], type, ForwardRef] params)
def	__init__ (self, doc, dtype=None, 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)
"Field[FieldTypeVar]"	__get__ (self, None instance, Any owner=None, Any at=None, str label="default")
FieldTypeVar	__get__ (self, "Config" instance, Any owner=None, Any at=None, str label="default")
def	__get__ (self, instance, owner=None, at=None, label="default")
None	__set__ (self, "Config" instance, Optional[FieldTypeVar] value, Any at=None, str label="assignment")
def	__delete__ (self, instance, at=None, label="deletion")
Public Member Functions inherited from lsst.pex.config.configChoiceField.ConfigInstanceDict
def	__init__ (self, config, field)
def	types (self)
def	__contains__ (self, k)
def	__len__ (self)
def	__iter__ (self)
def	__getitem__ (self, k, at=None, label="default")
def	__setitem__ (self, k, value, at=None, label="assignment")
def	__setattr__ (self, attr, value, at=None, label="assignment")
def	freeze (self)
def	__reduce__ (self)

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

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

Additional Inherited Members
Properties inherited from lsst.pex.config.configChoiceField.ConfigInstanceDict
	names = property(_getNames, _setNames, _delNames)
	name = property(_getName, _setName, _delName)
	active = property(_getActive)

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

Constructor & Destructor Documentation

__init__()

def lsst.pex.config.configChoiceField.ConfigChoiceField.__init__	(		self,
			doc,
			typemap,
			default = None,
			optional = False,
			multi = False,
			deprecated = None
	)

Reimplemented from lsst.pex.config.config.Field.

Member Function Documentation

__class_getitem__()

def lsst.pex.config.configChoiceField.ConfigChoiceField.__class_getitem__	(		cls,
		Union[tuple[type, ...], type, ForwardRef]	params
	)

Reimplemented from lsst.pex.config.config.Field.

__deepcopy__()

def lsst.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!

Reimplemented in lsst.pex.config.registry.RegistryField.

__get__() [1/3]

ConfigInstanceDict lsst.pex.config.configChoiceField.ConfigChoiceField.__get__	(		self,
		Config	instance,
		Any	owner = None,
		Any	at = None,
		str	label = "default"
	)

Reimplemented from lsst.pex.config.config.Field.

__get__() [2/3]

def lsst.pex.config.configChoiceField.ConfigChoiceField.__get__	(		self,
			instance,
			owner = None,
			at = None,
			label = "default"
	)

Reimplemented from lsst.pex.config.config.Field.

__get__() [3/3]

"ConfigChoiceField" lsst.pex.config.configChoiceField.ConfigChoiceField.__get__	(		self,
		None	instance,
		Any	owner = None,
		Any	at = None,
		str	label = "default"
	)

Reimplemented from lsst.pex.config.config.Field.

__set__()

None lsst.pex.config.configChoiceField.ConfigChoiceField.__set__	(		self,
		Config	instance,
		Optional[ConfigInstanceDict]	value,
		Any	at = None,
		str	label = "assignment"
	)

Set an attribute on the config instance.

Parameters
----------
instance : `lsst.pex.config.Config`
    The config instance that contains this field.
value : obj
    Value to set on this field.
at : `list` of `lsst.pex.config.callStack.StackFrame`
    The call stack (created by
    `lsst.pex.config.callStack.getCallStack`).
label : `str`, optional
    Event label for the history.

Notes
-----
This method is invoked by the owning `lsst.pex.config.Config` object
and should not be called directly.

Derived `~lsst.pex.config.Field` classes may need to override the
behavior. When overriding ``__set__``, `~lsst.pex.config.Field` authors
should follow the following rules:

- Do not allow modification of frozen configs.
- Validate the new value **before** modifying the field. Except if the
  new value is `None`. `None` is special and no attempt should be made
  to validate it until `lsst.pex.config.Config.validate` is called.
- Do not modify the `~lsst.pex.config.Config` instance to contain
  invalid values.
- If the field is modified, update the history of the
  `lsst.pex.config.field.Field` to reflect the changes.

In order to decrease the need to implement this method in derived
`~lsst.pex.config.Field` types, value validation is performed in the
`lsst.pex.config.Field._validateValue`. If only the validation step
differs in the derived `~lsst.pex.config.Field`, it is simpler to
implement `lsst.pex.config.Field._validateValue` than to reimplement
``__set__``. More complicated behavior, however, may require
reimplementation.

Reimplemented from lsst.pex.config.config.Field.

freeze()

def lsst.pex.config.configChoiceField.ConfigChoiceField.freeze	(		self,
			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.**

Reimplemented from lsst.pex.config.config.Field.

rename()

def lsst.pex.config.configChoiceField.ConfigChoiceField.rename	(		self,
			instance
	)

Rename the field in a `~lsst.pex.config.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 `~lsst.pex.config.Field` instances that
hold subconfigs. `~lsst.pex.config.Fields` that hold subconfigs should
rename each subconfig with the full field name as generated by
`lsst.pex.config.config._joinNamePath`.

Reimplemented from lsst.pex.config.config.Field.

save()

def lsst.pex.config.configChoiceField.ConfigChoiceField.save	(		self,
			outfile,
			instance
	)

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

Parameters
----------
outfile : file-like object
    A writeable field handle.
instance : `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.

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.

Reimplemented from lsst.pex.config.config.Field.

toDict()

def lsst.pex.config.configChoiceField.ConfigChoiceField.toDict	(		self,
			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
----------
instance : `Config`
    The `Config` that contains this field.

Returns
-------
value : object
    The field's value. See *Notes*.

Notes
-----
This method invoked by the owning `~lsst.pex.config.Config` object and
should not be called directly.

Simple values are passed through. Complex data structures must be
manipulated. For example, a `~lsst.pex.config.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.

Reimplemented from lsst.pex.config.config.Field.

validate()

def lsst.pex.config.configChoiceField.ConfigChoiceField.validate	(		self,
			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 `~lsst.pex.config.Field` subclasses should call
`lsst.pex.config.field.Field.validate` if they re-implement
`~lsst.pex.config.field.Field.validate`.

Reimplemented from lsst.pex.config.config.Field.

---

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

• python/lsst/pex/config/configChoiceField.py