ConfigurableField

class lsst.pex.config.ConfigurableField(doc, target, ConfigClass=None, default=None, check=None, deprecated=None)

Bases: Field[ConfigurableInstance[FieldTypeVar]]

A configuration field (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 (Task) called by a parent task.

Parameters:

docstr

A description of the configuration field.

targetconfigurable class

The configurable target. Configurables have a ConfigClass attribute. Within the task framework, configurables are lsst.pipe.base.Task subclasses)

ConfigClasslsst.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.

defaultConfigClass-type, optional

The default configuration class. Normally this parameter is not set, and defaults to ConfigClass (or target.ConfigClass).

checkcallable, 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).

deprecatedNone 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.

Attributes Summary

supportedTypes

Supported data types for field values (set of types).

Methods Summary

freeze(instance)	Make this field read-only (for internal use only).
rename(instance)	Rename the field in a Config (for internal use only).
save(outfile, instance)	Save this field to a file (for internal use only).
toDict(instance)	Convert the field value so that it can be set as the value of an item in a dict (for internal use only).
validate(instance)	Validate the field (for internal use only).
validateTarget(target, ConfigClass)	Validate the target and configuration class.

Attributes Documentation

supportedTypes = {<class 'bool'>, <class 'int'>, <class 'str'>, <class 'float'>, <class 'complex'>}

Supported data types for field values (set of types).

Methods Documentation

freeze(instance)

Make this field read-only (for internal use only).

Parameters:

instancelsst.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.

rename(instance)

Rename the field in a Config (for internal use only).

Parameters:

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

save(outfile, instance)

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

Parameters:

outfilefile-like object

A writeable field handle.

instanceConfig

The Config instance that contains this field.

Notes

This method is invoked by the 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.

toDict(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:

instanceConfig

The Config that contains this field.

Returns:

valueobject

The field’s value. See Notes.

Notes

This method invoked by the owning Config object and should not be called directly.

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

validate(instance)

Validate the field (for internal use only).

Parameters:

instancelsst.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 Field subclasses should call lsst.pex.config.Field.validate if they re-implement validate.

validateTarget(target, ConfigClass)

Validate the target and configuration class.

Parameters:

target

The configurable being verified.

ConfigClasslsst.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 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).