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) | |
| _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 800 of file config.py.
800 def __delete__(self, instance, at=None, label="deletion"):
801 """Delete an attribute from a `lsst.pex.config.Config` instance.
802
803 Parameters
804 ----------
805 instance : `lsst.pex.config.Config`
806 The config instance that contains this field.
807 at : `list` of `lsst.pex.config.callStack.StackFrame`
808 The call stack (created by
809 `lsst.pex.config.callStack.getCallStack`).
810 label : `str`, optional
811 Event label for the history.
812
813 Notes
814 -----
815 This is invoked by the owning `~lsst.pex.config.Config` object and
816 should not be called directly.
817 """
818 if at is None:
819 at = getCallStack()
820 self.__set__(instance, None, at=at, label=label)
821
◆ __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 713 of file config.py.
713 def __get__(self, instance, owner=None, at=None, label="default"):
714 """Define how attribute access should occur on the Config instance
715 This is invoked by the owning config object and should not be called
716 directly.
717
718 When the field attribute is accessed on a Config class object, it
719 returns the field object itself in order to allow inspection of
720 Config classes.
721
722 When the field attribute is access on a config instance, the actual
723 value described by the field (and held by the Config instance) is
724 returned.
725 """
726 if instance is None:
727 return self
728 else:
729 # try statements are almost free in python if they succeed
730 try:
731 return instance._storage[self.name]
732 except AttributeError:
733 if not isinstance(instance, Config):
734 return self
735 else:
736 raise AttributeError(
737 f"Config {instance} is missing _storage attribute, likely incorrectly initialized"
738 ) from None
739
◆ __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 740 of file config.py.
742 ) -> None:
743 """Set an attribute on the config instance.
744
745 Parameters
746 ----------
747 instance : `lsst.pex.config.Config`
748 The config instance that contains this field.
749 value : obj
750 Value to set on this field.
751 at : `list` of `~lsst.pex.config.callStack.StackFrame` or `None`,\
752 optional
753 The call stack (created by
754 `lsst.pex.config.callStack.getCallStack`).
755 label : `str`, optional
756 Event label for the history.
757
758 Notes
759 -----
760 This method is invoked by the owning `lsst.pex.config.Config` object
761 and should not be called directly.
762
763 Derived `~lsst.pex.config.Field` classes may need to override the
764 behavior. When overriding ``__set__``, `~lsst.pex.config.Field` authors
765 should follow the following rules:
766
767 - Do not allow modification of frozen configs.
768 - Validate the new value **before** modifying the field. Except if the
769 new value is `None`. `None` is special and no attempt should be made
770 to validate it until `lsst.pex.config.Config.validate` is called.
771 - Do not modify the `~lsst.pex.config.Config` instance to contain
772 invalid values.
773 - If the field is modified, update the history of the
774 `lsst.pex.config.field.Field` to reflect the changes.
775
776 In order to decrease the need to implement this method in derived
777 `~lsst.pex.config.Field` types, value validation is performed in the
778 `lsst.pex.config.Field._validateValue`. If only the validation step
779 differs in the derived `~lsst.pex.config.Field`, it is simpler to
780 implement `lsst.pex.config.Field._validateValue` than to reimplement
781 ``__set__``. More complicated behavior, however, may require
782 reimplementation.
783 """
784 if instance._frozen:
785 raise FieldValidationError(self, instance, "Cannot modify a frozen Config")
786
787 history = instance._history.setdefault(self.name, [])
788 if value is not None:
789 value = _autocast(value, self.dtype)
790 try:
791 self._validateValue(value)
792 except BaseException as e:
793 raise FieldValidationError(self, instance, str(e)) from e
794
795 instance._storage[self.name] = value
796 if at is None:
797 at = getCallStack()
798 history.append((value, at, label))
799
◆ _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 822 of file config.py.
822 def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
823 """Compare a field (named `Field.name`) in two
824 `~lsst.pex.config.Config` instances for equality.
825
826 Parameters
827 ----------
828 instance1 : `lsst.pex.config.Config`
829 Left-hand side `Config` instance to compare.
830 instance2 : `lsst.pex.config.Config`
831 Right-hand side `Config` instance to compare.
832 shortcut : `bool`, optional
833 **Unused.**
834 rtol : `float`, optional
835 Relative tolerance for floating point comparisons.
836 atol : `float`, optional
837 Absolute tolerance for floating point comparisons.
838 output : callable, optional
839 A callable that takes a string, used (possibly repeatedly) to
840 report inequalities.
841
842 Notes
843 -----
844 This method must be overridden by more complex `Field` subclasses.
845
846 See Also
847 --------
848 lsst.pex.config.compareScalars
849 """
850 v1 = getattr(instance1, self.name)
851 v2 = getattr(instance2, self.name)
852 name = getComparisonName(
853 _joinNamePath(instance1._name, self.name), _joinNamePath(instance2._name, self.name)
854 )
855 return compareScalars(name, v1, v2, dtype=self.dtype, rtol=rtol, atol=atol, output=output)
856
857
◆ _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-10.0.0/Linux64/pex_config/ge82c20c137+e12a08b75a/python/lsst/pex/config/config.py
Generated on Wed Mar 26 2025 08:43:38 for LSST Applications by
1.13.2