LSST Applications  21.0.0-172-gfb10e10a+18fedfabac,22.0.0+297cba6710,22.0.0+80564b0ff1,22.0.0+8d77f4f51a,22.0.0+a28f4c53b1,22.0.0+dcf3732eb2,22.0.1-1-g7d6de66+2a20fdde0d,22.0.1-1-g8e32f31+297cba6710,22.0.1-1-geca5380+7fa3b7d9b6,22.0.1-12-g44dc1dc+2a20fdde0d,22.0.1-15-g6a90155+515f58c32b,22.0.1-16-g9282f48+790f5f2caa,22.0.1-2-g92698f7+dcf3732eb2,22.0.1-2-ga9b0f51+7fa3b7d9b6,22.0.1-2-gd1925c9+bf4f0e694f,22.0.1-24-g1ad7a390+a9625a72a8,22.0.1-25-g5bf6245+3ad8ecd50b,22.0.1-25-gb120d7b+8b5510f75f,22.0.1-27-g97737f7+2a20fdde0d,22.0.1-32-gf62ce7b1+aa4237961e,22.0.1-4-g0b3f228+2a20fdde0d,22.0.1-4-g243d05b+871c1b8305,22.0.1-4-g3a563be+32dcf1063f,22.0.1-4-g44f2e3d+9e4ab0f4fa,22.0.1-42-gca6935d93+ba5e5ca3eb,22.0.1-5-g15c806e+85460ae5f3,22.0.1-5-g58711c4+611d128589,22.0.1-5-g75bb458+99c117b92f,22.0.1-6-g1c63a23+7fa3b7d9b6,22.0.1-6-g50866e6+84ff5a128b,22.0.1-6-g8d3140d+720564cf76,22.0.1-6-gd805d02+cc5644f571,22.0.1-8-ge5750ce+85460ae5f3,master-g6e05de7fdc+babf819c66,master-g99da0e417a+8d77f4f51a,w.2021.48
LSST Data Management Base Package
Public Member Functions | Public Attributes | Static Public Attributes | List of all members
lsst.pex.config.choiceField.ChoiceField Class Reference
Inheritance diagram for lsst.pex.config.choiceField.ChoiceField:
lsst.pex.config.config.Field

Public Member Functions

