lsst.pex.config gba4ed39666+e464e2e6f0
Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | List of all members
lsst.pex.config.config.Field Class Reference
Inheritance diagram for lsst.pex.config.config.Field:
lsst.pex.config.choiceField.ChoiceField lsst.pex.config.configChoiceField.ConfigChoiceField lsst.pex.config.configField.ConfigField lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField lsst.pex.config.configurableField.ConfigurableField lsst.pex.config.dictField.DictField lsst.pex.config.listField.ListField lsst.pex.config.rangeField.RangeField

Public Member Functions

 __class_getitem__ (cls, tuple[type,...]|type|ForwardRef params)
 
 __init__ (self, doc, dtype=None, default=None, check=None, optional=False, deprecated=None)
 
 rename (self, instance)
 
 validate (self, instance)
 
 freeze (self, instance)
 
 save (self, outfile, instance)
 
 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")
 
 __get__ (self, instance, owner=None, at=None, label="default")
 
None __set__ (self, Config instance, FieldTypeVar|None value, Any at=None, str label="assignment")
 
 __delete__ (self, instance, at=None, label="deletion")
 

Public Attributes

 dtype
 
 doc
 
 deprecated
 
 default
 
 check
 
 optional
 
 source
 
 name
 

Static Public Attributes

str name
 
dict supportedTypes = {str, bool, float, int, complex}
 

Protected Member Functions

 _setup (self, doc, dtype, default, check, optional, source, deprecated)
 
 _validateValue (self, value)
 
 _collectImports (self, instance, imports)
 
 _compare (self, instance1, instance2, shortcut, rtol, atol, output)
 

Static Protected Member Functions

Mapping[str, Any] _parseTypingArgs (tuple[type,...]|tuple[str,...] params, Mapping[str, Any] kwds)
 

Detailed Description

A field in a `~lsst.pex.config.Config` that supports `int`, `float`,
`complex`, `bool`, and `str` data types.

Parameters
----------
doc : `str`
    A description of the field for users.
dtype : type, 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.
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 the
    `lsst.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 is `None`.
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
    (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 `~lsst.pex.config.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
<https://docs.python.org/3/howto/descriptor.html>`_.

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 <https://peps.python.org/pep-0484/#generics>`_ ).
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

Member Function Documentation

◆ __delete__()

lsst.pex.config.config.Field.__delete__ ( self,
instance,
at = None,
label = "deletion" )
Delete an attribute from a `lsst.pex.config.Config` instance.

Parameters
----------
instance : `lsst.pex.config.Config`
    The config instance that contains 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 is invoked by the owning `~lsst.pex.config.Config` object and
should not be called directly.

◆ __get__()

lsst.pex.config.config.Field.__get__ ( self,
instance,
owner = None,
at = None,
label = "default" )
Define how attribute access should occur on the Config instance
This is invoked by the owning config object and should not be called
directly.

When the field attribute is accessed on a Config class object, it
returns the field object itself in order to allow inspection of
Config classes.

When the field attribute is access on a config instance, the actual
value described by the field (and held by the Config instance) is
returned.

◆ __set__()

None lsst.pex.config.config.Field.__set__ ( self,
Config instance,
FieldTypeVar | None value,
Any at = None,
str 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` or `None`,\
        optional
    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 in lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.listField.ListField, lsst.pex.config.dictField.DictField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.

◆ _collectImports()

lsst.pex.config.config.Field._collectImports ( self,
instance,
imports )
protected
Call the _collectImports method on all config
objects the field may own, and union them with the supplied imports
set.

Parameters
----------
instance : instance or subclass of `lsst.pex.config.Config`
    A config object that has this field defined on it
imports : `set`
    Set of python modules that need imported after persistence

Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.

◆ _compare()

lsst.pex.config.config.Field._compare ( self,
instance1,
instance2,
shortcut,
rtol,
atol,
output )
protected
Compare a field (named `Field.name`) in two
`~lsst.pex.config.Config` instances for equality.

Parameters
----------
instance1 : `lsst.pex.config.Config`
    Left-hand side `Config` instance to compare.
instance2 : `lsst.pex.config.Config`
    Right-hand side `Config` instance to compare.
shortcut : `bool`, optional
    **Unused.**
rtol : `float`, optional
    Relative tolerance for floating point comparisons.
atol : `float`, optional
    Absolute tolerance for floating point comparisons.
output : callable, optional
    A callable that takes a string, used (possibly repeatedly) to
    report inequalities.

Notes
-----
This method must be overridden by more complex `Field` subclasses.

See Also
--------
lsst.pex.config.compareScalars

Reimplemented in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.dictField.DictField, and lsst.pex.config.listField.ListField.

◆ _parseTypingArgs()

Mapping[str, Any] lsst.pex.config.config.Field._parseTypingArgs ( tuple[type, ...] | tuple[str, ...] params,
Mapping[str, Any] kwds )
staticprotected
Parse type annotations into keyword constructor arguments.

This is a special private method that interprets type arguments (i.e.
Field[str]) into keyword arguments to be passed on to the constructor.

Subclasses of Field can implement this method to customize how they
handle turning type parameters into keyword arguments (see DictField
for an example)

Parameters
----------
params : `tuple` of `type` or `tuple` of str
    Parameters passed to the type annotation. These will either be
    types or strings. Strings are to interpreted as forward references
    and will be treated as such.
kwds : `MutableMapping` with keys of `str` and values of `Any`
    These are the user supplied keywords that are to be passed to the
    Field constructor.

Returns
-------
kwds : `MutableMapping` with keys of `str` and values of `Any`
    The mapping of keywords that will be passed onto the constructor
    of the Field. Should be filled in with any information gleaned
    from the input parameters.

Raises
------
ValueError
    Raised if params is of incorrect length.
    Raised if a forward reference could not be resolved
    Raised if there is a conflict between params and values in kwds

Reimplemented in lsst.pex.config.configurableField.ConfigurableField, and lsst.pex.config.dictField.DictField.

◆ _setup()

lsst.pex.config.config.Field._setup ( self,
doc,
dtype,
default,
check,
optional,
source,
deprecated )
protected
Set attributes, usually during initialization.

◆ _validateValue()

lsst.pex.config.config.Field._validateValue ( self,
value )
protected
Validate a value.

Parameters
----------
value : object
    The value being validated.

Raises
------
TypeError
    Raised if the value's type is incompatible with the field's
    ``dtype``.
ValueError
    Raised if the value is rejected by the ``check`` method.

Reimplemented in lsst.pex.config.choiceField.ChoiceField, and lsst.pex.config.rangeField.RangeField.

◆ freeze()

lsst.pex.config.config.Field.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 in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.

◆ rename()

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

Reimplemented in lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, and lsst.pex.config.configurableField.ConfigurableField.

◆ save()

lsst.pex.config.config.Field.save ( self,
outfile,
instance )
Save this field to a file (for internal use only).

Parameters
----------
outfile : file-like object
    A writeable field handle.
instance : `~lsst.pex.config.Config`
    The `~lsst.pex.config.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 in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.

◆ toDict()

lsst.pex.config.config.Field.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 : `~lsst.pex.config.Config`
    The `~lsst.pex.config.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 in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.dictField.DictField, and lsst.pex.config.listField.ListField.

◆ validate()

lsst.pex.config.config.Field.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.validate` if they re-implement
`~lsst.pex.config.Field.validate`.

Reimplemented in lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.dictField.DictField, and lsst.pex.config.listField.ListField.


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