lsst.pex.config g7fdac2220c+8eec0b76e0
Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | Static Public Attributes | 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.configurableField.ConfigurableField lsst.pex.config.dictField.DictField lsst.pex.config.listField.ListField lsst.pex.config.rangeField.RangeField lsst.pex.config.registry.RegistryField lsst.pex.config.configDictField.ConfigDictField

Public Member Functions

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

Public Attributes

 dtype
 
 doc
 
 deprecated
 
 default
 
 check
 
 optional
 
 source
 

Static Public Attributes

 supportedTypes = set((str, bool, float, int, complex))
 

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__()

def 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__()

def 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,
Optional[FieldTypeVar]  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`
    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.configChoiceField.ConfigChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.listField.ListField, lsst.pex.config.dictField.DictField, and lsst.pex.config.configurableField.ConfigurableField.

◆ freeze()

def 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, and lsst.pex.config.configurableField.ConfigurableField.

◆ rename()

def 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.Fields` 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.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, and lsst.pex.config.configurableField.ConfigurableField.

◆ save()

def 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 : `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.

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, and lsst.pex.config.configurableField.ConfigurableField.

◆ toDict()

def 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 : `Config`
    The `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.configurableField.ConfigurableField, lsst.pex.config.dictField.DictField, and lsst.pex.config.listField.ListField.

◆ validate()

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

Reimplemented in 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: