LSST Applications g1653933729+a8ce1bb630,g171997e3ee+76e92115be,g1a997c3884+a8ce1bb630,g28da252d5a+4013ff5194,g2bbee38e9b+d6d0f9f6ae,g2bc492864f+d6d0f9f6ae,g2cdde0e794+ccb74358b7,g3156d2b45e+07302053f8,g347aa1857d+d6d0f9f6ae,g35bb328faa+a8ce1bb630,g3a166c0a6a+d6d0f9f6ae,g3e281a1b8c+130fae20e3,g4005a62e65+17cd334064,g414038480c+c9f68e2a12,g41af890bb2+3e1f62f438,g4e1a3235cc+9db7d56ad0,g7b55021d1b+7b623691d5,g80478fca09+334cc8d2bd,g82479be7b0+b568f6b267,g858d7b2824+37b39d8760,g9125e01d80+a8ce1bb630,ga5288a1d22+11cb34fefe,gae0086650b+a8ce1bb630,gb4ec7eb0ab+37b39d8760,gb58c049af0+d64f4d3760,gc081298178+284e133171,gc28159a63d+d6d0f9f6ae,gcf0d15dbbd+00fe2e0b07,gd6b7c0dfd1+8b62435e69,gda3e153d99+37b39d8760,gda6a2b7d83+00fe2e0b07,gdaeeff99f8+1711a396fd,gdd5a9049c5+23f3b3239a,ge2409df99d+5d9f551a54,ge33fd446bb+37b39d8760,ge79ae78c31+d6d0f9f6ae,gf0baf85859+2dea8344a2,gf5289d68f6+3777f3df5e,w.2024.41
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 298 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 461 of file config.py.

461 def __init__(self, doc, dtype=None, default=None, check=None, optional=False, deprecated=None):
462 if dtype is None:
463 raise ValueError(
464 "dtype must either be supplied as an argument or as a type argument to the class"
465 )
466 if dtype not in self.supportedTypes:
467 raise ValueError(f"Unsupported Field dtype {_typeStr(dtype)}")
468
469 source = getStackFrame()
470 self._setup(
471 doc=doc,
472 dtype=dtype,
473 default=default,
474 check=check,
475 optional=optional,
476 source=source,
477 deprecated=deprecated,
478 )
479

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 458 of file config.py.

458 def __class_getitem__(cls, params: tuple[type, ...] | type | ForwardRef):
459 return _PexConfigGenericAlias(cls, params)
460

◆ __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 794 of file config.py.

794 def __delete__(self, instance, at=None, label="deletion"):
795 """Delete an attribute from a `lsst.pex.config.Config` instance.
796
797 Parameters
798 ----------
799 instance : `lsst.pex.config.Config`
800 The config instance that contains this field.
801 at : `list` of `lsst.pex.config.callStack.StackFrame`
802 The call stack (created by
803 `lsst.pex.config.callStack.getCallStack`).
804 label : `str`, optional
805 Event label for the history.
806
807 Notes
808 -----
809 This is invoked by the owning `~lsst.pex.config.Config` object and
810 should not be called directly.
811 """
812 if at is None:
813 at = getCallStack()
814 self.__set__(instance, None, at=at, label=label)
815

◆ __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 707 of file config.py.

707 def __get__(self, instance, owner=None, at=None, label="default"):
708 """Define how attribute access should occur on the Config instance
709 This is invoked by the owning config object and should not be called
710 directly.
711
712 When the field attribute is accessed on a Config class object, it
713 returns the field object itself in order to allow inspection of
714 Config classes.
715
716 When the field attribute is access on a config instance, the actual
717 value described by the field (and held by the Config instance) is
718 returned.
719 """
720 if instance is None:
721 return self
722 else:
723 # try statements are almost free in python if they succeed
724 try:
725 return instance._storage[self.name]
726 except AttributeError:
727 if not isinstance(instance, Config):
728 return self
729 else:
730 raise AttributeError(
731 f"Config {instance} is missing _storage attribute, likely incorrectly initialized"
732 )
733

◆ __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 734 of file config.py.

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

◆ _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 620 of file config.py.

620 def _collectImports(self, instance, imports):
621 """Call the _collectImports method on all config
622 objects the field may own, and union them with the supplied imports
623 set.
624
625 Parameters
626 ----------
627 instance : instance or subclass of `lsst.pex.config.Config`
628 A config object that has this field defined on it
629 imports : `set`
630 Set of python modules that need imported after persistence
631 """
632 pass
633

