Public Member Functions |
Public Attributes |
Static Public Attributes |
Protected Member Functions |
Static Protected Member Functions |
List of all members
lsst.pex.config.configField.ConfigField Class Reference
Inheritance diagram for lsst.pex.config.configField.ConfigField:
Public Member Functions | |
| __init__ (self, doc, dtype=None, default=None, check=None, deprecated=None) | |
| "ConfigField[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") |
| rename (self, instance) | |
| save (self, outfile, instance) | |
| freeze (self, instance) | |
| toDict (self, instance) | |
| validate (self, instance) | |
| __class_getitem__ (cls, tuple[type,...]|type|ForwardRef params) | |
| __delete__ (self, instance, at=None, label="deletion") | |
Public Attributes | |
| name | |
| 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 | |
| _collectImports (self, instance, imports) | |
| _compare (self, instance1, instance2, shortcut, rtol, atol, output) | |
| _setup (self, doc, dtype, default, check, optional, source, deprecated) | |
| _validateValue (self, value) | |
Static Protected Member Functions | |
| Mapping[str, Any] | _parseTypingArgs (tuple[type,...]|tuple[str,...] params, Mapping[str, Any] kwds) |
Detailed Description
A configuration field (`~lsst.pex.config.Field` subclass) that takes a
`~lsst.pex.config.Config`-type as a value.
Parameters
----------
doc : `str`
A description of the configuration field.
dtype : `lsst.pex.config.Config`-type
The type of the field, which must be a subclass of
`lsst.pex.config.Config`.
default : `lsst.pex.config.Config`, optional
If default is `None`, the field will default to a default-constructed
instance of ``dtype``. Additionally, to allow for fewer deep-copies,
assigning an instance of ``ConfigField`` to ``dtype`` itself, is
considered equivalent to assigning a default-constructed sub-config.
This means that the argument default can be ``dtype``, as well as an
instance of ``dtype``.
check : callable, optional
A callback function that validates the field's value, returning `True`
if the value is valid, and `False` otherwise.
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.
See Also
--------
ChoiceField
ConfigChoiceField
ConfigDictField
ConfigurableField
DictField
Field
ListField
RangeField
RegistryField
Notes
-----
The behavior of this type of field is much like that of the base `Field`
type.
Assigning to ``ConfigField`` will update all of the fields in the
configuration.
Definition at line 37 of file configField.py.
Constructor & Destructor Documentation
◆ __init__()
| lsst.pex.config.configField.ConfigField.__init__ | ( | self, | |
| doc, | |||
| dtype = None, | |||
| default = None, | |||
| check = None, | |||
| deprecated = None ) |
Definition at line 83 of file configField.py.
83 def __init__(self, doc, dtype=None, default=None, check=None, deprecated=None):
84 if dtype is None or not issubclass(dtype, Config):
85 raise ValueError(f"dtype={_typeStr(dtype)} is not a subclass of Config")
86 if default is None:
87 default = dtype
88 source = getStackFrame()
89 self._setup(
90 doc=doc,
91 dtype=dtype,
92 default=default,
93 check=check,
94 optional=False,
95 source=source,
96 deprecated=deprecated,
97 )
98
Member Function Documentation
◆ __class_getitem__()
|
inherited |
◆ __delete__()
|
inherited |
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.configField.ConfigField.__get__ | ( | self, | |
| Config | instance, | ||
| Any | owner = None, | ||
| Any | at = None, | ||
| str | label = "default" ) |
Definition at line 105 of file configField.py.
107 ) -> FieldTypeVar: ...
108
◆ __get__() [2/3]
| lsst.pex.config.configField.ConfigField.__get__ | ( | self, | |
| instance, | |||
| owner = None, | |||
| at = None, | |||
| label = "default" ) |
Definition at line 109 of file configField.py.
109 def __get__(self, instance, owner=None, at=None, label="default"):
110 if instance is None or not isinstance(instance, Config):
111 return self
112 else:
113 value = instance._storage.get(self.name, None)
114 if value is None:
115 at = getCallStack()
116 at.insert(0, self.source)
117 self.__set__(instance, self.default, at=at, label="default")
118 return value
119
◆ __get__() [3/3]
| "ConfigField[FieldTypeVar]" lsst.pex.config.configField.ConfigField.__get__ | ( | self, | |
| None | instance, | ||
| Any | owner = None, | ||
| Any | at = None, | ||
| str | label = "default" ) |
Definition at line 100 of file configField.py.
102 ) -> "ConfigField[FieldTypeVar]": ...
103
◆ __set__()
| None lsst.pex.config.configField.ConfigField.__set__ | ( | self, | |
| Config | instance, | ||
| FieldTypeVar | None | value, | ||
| Any | at = None, | ||
| str | label = "assignment" ) |
Definition at line 120 of file configField.py.
122 ) -> None:
123 if instance._frozen:
124 raise FieldValidationError(self, instance, "Cannot modify a frozen Config")
125 name = _joinNamePath(prefix=instance._name, name=self.name)
126
127 if value != self.dtype and type(value) is not self.dtype:
128 msg = f"Value {value} is of incorrect type {_typeStr(value)}. Expected {_typeStr(self.dtype)}"
129 raise FieldValidationError(self, instance, msg)
130
131 if at is None:
132 at = getCallStack()
133
134 oldValue = instance._storage.get(self.name, None)
135 if oldValue is None:
136 if value == self.dtype:
137 instance._storage[self.name] = self.dtype(__name=name, __at=at, __label=label)
138 else:
139 instance._storage[self.name] = self.dtype(
140 __name=name, __at=at, __label=label, **value._storage
141 )
142 else:
143 if value == self.dtype:
144 value = value()
145 oldValue.update(__at=at, __label=label, **value._storage)
146 history = instance._history.setdefault(self.name, [])
147 history.append(("config value set", at, label))
148
◆ _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 from lsst.pex.config.config.Field.
Definition at line 171 of file configField.py.
171 def _collectImports(self, instance, imports):
172 value = self.__get__(instance)
173 value._collectImports()
174 imports |= value._imports
175
◆ _compare()
|
protected |
Compare two fields for equality.
Used by `ConfigField.compare`.
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`
If `True`, this function returns as soon as an inequality if found.
rtol : `float`
Relative tolerance for floating point comparisons.
atol : `float`
Absolute tolerance for floating point comparisons.
output : callable
A callable that takes a string, used (possibly repeatedly) to
report inequalities.
Returns
-------
isEqual : bool
`True` if the fields are equal, `False` otherwise.
Notes
-----
Floating point comparisons are performed by `numpy.allclose`.
Reimplemented from lsst.pex.config.config.Field.
Definition at line 278 of file configField.py.
278 def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
279 """Compare two fields for equality.
280
281 Used by `ConfigField.compare`.
282
283 Parameters
284 ----------
285 instance1 : `lsst.pex.config.Config`
286 Left-hand side config instance to compare.
287 instance2 : `lsst.pex.config.Config`
288 Right-hand side config instance to compare.
289 shortcut : `bool`
290 If `True`, this function returns as soon as an inequality if found.
291 rtol : `float`
292 Relative tolerance for floating point comparisons.
293 atol : `float`
294 Absolute tolerance for floating point comparisons.
295 output : callable
296 A callable that takes a string, used (possibly repeatedly) to
297 report inequalities.
298
299 Returns
300 -------
301 isEqual : bool
302 `True` if the fields are equal, `False` otherwise.
303
304 Notes
305 -----
306 Floating point comparisons are performed by `numpy.allclose`.
307 """
308 c1 = getattr(instance1, self.name)
309 c2 = getattr(instance2, self.name)
310 name = getComparisonName(
311 _joinNamePath(instance1._name, self.name), _joinNamePath(instance2._name, self.name)
312 )
313 return compareConfigs(name, c1, c2, shortcut=shortcut, rtol=rtol, atol=atol, output=output)
◆ _parseTypingArgs()
|
staticprotectedinherited |
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()
|
protectedinherited |
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()
|
protectedinherited |
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.configField.ConfigField.freeze | ( | self, | |
| instance ) |
Make this field read-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 from lsst.pex.config.config.Field.
Definition at line 200 of file configField.py.
200 def freeze(self, instance):
201 """Make this field read-only.
202
203 Parameters
204 ----------
205 instance : `lsst.pex.config.Config`
206 The config instance that contains this field.
207
208 Notes
209 -----
210 Freezing is only relevant for fields that hold subconfigs. Fields which
211 hold subconfigs should freeze each subconfig.
212
213 **Subclasses should implement this method.**
214 """
215 value = self.__get__(instance)
216 value.freeze()
217
◆ rename()
| lsst.pex.config.configField.ConfigField.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 from lsst.pex.config.config.Field.
Definition at line 149 of file configField.py.
149 def rename(self, instance):
150 r"""Rename the field in a `~lsst.pex.config.Config` (for internal use
151 only).
152
153 Parameters
154 ----------
155 instance : `lsst.pex.config.Config`
156 The config instance that contains this field.
157
158 Notes
159 -----
160 This method is invoked by the `lsst.pex.config.Config` object that
161 contains this field and should not be called directly.
162
163 Renaming is only relevant for `~lsst.pex.config.Field` instances that
164 hold subconfigs. `~lsst.pex.config.Field`\s that hold subconfigs should
165 rename each subconfig with the full field name as generated by
166 `lsst.pex.config.config._joinNamePath`.
167 """
168 value = self.__get__(instance)
169 value._rename(_joinNamePath(instance._name, self.name))
170
◆ save()
| lsst.pex.config.configField.ConfigField.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 from lsst.pex.config.config.Field.
Reimplemented in lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField.
Definition at line 176 of file configField.py.
176 def save(self, outfile, instance):
177 """Save this field to a file (for internal use only).
178
179 Parameters
180 ----------
181 outfile : file-like object
182 A writeable field handle.
183 instance : `~lsst.pex.config.Config`
184 The `~lsst.pex.config.Config` instance that contains this field.
185
186 Notes
187 -----
188 This method is invoked by the `~lsst.pex.config.Config` object that
189 contains this field and should not be called directly.
190
191 The output consists of the documentation string
192 (`lsst.pex.config.Field.doc`) formatted as a Python comment. The second
193 line is formatted as an assignment: ``{fullname}={value}``.
194
195 This output can be executed with Python.
196 """
197 value = self.__get__(instance)
198 value._save(outfile)
199
◆ toDict()
| lsst.pex.config.configField.ConfigField.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 from lsst.pex.config.config.Field.
Definition at line 218 of file configField.py.
218 def toDict(self, instance):
219 """Convert the field value so that it can be set as the value of an
220 item in a `dict` (for internal use only).
221
222 Parameters
223 ----------
224 instance : `~lsst.pex.config.Config`
225 The `~lsst.pex.config.Config` that contains this field.
226
227 Returns
228 -------
229 value : object
230 The field's value. See *Notes*.
231
232 Notes
233 -----
234 This method invoked by the owning `~lsst.pex.config.Config` object and
235 should not be called directly.
236
237 Simple values are passed through. Complex data structures must be
238 manipulated. For example, a `~lsst.pex.config.Field` holding a
239 subconfig should, instead of the subconfig object, return a `dict`
240 where the keys are the field names in the subconfig, and the values are
241 the field values in the subconfig.
242 """
243 value = self.__get__(instance)
244 return value.toDict()
245
◆ validate()
| lsst.pex.config.configField.ConfigField.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 from lsst.pex.config.config.Field.
Definition at line 246 of file configField.py.
246 def validate(self, instance):
247 """Validate the field (for internal use only).
248
249 Parameters
250 ----------
251 instance : `lsst.pex.config.Config`
252 The config instance that contains this field.
253
254 Raises
255 ------
256 lsst.pex.config.FieldValidationError
257 Raised if verification fails.
258
259 Notes
260 -----
261 This method provides basic validation:
262
263 - Ensures that the value is not `None` if the field is not optional.
264 - Ensures type correctness.
265 - Ensures that the user-provided ``check`` function is valid.
266
267 Most `~lsst.pex.config.Field` subclasses should call
268 `lsst.pex.config.Field.validate` if they re-implement
269 `~lsst.pex.config.Field.validate`.
270 """
271 value = self.__get__(instance)
272 value.validate()
273
274 if self.check is not None and not self.check(value):
275 msg = f"{value} is not a valid value"
276 raise FieldValidationError(self, instance, msg)
277
Member Data Documentation
◆ check
◆ default
◆ deprecated
|
inherited |
◆ doc
◆ dtype
◆ name
| lsst.pex.config.configField.ConfigField.name |
Definition at line 169 of file configField.py.
◆ optional
|
inherited |
◆ source
◆ supportedTypes
|
staticinherited |
The documentation for this class was generated from the following file:
- /j/snowflake/release/lsstsw/stack/lsst-scipipe-10.0.0/Linux64/pex_config/gabf8522325+fa80ff7197/python/lsst/pex/config/configField.py
Generated on Fri Apr 25 2025 08:04:00 for LSST Applications by
1.13.2