Inheritance diagram for lsst.pex.config.listField.ListField:
Public Member Functions | |
| __init__ (self, doc, dtype=None, default=None, optional=False, listCheck=None, itemCheck=None, length=None, minLength=None, maxLength=None, deprecated=None) | |
| validate (self, instance) | |
| None | __set__ (self, Config instance, Iterable[FieldTypeVar]|None value, Any at=None, str label="assignment") |
| toDict (self, instance) | |
Public Attributes | |
| listCheck | |
| itemCheck | |
| itemtype | |
| length | |
| minLength | |
| maxLength | |
| name | |
Protected Member Functions | |
| _compare (self, instance1, instance2, shortcut, rtol, atol, output) | |
Detailed Description
A configuration field (`~lsst.pex.config.Field` subclass) that contains
a list of values of a specific type.
Parameters
----------
doc : `str`
A description of the field.
dtype : class, optional
The data type of items in the list. Optional if supplied as typing
argument to the class.
default : sequence, optional
The default items for the field.
optional : `bool`, optional
Set whether the field is *optional*. When `False`,
`lsst.pex.config.Config.validate` will fail if the field's value is
`None`.
listCheck : callable, optional
A callable that validates the list as a whole.
itemCheck : callable, optional
A callable that validates individual items in the list.
length : `int`, optional
If set, this field must contain exactly ``length`` number of items.
minLength : `int`, optional
If set, this field must contain *at least* ``minLength`` number of
items.
maxLength : `int`, optional
If set, this field must contain *no more than* ``maxLength`` number of
items.
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
DictField
Field
RangeField
RegistryField
Definition at line 265 of file listField.py.
Constructor & Destructor Documentation
◆ __init__()
| lsst.pex.config.listField.ListField.__init__ | ( | self, | |
| doc, | |||
| dtype = None, | |||
| default = None, | |||
| optional = False, | |||
| listCheck = None, | |||
| itemCheck = None, | |||
| length = None, | |||
| minLength = None, | |||
| maxLength = None, | |||
| deprecated = None ) |
Reimplemented from lsst.pex.config.config.Field.
Definition at line 311 of file listField.py.
323 ):
324 if dtype is None:
325 raise ValueError(
326 "dtype must either be supplied as an argument or as a type argument to the class"
327 )
328 if dtype not in Field.supportedTypes:
329 raise ValueError(f"Unsupported dtype {_typeStr(dtype)}")
330 if length is not None:
331 if length <= 0:
332 raise ValueError("'length' (%d) must be positive" % length)
333 minLength = None
334 maxLength = None
335 else:
336 if maxLength is not None and maxLength <= 0:
337 raise ValueError("'maxLength' (%d) must be positive" % maxLength)
338 if minLength is not None and maxLength is not None and minLength > maxLength:
339 raise ValueError(
340 "'maxLength' (%d) must be at least as large as 'minLength' (%d)" % (maxLength, minLength)
341 )
342
343 if listCheck is not None and not hasattr(listCheck, "__call__"):
344 raise ValueError("'listCheck' must be callable")
345 if itemCheck is not None and not hasattr(itemCheck, "__call__"):
346 raise ValueError("'itemCheck' must be callable")
347
348 source = getStackFrame()
349 self._setup(
350 doc=doc,
351 dtype=List,
352 default=default,
353 check=None,
354 optional=optional,
355 source=source,
356 deprecated=deprecated,
357 )
358
359 self.listCheck = listCheck
360 """Callable used to check the list as a whole.
361 """
362
363 self.itemCheck = itemCheck
364 """Callable used to validate individual items as they are inserted
365 into the list.
366 """
367
368 self.itemtype = dtype
369 """Data type of list items.
370 """
371
372 self.length = length
373 """Number of items that must be present in the list (or `None` to
374 disable checking the list's length).
375 """
376
377 self.minLength = minLength
378 """Minimum number of items that must be present in the list (or `None`
379 to disable checking the list's minimum length).
380 """
381
382 self.maxLength = maxLength
383 """Maximum number of items that must be present in the list (or `None`
384 to disable checking the list's maximum length).
385 """
386
Member Function Documentation
◆ __set__()
| None lsst.pex.config.listField.ListField.__set__ | ( | self, | |
| Config | instance, | ||
| Iterable[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.
Definition at line 427 of file listField.py.
433 ) -> None:
434 if instance._frozen:
435 raise FieldValidationError(self, instance, "Cannot modify a frozen Config")
436
437 if at is None:
438 at = getCallStack()
439
440 if value is not None:
441 value = List(instance, self, value, at, label)
442 else:
443 history = instance._history.setdefault(self.name, [])
444 history.append((value, at, label))
445
446 instance._storage[self.name] = value
447
◆ _compare()
|
protected |
Compare two config instances for equality with respect to this
field.
`lsst.pex.config.config.compare` is the primary user of this method.
Parameters
----------
instance1 : `lsst.pex.config.Config`
Left-hand-side `~lsst.pex.config.Config` instance in the
comparison.
instance2 : `lsst.pex.config.Config`
Right-hand-side `~lsst.pex.config.Config` instance in the
comparison.
shortcut : `bool`
If `True`, return as soon as an **inequality** is found.
rtol : `float`
Relative tolerance for floating point comparisons.
atol : `float`
Absolute tolerance for floating point comparisons.
output : callable
If not None, a callable that takes a `str`, used (possibly
repeatedly) to report inequalities.
Returns
-------
equal : `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 466 of file listField.py.
466 def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
467 """Compare two config instances for equality with respect to this
468 field.
469
470 `lsst.pex.config.config.compare` is the primary user of this method.
471
472 Parameters
473 ----------
474 instance1 : `lsst.pex.config.Config`
475 Left-hand-side `~lsst.pex.config.Config` instance in the
476 comparison.
477 instance2 : `lsst.pex.config.Config`
478 Right-hand-side `~lsst.pex.config.Config` instance in the
479 comparison.
480 shortcut : `bool`
481 If `True`, return as soon as an **inequality** is found.
482 rtol : `float`
483 Relative tolerance for floating point comparisons.
484 atol : `float`
485 Absolute tolerance for floating point comparisons.
486 output : callable
487 If not None, a callable that takes a `str`, used (possibly
488 repeatedly) to report inequalities.
489
490 Returns
491 -------
492 equal : `bool`
493 `True` if the fields are equal; `False` otherwise.
494
495 Notes
496 -----
497 Floating point comparisons are performed by `numpy.allclose`.
498 """
499 l1 = getattr(instance1, self.name)
500 l2 = getattr(instance2, self.name)
501 name = getComparisonName(
502 _joinNamePath(instance1._name, self.name), _joinNamePath(instance2._name, self.name)
503 )
504 if not compareScalars(f"isnone for {name}", l1 is None, l2 is None, output=output):
505 return False
506 if l1 is None and l2 is None:
507 return True
508 if not compareScalars(f"size for {name}", len(l1), len(l2), output=output):
509 return False
510 equal = True
511 for n, v1, v2 in zip(range(len(l1)), l1, l2):
512 result = compareScalars(
513 "%s[%d]" % (name, n), v1, v2, dtype=self.dtype, rtol=rtol, atol=atol, output=output
514 )
515 if not result and shortcut:
516 return False
517 equal = equal and result
518 return equal
◆ toDict()
| lsst.pex.config.listField.ListField.toDict | ( | self, | |
| instance ) |
Convert the value of this field to a plain `list`.
`lsst.pex.config.Config.toDict` is the primary user of this method.
Parameters
----------
instance : `lsst.pex.config.Config`
The config instance that contains this field.
Returns
-------
`list`
Plain `list` of items, or `None` if the field is not set.
Reimplemented from lsst.pex.config.config.Field.
Definition at line 448 of file listField.py.
448 def toDict(self, instance):
449 """Convert the value of this field to a plain `list`.
450
451 `lsst.pex.config.Config.toDict` is the primary user of this method.
452
453 Parameters
454 ----------
455 instance : `lsst.pex.config.Config`
456 The config instance that contains this field.
457
458 Returns
459 -------
460 `list`
461 Plain `list` of items, or `None` if the field is not set.
462 """
463 value = self.__get__(instance)
464 return list(value) if value is not None else None
465
◆ validate()
| lsst.pex.config.listField.ListField.validate | ( | self, | |
| instance ) |
Validate the field.
Parameters
----------
instance : `lsst.pex.config.Config`
The config instance that contains this field.
Raises
------
lsst.pex.config.FieldValidationError
Raised if:
- The field is not optional, but the value is `None`.
- The list itself does not meet the requirements of the ``length``,
``minLength``, or ``maxLength`` attributes.
- The ``listCheck`` callable returns `False`.
Notes
-----
Individual item checks (``itemCheck``) are applied when each item is
set and are not re-checked by this method.
Reimplemented from lsst.pex.config.config.Field.
Definition at line 387 of file listField.py.
387 def validate(self, instance):
388 """Validate the field.
389
390 Parameters
391 ----------
392 instance : `lsst.pex.config.Config`
393 The config instance that contains this field.
394
395 Raises
396 ------
397 lsst.pex.config.FieldValidationError
398 Raised if:
399
400 - The field is not optional, but the value is `None`.
401 - The list itself does not meet the requirements of the ``length``,
402 ``minLength``, or ``maxLength`` attributes.
403 - The ``listCheck`` callable returns `False`.
404
405 Notes
406 -----
407 Individual item checks (``itemCheck``) are applied when each item is
408 set and are not re-checked by this method.
409 """
410 Field.validate(self, instance)
411 value = self.__get__(instance)
412 if value is not None:
413 lenValue = len(value)
414 if self.length is not None and not lenValue == self.length:
415 msg = "Required list length=%d, got length=%d" % (self.length, lenValue)
416 raise FieldValidationError(self, instance, msg)
417 elif self.minLength is not None and lenValue < self.minLength:
418 msg = "Minimum allowed list length=%d, got length=%d" % (self.minLength, lenValue)
419 raise FieldValidationError(self, instance, msg)
420 elif self.maxLength is not None and lenValue > self.maxLength:
421 msg = "Maximum allowed list length=%d, got length=%d" % (self.maxLength, lenValue)
422 raise FieldValidationError(self, instance, msg)
423 elif self.listCheck is not None and not self.listCheck(value):
424 msg = f"{value} is not a valid value"
425 raise FieldValidationError(self, instance, msg)
426
Member Data Documentation
◆ itemCheck
| lsst.pex.config.listField.ListField.itemCheck |
Definition at line 363 of file listField.py.
◆ itemtype
| lsst.pex.config.listField.ListField.itemtype |
Definition at line 368 of file listField.py.
◆ length
| lsst.pex.config.listField.ListField.length |
Definition at line 372 of file listField.py.
◆ listCheck
| lsst.pex.config.listField.ListField.listCheck |
Definition at line 359 of file listField.py.
◆ maxLength
| lsst.pex.config.listField.ListField.maxLength |
Definition at line 382 of file listField.py.
◆ minLength
| lsst.pex.config.listField.ListField.minLength |
Definition at line 377 of file listField.py.
◆ name
| lsst.pex.config.listField.ListField.name |
Definition at line 502 of file listField.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/g2cdde0e794+8523d0dbb4/python/lsst/pex/config/listField.py
