lsst.pex.config gc75b51116a+846e1f9efd
Public Member Functions | Public Attributes | List of all members
lsst.pex.config.configurableField.ConfigurableField Class Reference
Inheritance diagram for lsst.pex.config.configurableField.ConfigurableField:
lsst.pex.config.config.Field lsst.pex.config.configurableField.ConfigurableInstance

Public Member Functions

def validateTarget (self, target, ConfigClass)
 
def __init__ (self, doc, target, ConfigClass=None, default=None, check=None, deprecated=None)
 
"ConfigurableField" __get__ (self, None instance, Any owner=None, Any at=None, str label="default")
 
ConfigurableInstance[FieldTypeVar] __get__ (self, Config instance, Any owner=None, Any at=None, str label="default")
 
def __get__ (self, instance, owner=None, at=None, label="default")
 
def __set__ (self, instance, value, at=None, label="assignment")
 
def rename (self, instance)
 
def save (self, outfile, instance)
 
def freeze (self, instance)
 
def toDict (self, instance)
 
def validate (self, 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.configurableField.ConfigurableInstance
def __init__ (self, config, field, at=None, label="default")
 
def apply (self, *args, **kw)
 
def retarget (self, target, ConfigClass=None, at=None, label="retarget")
 
def __getattr__ (self, name)
 
def __setattr__ (self, name, value, at=None, label="assignment")
 
def __delattr__ (self, name, at=None, label="delete")
 
def __reduce__ (self)
 

Public Attributes

 target
 
 ConfigClass
 
- Public Attributes inherited from lsst.pex.config.config.Field
 dtype
 
 doc
 
 deprecated
 
 default
 
 check
 
 optional
 
 source
 

Additional Inherited Members

- Static Public Attributes inherited from lsst.pex.config.config.Field
 supportedTypes = set((str, bool, float, int, complex))
 
- Properties inherited from lsst.pex.config.configurableField.ConfigurableInstance
 target = property(lambda x: x._target)
 
 ConfigClass = property(lambda x: x._ConfigClass)
 
 value = property(lambda x: x._value)
 

Detailed Description

A configuration field (`~lsst.pex.config.Field` subclass) that can be
can be retargeted towards a different configurable (often a
`lsst.pipe.base.Task` subclass).

The ``ConfigurableField`` is often used to configure subtasks, which are
tasks (`~lsst.pipe.base.Task`) called by a parent task.

Parameters
----------
doc : `str`
    A description of the configuration field.
target : configurable class
    The configurable target. Configurables have a ``ConfigClass``
    attribute. Within the task framework, configurables are
    `lsst.pipe.base.Task` subclasses)
ConfigClass : `lsst.pex.config.Config`-type, optional
    The subclass of `lsst.pex.config.Config` expected as the configuration
    class of the ``target``. If ``ConfigClass`` is unset then
    ``target.ConfigClass`` is used.
default : ``ConfigClass``-type, optional
    The default configuration class. Normally this parameter is not set,
    and defaults to ``ConfigClass`` (or ``target.ConfigClass``).
check : callable, optional
    Callable that takes the field's value (the ``target``) as its only
    positional argument, and returns `True` if the ``target`` is valid (and
    `False` otherwise).
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
ConfigChoiceField
ConfigDictField
ConfigField
DictField
Field
ListField
RangeField
RegistryField

Notes
-----
You can use the `ConfigurableInstance.apply` method to construct a
fully-configured configurable.

Constructor & Destructor Documentation

◆ __init__()

def lsst.pex.config.configurableField.ConfigurableField.__init__ (   self,
  doc,
  target,
  ConfigClass = None,
  default = None,
  check = None,
  deprecated = None 
)

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

Member Function Documentation

◆ __deepcopy__()

def lsst.pex.config.configurableField.ConfigurableField.__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!

◆ __get__() [1/3]

ConfigurableInstance[FieldTypeVar] lsst.pex.config.configurableField.ConfigurableField.__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.configurableField.ConfigurableField.__get__ (   self,
  instance,
  owner = None,
  at = None,
  label = "default" 
)

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

◆ __get__() [3/3]

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

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

◆ __set__()

def lsst.pex.config.configurableField.ConfigurableField.__set__ (   self,
  instance,
  value,
  at = None,
  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.configurableField.ConfigurableField.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.configurableField.ConfigurableField.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.configurableField.ConfigurableField.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.configurableField.ConfigurableField.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.configurableField.ConfigurableField.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.

◆ validateTarget()

def lsst.pex.config.configurableField.ConfigurableField.validateTarget (   self,
  target,
  ConfigClass 
)
Validate the target and configuration class.

Parameters
----------
target
    The configurable being verified.
ConfigClass : `lsst.pex.config.Config`-type or `None`
    The configuration class associated with the ``target``. This can
    be `None` if ``target`` has a ``ConfigClass`` attribute.

Raises
------
AttributeError
    Raised if ``ConfigClass`` is `None` and ``target`` does not have a
    ``ConfigClass`` attribute.
TypeError
    Raised if ``ConfigClass`` is not a `~lsst.pex.config.Config`
    subclass.
ValueError
    Raised if:

    - ``target`` is not callable (callables have a ``__call__``
      method).
    - ``target`` is not startically defined (does not have
      ``__module__`` or ``__name__`` attributes).

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