LSST Applications g1635faa6d4+215bc75b8c,g1653933729+a8ce1bb630,g22ce9dc20b+d972d8df89,g28da252d5a+0fcf840c6d,g29321ee8c0+e558be0e74,g2bbee38e9b+9634bc57db,g2bc492864f+9634bc57db,g2cdde0e794+c2c89b37c4,g3156d2b45e+41e33cbcdc,g347aa1857d+9634bc57db,g35bb328faa+a8ce1bb630,g3a166c0a6a+9634bc57db,g3e281a1b8c+9f2c4e2fc3,g414038480c+077ccc18e7,g41af890bb2+2a6f257a1d,g5fbc88fb19+17cd334064,g781aacb6e4+a8ce1bb630,g7ab3e175f3+59ce30aec6,g80478fca09+f8b2ab54e1,g82479be7b0+ba9d578ff8,g858d7b2824+d972d8df89,g9125e01d80+a8ce1bb630,g9726552aa6+10f999ec6a,ga5288a1d22+630363936d,gae0086650b+a8ce1bb630,gb58c049af0+d64f4d3760,gb9c6c11c1e+9553554aa7,gbd46683f8f+0c4209622a,gc28159a63d+9634bc57db,gcf0d15dbbd+2db122af0a,gda3e153d99+d972d8df89,gda6a2b7d83+2db122af0a,gdaeeff99f8+1711a396fd,ge2409df99d+d1dc2f3b25,ge33fd446bb+d972d8df89,ge79ae78c31+9634bc57db,gf0baf85859+147a0692ba,gf3967379c6+02b11634a5,w.2024.45
LSST Data Management Base Package
Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | Static Public Attributes | Protected Member Functions | List of all members
lsst.pex.config.configChoiceField.ConfigChoiceField Class Reference
Inheritance diagram for lsst.pex.config.configChoiceField.ConfigChoiceField:
lsst.pex.config.config.Field lsst.pex.config.configChoiceField.ConfigInstanceDict lsst.pex.config.config.Config lsst.pex.config.config.ConfigMeta lsst.pex.config.registry.RegistryField

Public Member Functions

 __init__ (self, doc, typemap, default=None, optional=False, multi=False, deprecated=None)
 
 __class_getitem__ (cls, 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")
 
 __get__ (self, instance, owner=None, at=None, label="default")
 
None __set__ (self, Config instance, ConfigInstanceDict|None value, Any at=None, str label="assignment")
 
 rename (self, instance)
 
 validate (self, instance)
 
 toDict (self, instance)
 
 freeze (self, instance)
 
 save (self, outfile, instance)
 
 __deepcopy__ (self, memo)
 

Public Attributes

 typemap
 
 multi
 
 name
 

Static Public Attributes

 instanceDictClass = ConfigInstanceDict
 

Protected Member Functions

 _getOrMake (self, instance, label="default")
 
 _collectImports (self, instance, imports)
 
 _compare (self, instance1, instance2, shortcut, rtol, atol, output)
 

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

Definition at line 381 of file configChoiceField.py.

Constructor & Destructor Documentation

◆ __init__()

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

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

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

Definition at line 488 of file configChoiceField.py.

488 def __init__(self, doc, typemap, default=None, optional=False, multi=False, deprecated=None):
489 source = getStackFrame()
490 self._setup(
491 doc=doc,
492 dtype=self.instanceDictClass,
493 default=default,
494 check=None,
495 optional=optional,
496 source=source,
497 deprecated=deprecated,
498 )
499 self.typemap = typemap
500 self.multi = multi
501

Member Function Documentation

◆ __class_getitem__()

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

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

Definition at line 502 of file configChoiceField.py.

502 def __class_getitem__(cls, params: tuple[type, ...] | type | ForwardRef):
503 raise ValueError("ConfigChoiceField does not support typing argument")
504

◆ __deepcopy__()

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.

Definition at line 604 of file configChoiceField.py.

604 def __deepcopy__(self, memo):
605 """Customize deep-copying, because we always want a reference to the
606 original typemap.
607
608 WARNING: this must be overridden by subclasses if they change the
609 constructor signature!
610 """
611 other = type(self)(
612 doc=self.doc,
613 typemap=self.typemap,
614 default=copy.deepcopy(self.default),
615 optional=self.optional,
616 multi=self.multi,
617 )
618 other.source = self.source
619 return other
620

◆ __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.

Definition at line 523 of file configChoiceField.py.

525 ) -> ConfigInstanceDict: ...
526

