Field¶

class lsst.pex.config.Field(doc, dtype=None, default=None, check=None, optional=False, deprecated=None)¶

Bases: Generic[FieldTypeVar]

A field in a Config that supports int, float, complex, bool, and str data types.

Parameters:

docstr: A description of the field for users.
dtypetype, optional: The field’s data type. Field only supports basic data types: int, float, complex, bool, and str. See Field.supportedTypes. Optional if supplied as a typing argument to the class.
defaultobject, optional: The field’s default value.
checkcallable, optional: A callable that is called with the field’s value. This callable should return False if the value is invalid. More complex inter-field validation can be written as part of the lsst.pex.config.Config.validate method.
optionalbool, optional: This sets whether the field is considered optional, and therefore doesn’t need to be set by the user. When False, lsst.pex.config.Config.validate fails if the field’s value is None.
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.

Raises:

ValueError: Raised when the dtype parameter is not one of the supported types (see Field.supportedTypes).

See also

ChoiceField
ConfigChoiceField
ConfigDictField
ConfigField
ConfigurableField
DictField
ListField
RangeField
RegistryField

Notes

Field instances (including those of any subclass of Field) are used as class attributes of Config subclasses (see the example, below). Field attributes work like the property attributes of classes that implement custom setters and getters. Field attributes belong to the class, but operate on the instance. Formally speaking, Field attributes are descriptors.

When you access a Field attribute on a Config instance, you don’t get the Field instance itself. Instead, you get the value of that field, which might be a simple type (int, float, str, bool) or a custom container type (like a lsst.pex.config.List) depending on the field’s type. See the example, below.

Fields can be annotated with a type similar to other python classes (python specification here ). See the name field in the Config example below for an example of this. Unlike most other uses in python, this has an effect at type checking and runtime. If the type is specified with a class annotation, it will be used as the value of the dtype in the Field and there is no need to specify it as an argument during instantiation.

There are Some notes on dtype through type annotation syntax. Type annotation syntax supports supplying the argument as a string of a type name. i.e. “float”, but this cannot be used to resolve circular references. Type annotation syntax can be used on an identifier in addition to Class assignment i.e. variable: Field[str] = Config.someField vs someField = Field[str](doc="some doc"). However, this syntax is only useful for annotating the type of the identifier (i.e. variable in previous example) and does nothing for assigning the dtype of the ``Field.

Examples

Instances of Field should be used as class attributes of lsst.pex.config.Config subclasses:

>>> from lsst.pex.config import Config, Field
>>> class Example(Config):
...     myInt = Field("An integer field.", int, default=0)
...     name = Field[str](doc="A string Field")
...
>>> print(config.myInt)
0
>>> config.myInt = 5
>>> print(config.myInt)
5

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

Attributes Documentation

supportedTypes = {<class 'str'>, <class 'bool'>, <class 'int'>, <class 'complex'>, <class 'float'>}¶: 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.Field.validate if they re-implement validate.

Navigation

Field¶