◆ _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 816 of file config.py.

816 def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
817 """Compare a field (named `Field.name`) in two
818 `~lsst.pex.config.Config` instances for equality.
819
820 Parameters
821 ----------
822 instance1 : `lsst.pex.config.Config`
823 Left-hand side `Config` instance to compare.
824 instance2 : `lsst.pex.config.Config`
825 Right-hand side `Config` instance to compare.
826 shortcut : `bool`, optional
827 **Unused.**
828 rtol : `float`, optional
829 Relative tolerance for floating point comparisons.
830 atol : `float`, optional
831 Absolute tolerance for floating point comparisons.
832 output : callable, optional
833 A callable that takes a string, used (possibly repeatedly) to
834 report inequalities.
835
836 Notes
837 -----
838 This method must be overridden by more complex `Field` subclasses.
839
840 See Also
841 --------
842 lsst.pex.config.compareScalars
843 """
844 v1 = getattr(instance1, self.name)
845 v2 = getattr(instance2, self.name)
846 name = getComparisonName(
847 _joinNamePath(instance1._name, self.name), _joinNamePath(instance2._name, self.name)
848 )
849 return compareScalars(name, v1, v2, dtype=self.dtype, rtol=rtol, atol=atol, output=output)
850
851

◆ _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 404 of file config.py.

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

◆ _setup()

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

Definition at line 480 of file config.py.

480 def _setup(self, doc, dtype, default, check, optional, source, deprecated):
481 """Set attributes, usually during initialization."""
482 self.dtype = dtype
483 """Data type for the field.
484 """
485
486 if not doc:
487 raise ValueError("Docstring is empty.")
488
489 # append the deprecation message to the docstring.
490 if deprecated is not None:
491 doc = f"{doc} Deprecated: {deprecated}"
492 self.doc = doc
493 """A description of the field (`str`).
494 """
495
496 self.deprecated = deprecated
497 """If not None, a description of why this field is deprecated (`str`).
498 """
499
500 self.__doc__ = f"{doc} (`{dtype.__name__}`"
501 if optional or default is not None:
502 self.__doc__ += f", default ``{default!r}``"
503 self.__doc__ += ")"
504
505 self.default = default
506 """Default value for this field.
507 """
508
509 self.check = check
510 """A user-defined function that validates the value of the field.
511 """
512
513 self.optional = optional
514 """Flag that determines if the field is required to be set (`bool`).
515
516 When `False`, `lsst.pex.config.Config.validate` will fail if the
517 field's value is `None`.
518 """
519
520 self.source = source
521 """The stack frame where this field is defined (`list` of
522 `~lsst.pex.config.callStack.StackFrame`).
523 """
524

◆ _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 592 of file config.py.

592 def _validateValue(self, value):
593 """Validate a value.
594
595 Parameters
596 ----------
597 value : object
598 The value being validated.
599
600 Raises
601 ------
602 TypeError
603 Raised if the value's type is incompatible with the field's
604 ``dtype``.
605 ValueError
606 Raised if the value is rejected by the ``check`` method.
607 """
608 if value is None:
609 return
610
611 if not isinstance(value, self.dtype):
612 msg = (
613 f"Value {value} is of incorrect type {_typeStr(value)}. Expected type {_typeStr(self.dtype)}"
614 )
615 raise TypeError(msg)
616 if self.check is not None and not self.check(value):
617 msg = f"Value {value} is not a valid value"
618 raise ValueError(msg)
619

◆ 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 575 of file config.py.

575 def freeze(self, instance):
576 """Make this field read-only (for internal use only).
577
578 Parameters
579 ----------
580 instance : `lsst.pex.config.Config`
581 The config instance that contains this field.
582
583 Notes
584 -----
585 Freezing is only relevant for fields that hold subconfigs. Fields which
586 hold subconfigs should freeze each subconfig.
587
588 **Subclasses should implement this method.**
589 """
590 pass
591

◆ 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 525 of file config.py.

