Field¶
-
class
lsst.pex.config.
Field
(doc, dtype, default=None, check=None, optional=False, deprecated=None)¶ Bases:
object
A field in a
Config
that supportsint
,float
,complex
,bool
, andstr
data types.Parameters: - doc :
str
A description of the field for users.
- dtype : type
The field’s data type.
Field
only supports basic data types:int
,float
,complex
,bool
, andstr
. SeeField.supportedTypes
.- default : object, optional
The field’s default value.
- check : callable, 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 thelsst.pex.config.Config.validate
method.- optional :
bool
, 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 isNone
.- 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.
Raises: - ValueError
Raised when the
dtype
parameter is not one of the supported types (seeField.supportedTypes
).
See also
ChoiceField
,ConfigChoiceField
,ConfigDictField
,ConfigField
,ConfigurableField
,DictField
,ListField
,RangeField
,RegistryField
Notes
Field
instances (including those of any subclass ofField
) are used as class attributes ofConfig
subclasses (see the example, below).Field
attributes work like theproperty
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 aConfig
instance, you don’t get theField
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 alsst.pex.config.List
) depending on the field’s type. See the example, below.Examples
Instances of
Field
should be used as class attributes oflsst.pex.config.Config
subclasses:>>> from lsst.pex.config import Config, Field >>> class Example(Config): ... myInt = Field("An integer field.", int, default=0) ... >>> 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 'complex'>, <class 'int'>, <class 'float'>, <class 'bool'>, <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: - 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.
- instance :
-
rename
(instance)¶ Rename the field in a
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
Field
instances that hold subconfigs.Fields
that hold subconfigs should rename each subconfig with the full field name as generated bylsst.pex.config.config._joinNamePath
.- instance :
-
save
(outfile, instance)¶ Save this field to a file (for internal use only).
Parameters: 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: Returns: - value : object
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 adict
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: - 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
Field
subclasses should calllsst.pex.config.field.Field.validate
if they re-implementvalidate
.- instance :
- doc :