LSST Applications g04c3c9f7ca+2075667efa,g1e125bf412+5f448d5fcf,g2079a07aa2+3e9fd84d81,g2305ad1205+b635cf1488,g2bbee38e9b+6c6beb4891,g337abbeb29+6c6beb4891,g33d1c0ed96+6c6beb4891,g3a166c0a6a+6c6beb4891,g50ff169b8f+96c6868917,g52b1c1532d+585e252eca,g591dd9f2cf+42f171e1e6,g5c3423f6d4+d536b04327,g607f77f49a+d536b04327,g6f43f06aed+ca1339dc19,g858d7b2824+d536b04327,g8ee334c5b4+d7f9608c2f,g9963eaa53e+b3dc1655d3,g998f4353bf+d536b04327,g99cad8db69+8ef2408349,g9ddcbc5298+9a081db1e4,ga1e77700b3+2cbb763275,gadfd92a7e4+aec2f3b930,gae0086650b+585e252eca,gb0e22166c9+0e73c8378f,gb3b7280ab2+cb5fdb229e,gbb8dafda3b+a327199e22,gc120e1dc64+88074880ea,gc28159a63d+6c6beb4891,gcdd4ae20e8+bd241b2308,gcde1bda545+903e937d91,gcf0d15dbbd+bd241b2308,gdaeeff99f8+f9a426f77a,gddc38dedce+585e252eca,ge79ae78c31+6c6beb4891,gfbcc870c63+b310236976,w.2024.23
LSST Data Management Base Package
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

Definition at line 310 of file config.py.

Constructor & Destructor Documentation

◆ __init__()

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

Reimplemented in lsst.pex.config.rangeField.RangeField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.choiceField.ChoiceField, lsst.pex.config.configField.ConfigField, lsst.pex.config.listField.ListField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.dictField.DictField, lsst.pex.config.registry.RegistryField, lsst.pex.config.configurableField.ConfigurableField, lsst.pex.config.configChoiceField.ConfigChoiceField, and lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField.

Definition at line 478 of file config.py.

478 def __init__(self, doc, dtype=None, default=None, check=None, optional=False, deprecated=None):
479 if dtype is None:
480 raise ValueError(
481 "dtype must either be supplied as an argument or as a type argument to the class"
482 )
483 if dtype not in self.supportedTypes:
484 raise ValueError("Unsupported Field dtype %s" % _typeStr(dtype))
485
486 source = getStackFrame()
487 self._setup(
488 doc=doc,
489 dtype=dtype,
490 default=default,
491 check=check,
492 optional=optional,
493 source=source,
494 deprecated=deprecated,
495 )
496

Member Function Documentation

◆ __class_getitem__()

lsst.pex.config.config.Field.__class_getitem__ ( cls,
tuple[type, ...] | type | ForwardRef params )

Reimplemented in lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configChoiceField.ConfigChoiceField.

Definition at line 475 of file config.py.

475 def __class_getitem__(cls, params: tuple[type, ...] | type | ForwardRef):
476 return _PexConfigGenericAlias(cls, params)
477

◆ __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.

Definition at line 813 of file config.py.

813 def __delete__(self, instance, at=None, label="deletion"):
814 """Delete an attribute from a `lsst.pex.config.Config` instance.
815
816 Parameters
817 ----------
818 instance : `lsst.pex.config.Config`
819 The config instance that contains this field.
820 at : `list` of `lsst.pex.config.callStack.StackFrame`
821 The call stack (created by
822 `lsst.pex.config.callStack.getCallStack`).
823 label : `str`, optional
824 Event label for the history.
825
826 Notes
827 -----
828 This is invoked by the owning `~lsst.pex.config.Config` object and
829 should not be called directly.
830 """
831 if at is None:
832 at = getCallStack()
833 self.__set__(instance, None, at=at, label=label)
834

◆ __get__() [1/3]

FieldTypeVar lsst.pex.config.config.Field.__get__ ( self,
Config instance,
Any owner = None,
Any at = None,
str label = "default" )

◆ __get__() [2/3]

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.

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

Definition at line 726 of file config.py.

726 def __get__(self, instance, owner=None, at=None, label="default"):
727 """Define how attribute access should occur on the Config instance
728 This is invoked by the owning config object and should not be called
729 directly.
730
731 When the field attribute is accessed on a Config class object, it
732 returns the field object itself in order to allow inspection of
733 Config classes.
734
735 When the field attribute is access on a config instance, the actual
736 value described by the field (and held by the Config instance) is
737 returned.
738 """
739 if instance is None:
740 return self
741 else:
742 # try statements are almost free in python if they succeed
743 try:
744 return instance._storage[self.name]
745 except AttributeError:
746 if not isinstance(instance, Config):
747 return self
748 else:
749 raise AttributeError(
750 f"Config {instance} is missing _storage attribute, likely incorrectly initialized"
751 )
752