525 def rename(self, instance):
526 r"""Rename the field in a `~lsst.pex.config.Config` (for internal use
527 only).
528
529 Parameters
530 ----------
531 instance : `lsst.pex.config.Config`
532 The config instance that contains this field.
533
534 Notes
535 -----
536 This method is invoked by the `lsst.pex.config.Config` object that
537 contains this field and should not be called directly.
538
539 Renaming is only relevant for `~lsst.pex.config.Field` instances that
540 hold subconfigs. `~lsst.pex.config.Field`\s that hold subconfigs should
541 rename each subconfig with the full field name as generated by
542 `lsst.pex.config.config._joinNamePath`.
543 """
544 pass
545

◆ 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 634 of file config.py.

634 def save(self, outfile, instance):
635 """Save this field to a file (for internal use only).
636
637 Parameters
638 ----------
639 outfile : file-like object
640 A writeable field handle.
641 instance : `~lsst.pex.config.Config`
642 The `~lsst.pex.config.Config` instance that contains this field.
643
644 Notes
645 -----
646 This method is invoked by the `~lsst.pex.config.Config` object that
647 contains this field and should not be called directly.
648
649 The output consists of the documentation string
650 (`lsst.pex.config.Field.doc`) formatted as a Python comment. The second
651 line is formatted as an assignment: ``{fullname}={value}``.
652
653 This output can be executed with Python.
654 """
655 value = self.__get__(instance)
656 fullname = _joinNamePath(instance._name, self.name)
657
658 if self.deprecated and value == self.default:
659 return
660
661 # write full documentation string as comment lines
662 # (i.e. first character is #)
663 doc = "# " + str(self.doc).replace("\n", "\n# ")
664 if isinstance(value, float) and not math.isfinite(value):
665 # non-finite numbers need special care
666 outfile.write(f"{doc}\n{fullname}=float('{value!r}')\n\n")
667 else:
668 outfile.write(f"{doc}\n{fullname}={value!r}\n\n")
669

◆ 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 670 of file config.py.

670 def toDict(self, instance):
671 """Convert the field value so that it can be set as the value of an
672 item in a `dict` (for internal use only).
673
674 Parameters
675 ----------
676 instance : `~lsst.pex.config.Config`
677 The `~lsst.pex.config.Config` that contains this field.
678
679 Returns
680 -------
681 value : object
682 The field's value. See *Notes*.
683
684 Notes
685 -----
686 This method invoked by the owning `~lsst.pex.config.Config` object and
687 should not be called directly.
688
689 Simple values are passed through. Complex data structures must be
690 manipulated. For example, a `~lsst.pex.config.Field` holding a
691 subconfig should, instead of the subconfig object, return a `dict`
692 where the keys are the field names in the subconfig, and the values are
693 the field values in the subconfig.
694 """
695 return self.__get__(instance)
696

◆ 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 546 of file config.py.

546 def validate(self, instance):
547 """Validate the field (for internal use only).
548
549 Parameters
550 ----------
551 instance : `lsst.pex.config.Config`
552 The config instance that contains this field.
553
554 Raises
555 ------
556 lsst.pex.config.FieldValidationError
557 Raised if verification fails.
558
559 Notes
560 -----
561 This method provides basic validation:
562
563 - Ensures that the value is not `None` if the field is not optional.
564 - Ensures type correctness.
565 - Ensures that the user-provided ``check`` function is valid.
566
567 Most `~lsst.pex.config.Field` subclasses should call
568 `lsst.pex.config.Field.validate` if they re-implement
569 `~lsst.pex.config.Field.validate`.
570 """
571 value = self.__get__(instance)
572 if not self.optional and value is None:
573 raise FieldValidationError(self, instance, "Required value cannot be None")
574

Member Data Documentation

◆ check

lsst.pex.config.config.Field.check

Definition at line 509 of file config.py.

◆ default

lsst.pex.config.config.Field.default

Definition at line 505 of file config.py.

◆ deprecated

lsst.pex.config.config.Field.deprecated

Definition at line 496 of file config.py.

◆ doc

lsst.pex.config.config.Field.doc

Definition at line 492 of file config.py.

◆ dtype

lsst.pex.config.config.Field.dtype

Definition at line 482 of file config.py.

◆ name [1/2]

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

Definition at line 394 of file config.py.

◆ name [2/2]

lsst.pex.config.config.Field.name

Definition at line 847 of file config.py.

◆ optional

lsst.pex.config.config.Field.optional

Definition at line 513 of file config.py.

◆ source

lsst.pex.config.config.Field.source

Definition at line 520 of file config.py.

◆ supportedTypes

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

Definition at line 399 of file config.py.


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