Inheritance diagram for lsst.pex.config.dictField.DictField:
Public Member Functions | |
| __init__ (self, doc, keytype=None, itemtype=None, default=None, optional=False, dictCheck=None, itemCheck=None, deprecated=None) | |
| validate (self, instance) | |
| None | __set__ (self, Config instance, Mapping[KeyTypeVar, ItemTypeVar]|None value, Any at=None, str label="assignment") |
| toDict (self, instance) | |
Public Attributes | |
| keytype | |
| itemtype | |
| dictCheck | |
| itemCheck | |
| name | |
Static Public Attributes | |
| type | DictClass = Dict |
Protected Member Functions | |
| _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 configuration field (`~lsst.pex.config.Field` subclass) that maps keys
and values.
The types of both items and keys are restricted to these builtin types:
`int`, `float`, `complex`, `bool`, and `str`). All keys share the same type
and all values share the same type. Keys can have a different type from
values.
Parameters
----------
doc : `str`
A documentation string that describes the configuration field.
keytype : {`int`, `float`, `complex`, `bool`, `str`}, optional
The type of the mapping keys. All keys must have this type. Optional
if keytype and itemtype are supplied as typing arguments to the class.
itemtype : {`int`, `float`, `complex`, `bool`, `str`}, optional
Type of the mapping values. Optional if keytype and itemtype are
supplied as typing arguments to the class.
default : `dict`, optional
The default mapping.
optional : `bool`, optional
If `True`, the field doesn't need to have a set value.
dictCheck : callable
A function that validates the dictionary as a whole.
itemCheck : callable
A function that validates individual mapping values.
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
ConfigField
ConfigurableField
Field
ListField
RangeField
RegistryField
Examples
--------
This field maps has `str` keys and `int` values:
>>> from lsst.pex.config import Config, DictField
>>> class MyConfig(Config):
... field = DictField(
... doc="Example string-to-int mapping field.",
... keytype=str, itemtype=int,
... default={})
...
>>> config = MyConfig()
>>> config.field['myKey'] = 42
>>> print(config.field)
{'myKey': 42}
Definition at line 194 of file dictField.py.
Constructor & Destructor Documentation
◆ __init__()
| lsst.pex.config.dictField.DictField.__init__ | ( | self, | |
| doc, | |||
| keytype = None, | |||
| itemtype = None, | |||
| default = None, | |||
| optional = False, | |||
| dictCheck = None, | |||
| itemCheck = None, | |||
| deprecated = None ) |
Reimplemented from lsst.pex.config.config.Field.
Reimplemented in lsst.pex.config.configDictField.ConfigDictField.
Definition at line 291 of file dictField.py.
301 ):
302 source = getStackFrame()
303 self._setup(
304 doc=doc,
305 dtype=Dict,
306 default=default,
307 check=None,
308 optional=optional,
309 source=source,
310 deprecated=deprecated,
311 )
312 if keytype is None:
313 raise ValueError(
314 "keytype must either be supplied as an argument or as a type argument to the class"
315 )
316 if keytype not in self.supportedTypes:
317 raise ValueError("'keytype' %s is not a supported type" % _typeStr(keytype))
318 elif itemtype is not None and itemtype not in self.supportedTypes:
319 raise ValueError("'itemtype' %s is not a supported type" % _typeStr(itemtype))
320 if dictCheck is not None and not hasattr(dictCheck, "__call__"):
321 raise ValueError("'dictCheck' must be callable")
322 if itemCheck is not None and not hasattr(itemCheck, "__call__"):
323 raise ValueError("'itemCheck' must be callable")
324
325 self.keytype = keytype
326 self.itemtype = itemtype
327 self.dictCheck = dictCheck
328 self.itemCheck = itemCheck
329
Member Function Documentation
◆ __set__()
| None lsst.pex.config.dictField.DictField.__set__ | ( | self, | |
| Config | instance, | ||
| Mapping[KeyTypeVar, ItemTypeVar] | 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.
Definition at line 362 of file dictField.py.
368 ) -> None:
369 if instance._frozen:
370 msg = "Cannot modify a frozen Config. Attempting to set field to value %s" % value
371 raise FieldValidationError(self, instance, msg)
372
373 if at is None:
374 at = getCallStack()
375 if value is not None:
376 value = self.DictClass(instance, self, value, at=at, label=label)
377 else:
378 history = instance._history.setdefault(self.name, [])
379 history.append((value, at, label))
380
381 instance._storage[self.name] = value
382
◆ _compare()
|
protected |
Compare two fields for equality.
Used by `lsst.pex.ConfigDictField.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.
Reimplemented in lsst.pex.config.configDictField.ConfigDictField.
Definition at line 401 of file dictField.py.
401 def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
402 """Compare two fields for equality.
403
404 Used by `lsst.pex.ConfigDictField.compare`.
405
406 Parameters
407 ----------
408 instance1 : `lsst.pex.config.Config`
409 Left-hand side config instance to compare.
410 instance2 : `lsst.pex.config.Config`
411 Right-hand side config instance to compare.
412 shortcut : `bool`
413 If `True`, this function returns as soon as an inequality if found.
414 rtol : `float`
415 Relative tolerance for floating point comparisons.
416 atol : `float`
417 Absolute tolerance for floating point comparisons.
418 output : callable
419 A callable that takes a string, used (possibly repeatedly) to
420 report inequalities.
421
422 Returns
423 -------
424 isEqual : bool
425 `True` if the fields are equal, `False` otherwise.
426
427 Notes
428 -----
429 Floating point comparisons are performed by `numpy.allclose`.
430 """
431 d1 = getattr(instance1, self.name)
432 d2 = getattr(instance2, self.name)
433 name = getComparisonName(
434 _joinNamePath(instance1._name, self.name), _joinNamePath(instance2._name, self.name)
435 )
436 if not compareScalars("isnone for %s" % name, d1 is None, d2 is None, output=output):
437 return False
438 if d1 is None and d2 is None:
439 return True
441 return False
442 equal = True
443 for k, v1 in d1.items():
444 v2 = d2[k]
445 result = compareScalars(
446 f"{name}[{k!r}]", v1, v2, dtype=self.itemtype, rtol=rtol, atol=atol, output=output
447 )
448 if not result and shortcut:
449 return False
450 equal = equal and result
451 return equal
◆ _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 from lsst.pex.config.config.Field.
Definition at line 257 of file dictField.py.
259 ) -> Mapping[str, Any]:
260 if len(params) != 2:
261 raise ValueError("Only tuples of types that are length 2 are supported")
262 resultParams = []
263 for typ in params:
264 if isinstance(typ, str):
265 _typ = ForwardRef(typ)
266 # type ignore below because typeshed seems to be wrong. It
267 # indicates there are only 2 args, as it was in python 3.8, but
268 # 3.9+ takes 3 args. Attempt in old style and new style to
269 # work with both.
270 try:
272 except TypeError:
273 # python 3.8 path
274 result = _typ._evaluate(globals(), locals())
275 if result is None:
276 raise ValueError("Could not deduce type from input")
277 typ = cast(type, result)
278 resultParams.append(typ)
279 keyType, itemType = resultParams
280 results = dict(kwds)
281 if (supplied := kwds.get("keytype")) and supplied != keyType:
282 raise ValueError("Conflicting definition for keytype")
283 else:
284 results["keytype"] = keyType
285 if (supplied := kwds.get("itemtype")) and supplied != itemType:
286 raise ValueError("Conflicting definition for itemtype")
287 else:
288 results["itemtype"] = itemType
289 return results
290
◆ toDict()
| lsst.pex.config.dictField.DictField.toDict | ( | self, | |
| instance ) |
Convert this field's key-value pairs into a regular `dict`.
Parameters
----------
instance : `lsst.pex.config.Config`
The configuration that contains this field.
Returns
-------
result : `dict` or `None`
If this field has a value of `None`, then this method returns
`None`. Otherwise, this method returns the field's value as a
regular Python `dict`.
Reimplemented from lsst.pex.config.config.Field.
Reimplemented in lsst.pex.config.configDictField.ConfigDictField.
Definition at line 383 of file dictField.py.
383 def toDict(self, instance):
384 """Convert this field's key-value pairs into a regular `dict`.
385
386 Parameters
387 ----------
388 instance : `lsst.pex.config.Config`
389 The configuration that contains this field.
390
391 Returns
392 -------
393 result : `dict` or `None`
394 If this field has a value of `None`, then this method returns
395 `None`. Otherwise, this method returns the field's value as a
396 regular Python `dict`.
397 """
398 value = self.__get__(instance)
399 return dict(value) if value is not None else None
400
◆ validate()
| lsst.pex.config.dictField.DictField.validate | ( | self, | |
| instance ) |
Validate the field's value (for internal use only).
Parameters
----------
instance : `lsst.pex.config.Config`
The configuration that contains this field.
Returns
-------
isValid : `bool`
`True` is returned if the field passes validation criteria (see
*Notes*). Otherwise `False`.
Notes
-----
This method validates values according to the following criteria:
- A non-optional field is not `None`.
- If a value is not `None`, is must pass the `ConfigField.dictCheck`
user callback functon.
Individual item checks by the `ConfigField.itemCheck` user callback
function are done immediately when the value is set on a key. Those
checks are not repeated by this method.
Reimplemented from lsst.pex.config.config.Field.
Reimplemented in lsst.pex.config.configDictField.ConfigDictField.
Definition at line 330 of file dictField.py.
330 def validate(self, instance):
331 """Validate the field's value (for internal use only).
332
333 Parameters
334 ----------
335 instance : `lsst.pex.config.Config`
336 The configuration that contains this field.
337
338 Returns
339 -------
340 isValid : `bool`
341 `True` is returned if the field passes validation criteria (see
342 *Notes*). Otherwise `False`.
343
344 Notes
345 -----
346 This method validates values according to the following criteria:
347
348 - A non-optional field is not `None`.
349 - If a value is not `None`, is must pass the `ConfigField.dictCheck`
350 user callback functon.
351
352 Individual item checks by the `ConfigField.itemCheck` user callback
353 function are done immediately when the value is set on a key. Those
354 checks are not repeated by this method.
355 """
356 Field.validate(self, instance)
357 value = self.__get__(instance)
358 if value is not None and self.dictCheck is not None and not self.dictCheck(value):
359 msg = "%s is not a valid value" % str(value)
360 raise FieldValidationError(self, instance, msg)
361
Member Data Documentation
◆ dictCheck
| lsst.pex.config.dictField.DictField.dictCheck |
Definition at line 327 of file dictField.py.
◆ DictClass
Definition at line 254 of file dictField.py.
◆ itemCheck
| lsst.pex.config.dictField.DictField.itemCheck |
Definition at line 328 of file dictField.py.
◆ itemtype
| lsst.pex.config.dictField.DictField.itemtype |
Definition at line 326 of file dictField.py.
◆ keytype
| lsst.pex.config.dictField.DictField.keytype |
Definition at line 325 of file dictField.py.
◆ name
| lsst.pex.config.dictField.DictField.name |
Definition at line 434 of file dictField.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+9664299f35/python/lsst/pex/config/dictField.py