◆ __get__() [3/3]

Field[FieldTypeVar] lsst.pex.config.config.Field.__get__ ( self,
None instance,
Any owner = None,
Any at = None,
str label = "default" )

◆ __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.

Definition at line 753 of file config.py.

755 ) -> None:
756 """Set an attribute on the config instance.
757
758 Parameters
759 ----------
760 instance : `lsst.pex.config.Config`
761 The config instance that contains this field.
762 value : obj
763 Value to set on this field.
764 at : `list` of `~lsst.pex.config.callStack.StackFrame` or `None`,\
765 optional
766 The call stack (created by
767 `lsst.pex.config.callStack.getCallStack`).
768 label : `str`, optional
769 Event label for the history.
770
771 Notes
772 -----
773 This method is invoked by the owning `lsst.pex.config.Config` object
774 and should not be called directly.
775
776 Derived `~lsst.pex.config.Field` classes may need to override the
777 behavior. When overriding ``__set__``, `~lsst.pex.config.Field` authors
778 should follow the following rules:
779
780 - Do not allow modification of frozen configs.
781 - Validate the new value **before** modifying the field. Except if the
782 new value is `None`. `None` is special and no attempt should be made
783 to validate it until `lsst.pex.config.Config.validate` is called.
784 - Do not modify the `~lsst.pex.config.Config` instance to contain
785 invalid values.
786 - If the field is modified, update the history of the
787 `lsst.pex.config.field.Field` to reflect the changes.
788
789 In order to decrease the need to implement this method in derived
790 `~lsst.pex.config.Field` types, value validation is performed in the
791 `lsst.pex.config.Field._validateValue`. If only the validation step
792 differs in the derived `~lsst.pex.config.Field`, it is simpler to
793 implement `lsst.pex.config.Field._validateValue` than to reimplement
794 ``__set__``. More complicated behavior, however, may require
795 reimplementation.
796 """
797 if instance._frozen:
798 raise FieldValidationError(self, instance, "Cannot modify a frozen Config")
799
800 history = instance._history.setdefault(self.name, [])
801 if value is not None:
802 value = _autocast(value, self.dtype)
803 try:
804 self._validateValue(value)
805 except BaseException as e:
806 raise FieldValidationError(self, instance, str(e))
807
808 instance._storage[self.name] = value
809 if at is None:
810 at = getCallStack()
811 history.append((value, at, label))
812

◆ _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.

Definition at line 639 of file config.py.

639 def _collectImports(self, instance, imports):
640 """Call the _collectImports method on all config
641 objects the field may own, and union them with the supplied imports
642 set.
643
644 Parameters
645 ----------
646 instance : instance or subclass of `lsst.pex.config.Config`
647 A config object that has this field defined on it
648 imports : `set`
649 Set of python modules that need imported after persistence
650 """
651 pass
652

◆ _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.

Definition at line 835 of file config.py.

835 def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
836 """Compare a field (named `Field.name`) in two
837 `~lsst.pex.config.Config` instances for equality.
838
839 Parameters
840 ----------
841 instance1 : `lsst.pex.config.Config`
842 Left-hand side `Config` instance to compare.
843 instance2 : `lsst.pex.config.Config`
844 Right-hand side `Config` instance to compare.
845 shortcut : `bool`, optional
846 **Unused.**
847 rtol : `float`, optional
848 Relative tolerance for floating point comparisons.
849 atol : `float`, optional
850 Absolute tolerance for floating point comparisons.
851 output : callable, optional
852 A callable that takes a string, used (possibly repeatedly) to
853 report inequalities.
854
855 Notes
856 -----
857 This method must be overridden by more complex `Field` subclasses.
858
859 See Also
860 --------
861 lsst.pex.config.compareScalars
862 """
863 v1 = getattr(instance1, self.name)
864 v2 = getattr(instance2, self.name)
865 name = getComparisonName(
866 _joinNamePath(instance1._name, self.name), _joinNamePath(instance2._name, self.name)
867 )
868 return compareScalars(name, v1, v2, dtype=self.dtype, rtol=rtol, atol=atol, output=output)
869
870

◆ _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.

Definition at line 416 of file config.py.

