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