◆ __get__() [2/3]

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

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

Definition at line 527 of file configChoiceField.py.

527 def __get__(self, instance, owner=None, at=None, label="default"):
528 if instance is None or not isinstance(instance, Config):
529 return self
530 else:
531 return self._getOrMake(instance)
532

◆ __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.

Definition at line 518 of file configChoiceField.py.

520 ) -> ConfigChoiceField: ...
521

◆ __set__()

None lsst.pex.config.configChoiceField.ConfigChoiceField.__set__ ( self,
Config instance,
ConfigInstanceDict | None 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` or `None`,\
        optional
    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.

Definition at line 533 of file configChoiceField.py.

535 ) -> None:
536 if instance._frozen:
537 raise FieldValidationError(self, instance, "Cannot modify a frozen Config")
538 if at is None:
539 at = getCallStack()
540 instanceDict = self._getOrMake(instance)
541 if isinstance(value, self.instanceDictClass):
542 for k, v in value.items():
543 instanceDict.__setitem__(k, v, at=at, label=label)
544 instanceDict._setSelection(value._selection, at=at, label=label)
545
546 else:
547 instanceDict._setSelection(value, at=at, label=label)
548

◆ _collectImports()

lsst.pex.config.configChoiceField.ConfigChoiceField._collectImports ( self,
instance,
imports )
protected
Call the _collectImports method on all config
objects the field may own, and union them with the supplied imports
set.

Parameters
----------
instance : instance or subclass of `lsst.pex.config.Config`
    A config object that has this field defined on it
imports : `set`
    Set of python modules that need imported after persistence

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

Definition at line 588 of file configChoiceField.py.

588 def _collectImports(self, instance, imports):
589 instanceDict = self.__get__(instance)
590 for config in instanceDict.values():
591 config._collectImports()
592 imports |= config._imports
593

◆ _compare()

lsst.pex.config.configChoiceField.ConfigChoiceField._compare ( self,
instance1,
instance2,
shortcut,
rtol,
atol,
output )
protected
Compare two fields for equality.

Used by `lsst.pex.ConfigChoiceField.compare`.

Parameters
----------
instance1 : `lsst.pex.config.Config`
    Left-hand side config instance to compare.
instance2 : `lsst.pex.config.Config`
    Right-hand side config instance to compare.
shortcut : `bool`
    If `True`, this function returns as soon as an inequality if found.
rtol : `float`
    Relative tolerance for floating point comparisons.
atol : `float`
    Absolute tolerance for floating point comparisons.
output : callable
    A callable that takes a string, used (possibly repeatedly) to
    report inequalities.

Returns
-------
isEqual : bool
    `True` if the fields are equal, `False` otherwise.

Notes
-----
Only the selected configurations are compared, as the parameters of any
others do not matter.

Floating point comparisons are performed by `numpy.allclose`.

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

Definition at line 621 of file configChoiceField.py.

621 def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
622 """Compare two fields for equality.
623
624 Used by `lsst.pex.ConfigChoiceField.compare`.
625
626 Parameters
627 ----------
628 instance1 : `lsst.pex.config.Config`
629 Left-hand side config instance to compare.
630 instance2 : `lsst.pex.config.Config`
631 Right-hand side config instance to compare.
632 shortcut : `bool`
633 If `True`, this function returns as soon as an inequality if found.
634 rtol : `float`
635 Relative tolerance for floating point comparisons.
636 atol : `float`
637 Absolute tolerance for floating point comparisons.
638 output : callable
639 A callable that takes a string, used (possibly repeatedly) to
640 report inequalities.
641
642 Returns
643 -------
644 isEqual : bool
645 `True` if the fields are equal, `False` otherwise.
646
647 Notes
648 -----
649 Only the selected configurations are compared, as the parameters of any
650 others do not matter.
651
652 Floating point comparisons are performed by `numpy.allclose`.
653 """
654 d1 = getattr(instance1, self.name)
655 d2 = getattr(instance2, self.name)
656 name = getComparisonName(
657 _joinNamePath(instance1._name, self.name), _joinNamePath(instance2._name, self.name)
658 )
659 if not compareScalars(f"selection for {name}", d1._selection, d2._selection, output=output):
660 return False
661 if d1._selection is None:
662 return True
663 if self.multi:
664 nested = [(k, d1[k], d2[k]) for k in d1._selection]
665 else:
666 nested = [(d1._selection, d1[d1._selection], d2[d1._selection])]
667 equal = True
668 for k, c1, c2 in nested:
669 result = compareConfigs(
670 f"{name}[{k!r}]", c1, c2, shortcut=shortcut, rtol=rtol, atol=atol, output=output
671 )
672 if not result and shortcut:
673 return False
674 equal = equal and result
675 return equal

◆ _getOrMake()

lsst.pex.config.configChoiceField.ConfigChoiceField._getOrMake ( self,
instance,
label = "default" )
protected

Definition at line 505 of file configChoiceField.py.

505 def _getOrMake(self, instance, label="default"):
506 instanceDict = instance._storage.get(self.name)
507 if instanceDict is None:
508 at = getCallStack(1)
509 instanceDict = self.dtype(instance, self)
510 instanceDict.__doc__ = self.doc
511 instance._storage[self.name] = instanceDict
512 history = instance._history.setdefault(self.name, [])
513 history.append(("Initialized from defaults", at, label))
514
515 return instanceDict
516

◆ freeze()

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.

Definition at line 582 of file configChoiceField.py.

582 def freeze(self, instance):
583 instanceDict = self.__get__(instance)
584 instanceDict.freeze()
585 for v in instanceDict.values():
586 v.freeze()
587

◆ rename()

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.Field`\s 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.

Definition at line 549 of file configChoiceField.py.

549 def rename(self, instance):
550 instanceDict = self.__get__(instance)
551 fullname = _joinNamePath(instance._name, self.name)
552 instanceDict._rename(fullname)
553

◆ save()

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 : `~lsst.pex.config.Config`
    The `~lsst.pex.config.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.

Definition at line 594 of file configChoiceField.py.

594 def save(self, outfile, instance):
595 instanceDict = self.__get__(instance)
596 fullname = _joinNamePath(instance._name, self.name)
597 for v in instanceDict.values():
598 v._save(outfile)
599 if self.multi:
600 outfile.write(f"{fullname}.names={sorted(instanceDict.names)!r}\n")
601 else:
602 outfile.write(f"{fullname}.name={instanceDict.name!r}\n")
603

◆ toDict()

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 : `~lsst.pex.config.Config`
    The `~lsst.pex.config.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.

Definition at line 566 of file configChoiceField.py.

566 def toDict(self, instance):
567 instanceDict = self.__get__(instance)
568
569 dict_ = {}
570 if self.multi:
571 dict_["names"] = instanceDict.names
572 else:
573 dict_["name"] = instanceDict.name
574
575 values = {}
576 for k, v in instanceDict.items():
577 values[k] = v.toDict()
578 dict_["values"] = values
579
580 return dict_
581

◆ validate()

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

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

Definition at line 554 of file configChoiceField.py.

554 def validate(self, instance):
555 instanceDict = self.__get__(instance)
556 if instanceDict.active is None and not self.optional:
557 msg = "Required field cannot be None"
558 raise FieldValidationError(self, instance, msg)
559 elif instanceDict.active is not None:
560 if self.multi:
561 for a in instanceDict.active:
562 a.validate()
563 else:
564 instanceDict.active.validate()
565

Member Data Documentation

◆ instanceDictClass

lsst.pex.config.configChoiceField.ConfigChoiceField.instanceDictClass = ConfigInstanceDict
static

Definition at line 486 of file configChoiceField.py.

◆ multi

lsst.pex.config.configChoiceField.ConfigChoiceField.multi

Definition at line 500 of file configChoiceField.py.

◆ name

lsst.pex.config.configChoiceField.ConfigChoiceField.name

Definition at line 657 of file configChoiceField.py.

◆ typemap

lsst.pex.config.configChoiceField.ConfigChoiceField.typemap

Definition at line 499 of file configChoiceField.py.


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