418 ) -> Mapping[str, Any]:
419 """Parse type annotations into keyword constructor arguments.
420
421 This is a special private method that interprets type arguments (i.e.
422 Field[str]) into keyword arguments to be passed on to the constructor.
423
424 Subclasses of Field can implement this method to customize how they
425 handle turning type parameters into keyword arguments (see DictField
426 for an example)
427
428 Parameters
429 ----------
430 params : `tuple` of `type` or `tuple` of str
431 Parameters passed to the type annotation. These will either be
432 types or strings. Strings are to interpreted as forward references
433 and will be treated as such.
434 kwds : `MutableMapping` with keys of `str` and values of `Any`
435 These are the user supplied keywords that are to be passed to the
436 Field constructor.
437
438 Returns
439 -------
440 kwds : `MutableMapping` with keys of `str` and values of `Any`
441 The mapping of keywords that will be passed onto the constructor
442 of the Field. Should be filled in with any information gleaned
443 from the input parameters.
444
445 Raises
446 ------
447 ValueError
448 Raised if params is of incorrect length.
449 Raised if a forward reference could not be resolved
450 Raised if there is a conflict between params and values in kwds
451 """
452 if len(params) > 1:
453 raise ValueError("Only single type parameters are supported")
454 unpackedParams = params[0]
455 if isinstance(unpackedParams, str):
456 _typ = ForwardRef(unpackedParams)
457 # type ignore below because typeshed seems to be wrong. It
458 # indicates there are only 2 args, as it was in python 3.8, but
459 # 3.9+ takes 3 args. Attempt in old style and new style to
460 # work with both.
461 try:
462 result = _typ._evaluate(globals(), locals(), set()) # type: ignore
463 except TypeError:
464 # python 3.8 path
465 result = _typ._evaluate(globals(), locals())
466 if result is None:
467 raise ValueError("Could not deduce type from input")
468 unpackedParams = cast(type, result)
469 if "dtype" in kwds and kwds["dtype"] != unpackedParams:
470 raise ValueError("Conflicting definition for dtype")
471 elif "dtype" not in kwds:
472 kwds = {**kwds, **{"dtype": unpackedParams}}
473 return kwds
474
daf::base::PropertySet * set
Definition fits.cc:931

◆ _setup()

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

Definition at line 497 of file config.py.

497 def _setup(self, doc, dtype, default, check, optional, source, deprecated):
498 """Set attributes, usually during initialization."""
499 self.dtype = dtype
500 """Data type for the field.
501 """
502
503 if not doc:
504 raise ValueError("Docstring is empty.")
505
506 # append the deprecation message to the docstring.
507 if deprecated is not None:
508 doc = f"{doc} Deprecated: {deprecated}"
509 self.doc = doc
510 """A description of the field (`str`).
511 """
512
513 self.deprecated = deprecated
514 """If not None, a description of why this field is deprecated (`str`).
515 """
516
517 self.__doc__ = f"{doc} (`{dtype.__name__}`"
518 if optional or default is not None:
519 self.__doc__ += f", default ``{default!r}``"
520 self.__doc__ += ")"
521
522 self.default = default
523 """Default value for this field.
524 """
525
526 self.check = check
527 """A user-defined function that validates the value of the field.
528 """
529
530 self.optional = optional
531 """Flag that determines if the field is required to be set (`bool`).
532
533 When `False`, `lsst.pex.config.Config.validate` will fail if the
534 field's value is `None`.
535 """
536
537 self.source = source
538 """The stack frame where this field is defined (`list` of
539 `~lsst.pex.config.callStack.StackFrame`).
540 """
541

◆ _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.

Definition at line 609 of file config.py.

609 def _validateValue(self, value):
610 """Validate a value.
611
612 Parameters
613 ----------
614 value : object
615 The value being validated.
616
617 Raises
618 ------
619 TypeError
620 Raised if the value's type is incompatible with the field's
621 ``dtype``.
622 ValueError
623 Raised if the value is rejected by the ``check`` method.
624 """
625 if value is None:
626 return
627
628 if not isinstance(value, self.dtype):
629 msg = "Value {} is of incorrect type {}. Expected type {}".format(
630 value,
631 _typeStr(value),
632 _typeStr(self.dtype),
633 )
634 raise TypeError(msg)
635 if self.check is not None and not self.check(value):
636 msg = "Value %s is not a valid value" % str(value)
637 raise ValueError(msg)
638

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

Definition at line 592 of file config.py.

592 def freeze(self, instance):
593 """Make this field read-only (for internal use only).
594
595 Parameters
596 ----------
597 instance : `lsst.pex.config.Config`
598 The config instance that contains this field.
599
600 Notes
601 -----
602 Freezing is only relevant for fields that hold subconfigs. Fields which
603 hold subconfigs should freeze each subconfig.
604
605 **Subclasses should implement this method.**
606 """
607 pass
608

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

Definition at line 542 of file config.py.

