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:
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 = dtype | |
| doc = doc | |
| deprecated = deprecated | |
| default = default | |
| check = check | |
| optional = optional | |
| source = source | |
Static Public Attributes | |
| 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) | |
| Any | _copy_storage (self, Config old, Config new) |
| _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
Constructor & Destructor Documentation
◆ __init__()
| lsst.pex.config.config.Field.__init__ | ( | self, | |
| doc, | |||
| dtype = None, | |||
| default = None, | |||
| check = None, | |||
| optional = False, | |||
| deprecated = None ) |
Definition at line 467 of file config.py.
467 def __init__(self, doc, dtype=None, default=None, check=None, optional=False, deprecated=None):
468 if dtype is None:
469 raise ValueError(
470 "dtype must either be supplied as an argument or as a type argument to the class"
471 )
472 if dtype not in self.supportedTypes:
473 raise ValueError(f"Unsupported Field dtype {_typeStr(dtype)}")
474
475 source = getStackFrame()
476 self._setup(
477 doc=doc,
478 dtype=dtype,
479 default=default,
480 check=check,
481 optional=optional,
482 source=source,
483 deprecated=deprecated,
484 )
485
Member Function Documentation
◆ __class_getitem__()
| lsst.pex.config.config.Field.__class_getitem__ | ( | cls, | |
| tuple[type, ...] | type | ForwardRef | params ) |
◆ __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 808 of file config.py.
808 def __delete__(self, instance, at=None, label="deletion"):
809 """Delete an attribute from a `lsst.pex.config.Config` instance.
810
811 Parameters
812 ----------
813 instance : `lsst.pex.config.Config`
814 The config instance that contains this field.
815 at : `list` of `lsst.pex.config.callStack.StackFrame`
816 The call stack (created by
817 `lsst.pex.config.callStack.getCallStack`).
818 label : `str`, optional
819 Event label for the history.
820
821 Notes
822 -----
823 This is invoked by the owning `~lsst.pex.config.Config` object and
824 should not be called directly.
825 """
826 if at is None:
827 at = getCallStack()
828 self.__set__(instance, None, at=at, label=label)
829
◆ __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.
Definition at line 721 of file config.py.
721 def __get__(self, instance, owner=None, at=None, label="default"):
722 """Define how attribute access should occur on the Config instance
723 This is invoked by the owning config object and should not be called
724 directly.
725
726 When the field attribute is accessed on a Config class object, it
727 returns the field object itself in order to allow inspection of
728 Config classes.
729
730 When the field attribute is access on a config instance, the actual
731 value described by the field (and held by the Config instance) is
732 returned.
733 """
734 if instance is None:
735 return self
736 else:
737 # try statements are almost free in python if they succeed
738 try:
739 return instance._storage[self.name]
740 except AttributeError:
741 if not isinstance(instance, Config):
742 return self
743 else:
744 raise AttributeError(
745 f"Config {instance} is missing _storage attribute, likely incorrectly initialized"
746 ) from None
747
◆ __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.
Definition at line 748 of file config.py.
750 ) -> None:
751 """Set an attribute on the config instance.
752
753 Parameters
754 ----------
755 instance : `lsst.pex.config.Config`
756 The config instance that contains this field.
757 value : obj
758 Value to set on this field.
759 at : `list` of `~lsst.pex.config.callStack.StackFrame` or `None`,\
760 optional
761 The call stack (created by
762 `lsst.pex.config.callStack.getCallStack`).
763 label : `str`, optional
764 Event label for the history.
765
766 Notes
767 -----
768 This method is invoked by the owning `lsst.pex.config.Config` object
769 and should not be called directly.
770
771 Derived `~lsst.pex.config.Field` classes may need to override the
772 behavior. When overriding ``__set__``, `~lsst.pex.config.Field` authors
773 should follow the following rules:
774
775 - Do not allow modification of frozen configs.
776 - Validate the new value **before** modifying the field. Except if the
777 new value is `None`. `None` is special and no attempt should be made
778 to validate it until `lsst.pex.config.Config.validate` is called.
779 - Do not modify the `~lsst.pex.config.Config` instance to contain
780 invalid values.
781 - If the field is modified, update the history of the
782 `lsst.pex.config.field.Field` to reflect the changes.
783
784 In order to decrease the need to implement this method in derived
785 `~lsst.pex.config.Field` types, value validation is performed in the
786 `lsst.pex.config.Field._validateValue`. If only the validation step
787 differs in the derived `~lsst.pex.config.Field`, it is simpler to
788 implement `lsst.pex.config.Field._validateValue` than to reimplement
789 ``__set__``. More complicated behavior, however, may require
790 reimplementation.
791 """
792 if instance._frozen:
793 raise FieldValidationError(self, instance, "Cannot modify a frozen Config")
794
795 history = instance._history.setdefault(self.name, [])
796 if value is not None:
797 value = _autocast(value, self.dtype)
798 try:
799 self._validateValue(value)
800 except BaseException as e:
801 raise FieldValidationError(self, instance, str(e)) from e
802
803 instance._storage[self.name] = value
804 if at is None:
805 at = getCallStack()
806 history.append((value, at, label))
807
◆ _collectImports()
|
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 626 of file config.py.
626 def _collectImports(self, instance, imports):
627 """Call the _collectImports method on all config
628 objects the field may own, and union them with the supplied imports
629 set.
630
631 Parameters
632 ----------
633 instance : instance or subclass of `lsst.pex.config.Config`
634 A config object that has this field defined on it
635 imports : `set`
636 Set of python modules that need imported after persistence
637 """
638 pass
639
◆ _compare()
|
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 830 of file config.py.
830 def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
831 """Compare a field (named `Field.name`) in two
832 `~lsst.pex.config.Config` instances for equality.
833
834 Parameters
835 ----------
836 instance1 : `lsst.pex.config.Config`
837 Left-hand side `Config` instance to compare.
838 instance2 : `lsst.pex.config.Config`
839 Right-hand side `Config` instance to compare.
840 shortcut : `bool`, optional
841 **Unused.**
842 rtol : `float`, optional
843 Relative tolerance for floating point comparisons.
844 atol : `float`, optional
845 Absolute tolerance for floating point comparisons.
846 output : callable, optional
847 A callable that takes a string, used (possibly repeatedly) to
848 report inequalities.
849
850 Notes
851 -----
852 This method must be overridden by more complex `Field` subclasses.
853
854 See Also
855 --------
856 lsst.pex.config.compareScalars
857 """
858 v1 = getattr(instance1, self.name)
859 v2 = getattr(instance2, self.name)
860 name = getComparisonName(
861 _joinNamePath(instance1._name, self.name), _joinNamePath(instance2._name, self.name)
862 )
863 return compareScalars(name, v1, v2, dtype=self.dtype, rtol=rtol, atol=atol, output=output)
864
865
◆ _copy_storage()
Copy the storage for this field in the given field into an object suitable for storage in a new copy of that config. Any frozen storage should be unfrozen.
Reimplemented in 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, and lsst.pex.config.listField.ListField.
Definition at line 703 of file config.py.
703 def _copy_storage(self, old: Config, new: Config) -> Any:
704 """Copy the storage for this field in the given field into an object
705 suitable for storage in a new copy of that config.
706
707 Any frozen storage should be unfrozen.
708 """
709 return copy.deepcopy(old._storage[self.name])
710
◆ _parseTypingArgs()
|
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 410 of file config.py.
412 ) -> Mapping[str, Any]:
413 """Parse type annotations into keyword constructor arguments.
414
415 This is a special private method that interprets type arguments (i.e.
416 Field[str]) into keyword arguments to be passed on to the constructor.
417
418 Subclasses of Field can implement this method to customize how they
419 handle turning type parameters into keyword arguments (see DictField
420 for an example)
421
422 Parameters
423 ----------
424 params : `tuple` of `type` or `tuple` of str
425 Parameters passed to the type annotation. These will either be
426 types or strings. Strings are to interpreted as forward references
427 and will be treated as such.
428 kwds : `MutableMapping` with keys of `str` and values of `Any`
429 These are the user supplied keywords that are to be passed to the
430 Field constructor.
431
432 Returns
433 -------
434 kwds : `MutableMapping` with keys of `str` and values of `Any`
435 The mapping of keywords that will be passed onto the constructor
436 of the Field. Should be filled in with any information gleaned
437 from the input parameters.
438
439 Raises
440 ------
441 ValueError
442 Raised if params is of incorrect length.
443 Raised if a forward reference could not be resolved
444 Raised if there is a conflict between params and values in kwds
445 """
446 if len(params) > 1:
447 raise ValueError("Only single type parameters are supported")
448 unpackedParams = params[0]
449 if isinstance(unpackedParams, str):
450 _typ = ForwardRef(unpackedParams)
451 # type ignore below because typeshed seems to be wrong. It
452 # indicates there are only 2 args, as it was in python 3.8, but
453 # 3.9+ takes 3 args.
454 result = _typ._evaluate(globals(), locals(), recursive_guard=set()) # type: ignore
455 if result is None:
456 raise ValueError("Could not deduce type from input")
457 unpackedParams = cast(type, result)
458 if "dtype" in kwds and kwds["dtype"] != unpackedParams:
459 raise ValueError("Conflicting definition for dtype")
460 elif "dtype" not in kwds:
461 kwds = {**kwds, **{"dtype": unpackedParams}}
462 return kwds
463
◆ _setup()
|
protected |
Set attributes, usually during initialization.
Definition at line 486 of file config.py.
486 def _setup(self, doc, dtype, default, check, optional, source, deprecated):
487 """Set attributes, usually during initialization."""
488 self.dtype = dtype
489 """Data type for the field.
490 """
491
492 if not doc:
493 raise ValueError("Docstring is empty.")
494
495 # append the deprecation message to the docstring.
496 if deprecated is not None:
497 doc = f"{doc} Deprecated: {deprecated}"
498 self.doc = doc
499 """A description of the field (`str`).
500 """
501
502 self.deprecated = deprecated
503 """If not None, a description of why this field is deprecated (`str`).
504 """
505
506 self.__doc__ = f"{doc} (`{dtype.__name__}`"
507 if optional or default is not None:
508 self.__doc__ += f", default ``{default!r}``"
509 self.__doc__ += ")"
510
511 self.default = default
512 """Default value for this field.
513 """
514
515 self.check = check
516 """A user-defined function that validates the value of the field.
517 """
518
519 self.optional = optional
520 """Flag that determines if the field is required to be set (`bool`).
521
522 When `False`, `lsst.pex.config.Config.validate` will fail if the
523 field's value is `None`.
524 """
525
526 self.source = source
527 """The stack frame where this field is defined (`list` of
528 `~lsst.pex.config.callStack.StackFrame`).
529 """
530
◆ _validateValue()
|
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 598 of file config.py.
598 def _validateValue(self, value):
599 """Validate a value.
600
601 Parameters
602 ----------
603 value : object
604 The value being validated.
605
606 Raises
607 ------
608 TypeError
609 Raised if the value's type is incompatible with the field's
610 ``dtype``.
611 ValueError
612 Raised if the value is rejected by the ``check`` method.
613 """
614 if value is None:
615 return
616
617 if not isinstance(value, self.dtype):
618 msg = (
619 f"Value {value} is of incorrect type {_typeStr(value)}. Expected type {_typeStr(self.dtype)}"
620 )
621 raise TypeError(msg)
622 if self.check is not None and not self.check(value):
623 msg = f"Value {value} is not a valid value"
624 raise ValueError(msg)
625
◆ 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 581 of file config.py.
581 def freeze(self, instance):
582 """Make this field read-only (for internal use only).
583
584 Parameters
585 ----------
586 instance : `lsst.pex.config.Config`
587 The config instance that contains this field.
588
589 Notes
590 -----
591 Freezing is only relevant for fields that hold subconfigs. Fields which
592 hold subconfigs should freeze each subconfig.
593
594 **Subclasses should implement this method.**
595 """
596 pass
597
◆ 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.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 531 of file config.py.
531 def rename(self, instance):
532 r"""Rename the field in a `~lsst.pex.config.Config` (for internal use
533 only).
534
535 Parameters
536 ----------
537 instance : `lsst.pex.config.Config`
538 The config instance that contains this field.
539
540 Notes
541 -----
542 This method is invoked by the `lsst.pex.config.Config` object that
543 contains this field and should not be called directly.
544
545 Renaming is only relevant for `~lsst.pex.config.Field` instances that
546 hold subconfigs. `~lsst.pex.config.Field`\s that hold subconfigs should
547 rename each subconfig with the full field name as generated by
548 `lsst.pex.config.config._joinNamePath`.
549 """
550 pass
551
◆ 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 640 of file config.py.
640 def save(self, outfile, instance):
641 """Save this field to a file (for internal use only).
642
643 Parameters
644 ----------
645 outfile : file-like object
646 A writeable field handle.
647 instance : `~lsst.pex.config.Config`
648 The `~lsst.pex.config.Config` instance that contains this field.
649
650 Notes
651 -----
652 This method is invoked by the `~lsst.pex.config.Config` object that
653 contains this field and should not be called directly.
654
655 The output consists of the documentation string
656 (`lsst.pex.config.Field.doc`) formatted as a Python comment. The second
657 line is formatted as an assignment: ``{fullname}={value}``.
658
659 This output can be executed with Python.
660 """
661 value = self.__get__(instance)
662 fullname = _joinNamePath(instance._name, self.name)
663
664 if self.deprecated and value == self.default:
665 return
666
667 # write full documentation string as comment lines
668 # (i.e. first character is #)
669 doc = "# " + str(self.doc).replace("\n", "\n# ")
670 if isinstance(value, float) and not math.isfinite(value):
671 # non-finite numbers need special care
672 outfile.write(f"{doc}\n{fullname}=float('{value!r}')\n\n")
673 else:
674 outfile.write(f"{doc}\n{fullname}={value!r}\n\n")
675
◆ 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 676 of file config.py.
676 def toDict(self, instance):
677 """Convert the field value so that it can be set as the value of an
678 item in a `dict` (for internal use only).
679
680 Parameters
681 ----------
682 instance : `~lsst.pex.config.Config`
683 The `~lsst.pex.config.Config` that contains this field.
684
685 Returns
686 -------
687 value : object
688 The field's value. See *Notes*.
689
690 Notes
691 -----
692 This method invoked by the owning `~lsst.pex.config.Config` object and
693 should not be called directly.
694
695 Simple values are passed through. Complex data structures must be
696 manipulated. For example, a `~lsst.pex.config.Field` holding a
697 subconfig should, instead of the subconfig object, return a `dict`
698 where the keys are the field names in the subconfig, and the values are
699 the field values in the subconfig.
700 """
701 return self.__get__(instance)
702
◆ 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.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 552 of file config.py.
552 def validate(self, instance):
553 """Validate the field (for internal use only).
554
555 Parameters
556 ----------
557 instance : `lsst.pex.config.Config`
558 The config instance that contains this field.
559
560 Raises
561 ------
562 lsst.pex.config.FieldValidationError
563 Raised if verification fails.
564
565 Notes
566 -----
567 This method provides basic validation:
568
569 - Ensures that the value is not `None` if the field is not optional.
570 - Ensures type correctness.
571 - Ensures that the user-provided ``check`` function is valid.
572
573 Most `~lsst.pex.config.Field` subclasses should call
574 `lsst.pex.config.Field.validate` if they re-implement
575 `~lsst.pex.config.Field.validate`.
576 """
577 value = self.__get__(instance)
578 if not self.optional and value is None:
579 raise FieldValidationError(self, instance, "Required value cannot be None")
580
Member Data Documentation
◆ check
◆ default
◆ deprecated
◆ doc
◆ dtype
◆ optional
◆ source
◆ supportedTypes
|
static |
The documentation for this class was generated from the following file:
- /j/snowflake/release/lsstsw/stack/lsst-scipipe-12.0.0/Linux/pex_config/ga9e74d7ce9+43ac651df0/python/lsst/pex/config/config.py
Generated on Sun Nov 2 2025 07:01:53 for LSST Applications by
1.13.2