ListField

class lsst.pex.config.ListField(doc, dtype=None, default=None, optional=False, listCheck=None, itemCheck=None, length=None, minLength=None, maxLength=None, deprecated=None)

Bases: Field[List[FieldTypeVar]], Generic[FieldTypeVar]

A configuration field (Field subclass) that contains a list of values of a specific type.

Parameters:
docstr

A description of the field.

dtypeclass, optional

The data type of items in the list. Optional if supplied as typing argument to the class.

defaultsequence, optional

The default items for the field.

optionalbool, optional

Set whether the field is optional. When False, lsst.pex.config.Config.validate will fail if the field’s value is None.

listCheckcallable, optional

A callable that validates the list as a whole.

itemCheckcallable, optional

A callable that validates individual items in the list.

lengthint, optional

If set, this field must contain exactly length number of items.

minLengthint, optional

If set, this field must contain at least minLength number of items.

maxLengthint, optional

If set, this field must contain no more than maxLength number of items.

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.

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 value of this field to a plain list.

validate(instance)

Validate the field.

Attributes Documentation

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

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 value of this field to a plain list.

lsst.pex.config.Config.toDict is the primary user of this method.

Parameters:
instancelsst.pex.config.Config

The config instance that contains this field.

Returns:
list

Plain list of items, or None if the field is not set.

validate(instance)

Validate the field.

Parameters:
instancelsst.pex.config.Config

The config instance that contains this field.

Raises:
lsst.pex.config.FieldValidationError

Raised if:

  • The field is not optional, but the value is None.

  • The list itself does not meet the requirements of the length, minLength, or maxLength attributes.

  • The listCheck callable returns False.

Notes

Individual item checks (itemCheck) are applied when each item is set and are not re-checked by this method.