542 def rename(self, instance):
543 r"""Rename the field in a `~lsst.pex.config.Config` (for internal use
544 only).
545
546 Parameters
547 ----------
548 instance : `lsst.pex.config.Config`
549 The config instance that contains this field.
550
551 Notes
552 -----
553 This method is invoked by the `lsst.pex.config.Config` object that
554 contains this field and should not be called directly.
555
556 Renaming is only relevant for `~lsst.pex.config.Field` instances that
557 hold subconfigs. `~lsst.pex.config.Field`\s that hold subconfigs should
558 rename each subconfig with the full field name as generated by
559 `lsst.pex.config.config._joinNamePath`.
560 """
561 pass
562

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

Definition at line 653 of file config.py.

653 def save(self, outfile, instance):
654 """Save this field to a file (for internal use only).
655
656 Parameters
657 ----------
658 outfile : file-like object
659 A writeable field handle.
660 instance : `~lsst.pex.config.Config`
661 The `~lsst.pex.config.Config` instance that contains this field.
662
663 Notes
664 -----
665 This method is invoked by the `~lsst.pex.config.Config` object that
666 contains this field and should not be called directly.
667
668 The output consists of the documentation string
669 (`lsst.pex.config.Field.doc`) formatted as a Python comment. The second
670 line is formatted as an assignment: ``{fullname}={value}``.
671
672 This output can be executed with Python.
673 """
674 value = self.__get__(instance)
675 fullname = _joinNamePath(instance._name, self.name)
676
677 if self.deprecated and value == self.default:
678 return
679
680 # write full documentation string as comment lines
681 # (i.e. first character is #)
682 doc = "# " + str(self.doc).replace("\n", "\n# ")
683 if isinstance(value, float) and not math.isfinite(value):
684 # non-finite numbers need special care
685 outfile.write(f"{doc}\n{fullname}=float('{value!r}')\n\n")
686 else:
687 outfile.write(f"{doc}\n{fullname}={value!r}\n\n")
688

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

Definition at line 689 of file config.py.

689 def toDict(self, instance):
690 """Convert the field value so that it can be set as the value of an
691 item in a `dict` (for internal use only).
692
693 Parameters
694 ----------
695 instance : `~lsst.pex.config.Config`
696 The `~lsst.pex.config.Config` that contains this field.
697
698 Returns
699 -------
700 value : object
701 The field's value. See *Notes*.
702
703 Notes
704 -----
705 This method invoked by the owning `~lsst.pex.config.Config` object and
706 should not be called directly.
707
708 Simple values are passed through. Complex data structures must be
709 manipulated. For example, a `~lsst.pex.config.Field` holding a
710 subconfig should, instead of the subconfig object, return a `dict`
711 where the keys are the field names in the subconfig, and the values are
712 the field values in the subconfig.
713 """
714 return self.__get__(instance)
715

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

Definition at line 563 of file config.py.

563 def validate(self, instance):
564 """Validate the field (for internal use only).
565
566 Parameters
567 ----------
568 instance : `lsst.pex.config.Config`
569 The config instance that contains this field.
570
571 Raises
572 ------
573 lsst.pex.config.FieldValidationError
574 Raised if verification fails.
575
576 Notes
577 -----
578 This method provides basic validation:
579
580 - Ensures that the value is not `None` if the field is not optional.
581 - Ensures type correctness.
582 - Ensures that the user-provided ``check`` function is valid.
583
584 Most `~lsst.pex.config.Field` subclasses should call
585 `lsst.pex.config.Field.validate` if they re-implement
586 `~lsst.pex.config.Field.validate`.
587 """
588 value = self.__get__(instance)
589 if not self.optional and value is None:
590 raise FieldValidationError(self, instance, "Required value cannot be None")
591

Member Data Documentation

◆ check

lsst.pex.config.config.Field.check

Definition at line 526 of file config.py.

◆ default

lsst.pex.config.config.Field.default

Definition at line 522 of file config.py.

◆ deprecated

lsst.pex.config.config.Field.deprecated

Definition at line 513 of file config.py.

◆ doc

lsst.pex.config.config.Field.doc

Definition at line 509 of file config.py.

◆ dtype

lsst.pex.config.config.Field.dtype

Definition at line 499 of file config.py.

◆ name [1/2]

str lsst.pex.config.config.Field.name
static

Definition at line 406 of file config.py.

◆ name [2/2]

lsst.pex.config.config.Field.name

Definition at line 866 of file config.py.

◆ optional

lsst.pex.config.config.Field.optional

Definition at line 530 of file config.py.

◆ source

lsst.pex.config.config.Field.source

Definition at line 537 of file config.py.

◆ supportedTypes

dict lsst.pex.config.config.Field.supportedTypes = {str, bool, float, int, complex}
static

Definition at line 411 of file config.py.


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