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