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