def __init__ (self, doc, dtype, allowed, default=None, optional=True, 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

 allowed
 
 source
 
 dtype
 
 doc
 
 deprecated
 
 default
 
 check
 
 optional
 

Static Public Attributes

 supportedTypes = set((str, bool, float, int, complex))
 

Detailed Description

A configuration field (`~lsst.pex.config.Field` subclass) that allows a
user to select from a predefined set of values.

Use ``ChoiceField`` when a configuration can only take one of a predefined
set of values. Each choice must be of the same type.

Parameters
----------
doc : `str`
    Documentation string that describes the configuration field.
dtype : class
    The type of the field's choices. For example, `str` or `int`.
allowed : `dict`
    The allowed values. Keys are the allowed choices (of ``dtype``-type).
    Values are descriptions (`str`-type) of each choice.
default : ``dtype``-type, optional
    The default value, which is of type ``dtype`` and one of the allowed
    choices.
optional : `bool`, optional
    If `True`, this configuration field is *optional*. Default is `True`.
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
--------
ConfigChoiceField
ConfigDictField
ConfigField
ConfigurableField
DictField
Field
ListField
RangeField
RegistryField

Definition at line 34 of file choiceField.py.

Constructor & Destructor Documentation

◆ __init__()

def lsst.pex.config.choiceField.ChoiceField.__init__ (   self,
  doc,
  dtype,
  allowed,
  default = None,
  optional = True,
  deprecated = None 
)

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

Definition at line 71 of file choiceField.py.

71  def __init__(self, doc, dtype, allowed, default=None, optional=True, deprecated=None):
72  self.allowed = dict(allowed)
73  if optional and None not in self.allowed:
74  self.allowed[None] = "Field is optional"
75 
76  if len(self.allowed) == 0:
77  raise ValueError("ChoiceFields must allow at least one choice")
78 
79  Field.__init__(self, doc=doc, dtype=dtype, default=default,
80  check=None, optional=optional, deprecated=deprecated)
81 
82  self.__doc__ += "\n\nAllowed values:\n\n"
83  for choice, choiceDoc in self.allowed.items():
84  if choice is not None and not isinstance(choice, dtype):
85  raise ValueError("ChoiceField's allowed choice %s is of incorrect type %s. Expected %s" %
86  (choice, _typeStr(choice), _typeStr(dtype)))
87  self.__doc__ += "%s\n %s\n" % ('``{0!r}``'.format(str(choice)), choiceDoc)
88 
89  self.source = getStackFrame()
90 
std::vector< SchemaItem< Flag > > * items
def getStackFrame(relative=0)
Definition: callStack.py:58
def format(config, name=None, writeSourceLine=True, prefix="", verbose=False)
Definition: history.py:174

Member Function Documentation

◆ __delete__()

def lsst.pex.config.config.Field.__delete__ (   self,
  instance,
  at = None,
  label = 'deletion' 
)
inherited
Delete an attribute from a `lsst.pex.config.Config` instance.

Parameters
----------
instance : `lsst.pex.config.Config`
    The config instance that contains 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 is invoked by the owning `~lsst.pex.config.Config` object and
should not be called directly.

Definition at line 634 of file config.py.

634  def __delete__(self, instance, at=None, label='deletion'):
635  """Delete an attribute from a `lsst.pex.config.Config` instance.
636 
637  Parameters
638  ----------
639  instance : `lsst.pex.config.Config`
640  The config instance that contains this field.
641  at : `list` of `lsst.pex.config.callStack.StackFrame`
642  The call stack (created by
643  `lsst.pex.config.callStack.getCallStack`).
644  label : `str`, optional
645  Event label for the history.
646 
647  Notes
648  -----
649  This is invoked by the owning `~lsst.pex.config.Config` object and
650  should not be called directly.
651  """
652  if at is None:
653  at = getCallStack()
654  self.__set__(instance, None, at=at, label=label)
655 
def getCallStack(skip=0)
Definition: callStack.py:175

◆ __get__()

def lsst.pex.config.config.Field.__get__ (   self,
  instance,
  owner = None,
  at = None,
  label = "default" 
)
inherited
Define how attribute access should occur on the Config instance
This is invoked by the owning config object and should not be called
directly

When the field attribute is accessed on a Config class object, it
returns the field object itself in order to allow inspection of
Config classes.

When the field attribute is access on a config instance, the actual
value described by the field (and held by the Config instance) is
returned.

Reimplemented in lsst.pex.config.configurableField.ConfigurableField.

Definition at line 550 of file config.py.

550  def __get__(self, instance, owner=None, at=None, label="default"):
551  """Define how attribute access should occur on the Config instance
552  This is invoked by the owning config object and should not be called
553  directly
554 
555  When the field attribute is accessed on a Config class object, it
556  returns the field object itself in order to allow inspection of
557  Config classes.
558 
559  When the field attribute is access on a config instance, the actual
560  value described by the field (and held by the Config instance) is
561  returned.
562  """
563  if instance is None:
564  return self
565  else:
566  # try statements are almost free in python if they succeed
567  try:
568  return instance._storage[self.name]
569  except AttributeError:
570  if not isinstance(instance, Config):
571  return self
572  else:
573  raise AttributeError(f"Config {instance} is missing "
574  "_storage attribute, likely"
575  " incorrectly initialized")
576 

◆ __set__()

def lsst.pex.config.config.Field.__set__ (   self,
  instance,
  value,
  at = None,
  label = 'assignment' 
)
inherited
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 in lsst.pipe.tasks.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.listField.ListField, lsst.pex.config.dictField.DictField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configField.ConfigField, and lsst.pex.config.configChoiceField.ConfigChoiceField.

Definition at line 577 of file config.py.

577  def __set__(self, instance, value, at=None, label='assignment'):
578  """Set an attribute on the config instance.
579 
580  Parameters
581  ----------
582  instance : `lsst.pex.config.Config`
583  The config instance that contains this field.
584  value : obj
585  Value to set on this field.
586  at : `list` of `lsst.pex.config.callStack.StackFrame`
587  The call stack (created by
588  `lsst.pex.config.callStack.getCallStack`).
589  label : `str`, optional
590  Event label for the history.
591 
592  Notes
593  -----
594  This method is invoked by the owning `lsst.pex.config.Config` object
595  and should not be called directly.
596 
597  Derived `~lsst.pex.config.Field` classes may need to override the
598  behavior. When overriding ``__set__``, `~lsst.pex.config.Field` authors
599  should follow the following rules:
600 
601  - Do not allow modification of frozen configs.
602  - Validate the new value **before** modifying the field. Except if the
603  new value is `None`. `None` is special and no attempt should be made
604  to validate it until `lsst.pex.config.Config.validate` is called.
605  - Do not modify the `~lsst.pex.config.Config` instance to contain
606  invalid values.
607  - If the field is modified, update the history of the
608  `lsst.pex.config.field.Field` to reflect the changes.
609 
610  In order to decrease the need to implement this method in derived
611  `~lsst.pex.config.Field` types, value validation is performed in the
612  `lsst.pex.config.Field._validateValue`. If only the validation step
613  differs in the derived `~lsst.pex.config.Field`, it is simpler to
614  implement `lsst.pex.config.Field._validateValue` than to reimplement
615  ``__set__``. More complicated behavior, however, may require
616  reimplementation.
617  """
618  if instance._frozen:
619  raise FieldValidationError(self, instance, "Cannot modify a frozen Config")
620 
621  history = instance._history.setdefault(self.name, [])
622  if value is not None:
623  value = _autocast(value, self.dtype)
624  try:
625  self._validateValue(value)
626  except BaseException as e:
627  raise FieldValidationError(self, instance, str(e))
628 
629  instance._storage[self.name] = value
630  if at is None:
631  at = getCallStack()
632  history.append((value, at, label))
633 

◆ freeze()

def lsst.pex.config.config.Field.freeze (   self,
  instance 
)
inherited
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 in lsst.pipe.tasks.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configDictField.ConfigDictField, and lsst.pex.config.configChoiceField.ConfigChoiceField.

Definition at line 429 of file config.py.

429  def freeze(self, instance):
430  """Make this field read-only (for internal use only).
431 
432  Parameters
433  ----------
434  instance : `lsst.pex.config.Config`
435  The config instance that contains this field.
436 
437  Notes
438  -----
439  Freezing is only relevant for fields that hold subconfigs. Fields which
440  hold subconfigs should freeze each subconfig.
441 
442  **Subclasses should implement this method.**
443  """
444  pass
445 

◆ rename()

def lsst.pex.config.config.Field.rename (   self,
  instance 
)
inherited
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 in lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configDictField.ConfigDictField, and lsst.pex.config.configChoiceField.ConfigChoiceField.

Definition at line 379 of file config.py.

379  def rename(self, instance):
380  """Rename the field in a `~lsst.pex.config.Config` (for internal use
381  only).
382 
383  Parameters
384  ----------
385  instance : `lsst.pex.config.Config`
386  The config instance that contains this field.
387 
388  Notes
389  -----
390  This method is invoked by the `lsst.pex.config.Config` object that
391  contains this field and should not be called directly.
392 
393  Renaming is only relevant for `~lsst.pex.config.Field` instances that
394  hold subconfigs. `~lsst.pex.config.Fields` that hold subconfigs should
395  rename each subconfig with the full field name as generated by
396  `lsst.pex.config.config._joinNamePath`.
397  """
398  pass
399 

◆ save()

def lsst.pex.config.config.Field.save (   self,
  outfile,
  instance 
)
inherited
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 in lsst.pipe.tasks.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configDictField.ConfigDictField, and lsst.pex.config.configChoiceField.ConfigChoiceField.

Definition at line 487 of file config.py.

487  def save(self, outfile, instance):
488  """Save this field to a file (for internal use only).
489 
490  Parameters
491  ----------
492  outfile : file-like object
493  A writeable field handle.
494  instance : `Config`
495  The `Config` instance that contains this field.
496 
497  Notes
498  -----
499  This method is invoked by the `~lsst.pex.config.Config` object that
500  contains this field and should not be called directly.
501 
502  The output consists of the documentation string
503  (`lsst.pex.config.Field.doc`) formatted as a Python comment. The second
504  line is formatted as an assignment: ``{fullname}={value}``.
505 
506  This output can be executed with Python.
507  """
508  value = self.__get__(instance)
509  fullname = _joinNamePath(instance._name, self.name)
510 
511  if self.deprecated and value == self.default:
512  return
513 
514  # write full documentation string as comment lines
515  # (i.e. first character is #)
516  doc = "# " + str(self.doc).replace("\n", "\n# ")
517  if isinstance(value, float) and not math.isfinite(value):
518  # non-finite numbers need special care
519  outfile.write(u"{}\n{}=float('{!r}')\n\n".format(doc, fullname, value))
520  else:
521  outfile.write(u"{}\n{}={!r}\n\n".format(doc, fullname, value))
522 

◆ toDict()

def lsst.pex.config.config.Field.toDict (   self,
  instance 
)
inherited
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 in lsst.pipe.tasks.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.listField.ListField, lsst.pex.config.dictField.DictField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configDictField.ConfigDictField, and lsst.pex.config.configChoiceField.ConfigChoiceField.

Definition at line 523 of file config.py.

523  def toDict(self, instance):
524  """Convert the field value so that it can be set as the value of an
525  item in a `dict` (for internal use only).
526 
527  Parameters
528  ----------
529  instance : `Config`
530  The `Config` that contains this field.
531 
532  Returns
533  -------
534  value : object
535  The field's value. See *Notes*.
536 
537  Notes
538  -----
539  This method invoked by the owning `~lsst.pex.config.Config` object and
540  should not be called directly.
541 
542  Simple values are passed through. Complex data structures must be
543  manipulated. For example, a `~lsst.pex.config.Field` holding a
544  subconfig should, instead of the subconfig object, return a `dict`
545  where the keys are the field names in the subconfig, and the values are
546  the field values in the subconfig.
547  """
548  return self.__get__(instance)
549 

◆ validate()

def lsst.pex.config.config.Field.validate (   self,
  instance 
)
inherited
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 in lsst.pipe.tasks.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.listField.ListField, lsst.pex.config.dictField.DictField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configDictField.ConfigDictField, and lsst.pex.config.configChoiceField.ConfigChoiceField.

Definition at line 400 of file config.py.

400  def validate(self, instance):
401  """Validate the field (for internal use only).
402 
403  Parameters
404  ----------
405  instance : `lsst.pex.config.Config`
406  The config instance that contains this field.
407 
408  Raises
409  ------
410  lsst.pex.config.FieldValidationError
411  Raised if verification fails.
412 
413  Notes
414  -----
415  This method provides basic validation:
416 
417  - Ensures that the value is not `None` if the field is not optional.
418  - Ensures type correctness.
419  - Ensures that the user-provided ``check`` function is valid.
420 
421  Most `~lsst.pex.config.Field` subclasses should call
422  `lsst.pex.config.field.Field.validate` if they re-implement
423  `~lsst.pex.config.field.Field.validate`.
424  """
425  value = self.__get__(instance)
426  if not self.optional and value is None:
427  raise FieldValidationError(self, instance, "Required value cannot be None")
428 

Member Data Documentation

◆ allowed

lsst.pex.config.choiceField.ChoiceField.allowed

Definition at line 72 of file choiceField.py.

◆ check

lsst.pex.config.config.Field.check
inherited

Definition at line 363 of file config.py.

◆ default

lsst.pex.config.config.Field.default
inherited

Definition at line 359 of file config.py.

◆ deprecated

lsst.pex.config.config.Field.deprecated
inherited

Definition at line 350 of file config.py.

◆ doc

lsst.pex.config.config.Field.doc
inherited

Definition at line 346 of file config.py.

◆ dtype

lsst.pex.config.config.Field.dtype
inherited

Definition at line 339 of file config.py.

◆ optional

lsst.pex.config.config.Field.optional
inherited

Definition at line 367 of file config.py.

◆ source

lsst.pex.config.choiceField.ChoiceField.source

Definition at line 89 of file choiceField.py.

◆ supportedTypes

lsst.pex.config.config.Field.supportedTypes = set((str, bool, float, int, complex))
staticinherited

Definition at line 324 of file config.py.


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