LSST Applications g04c3c9f7ca+2075667efa,g1e125bf412+5f448d5fcf,g2079a07aa2+3e9fd84d81,g2305ad1205+b635cf1488,g2bbee38e9b+6c6beb4891,g337abbeb29+6c6beb4891,g33d1c0ed96+6c6beb4891,g3a166c0a6a+6c6beb4891,g50ff169b8f+96c6868917,g52b1c1532d+585e252eca,g591dd9f2cf+42f171e1e6,g5c3423f6d4+d536b04327,g607f77f49a+d536b04327,g6f43f06aed+ca1339dc19,g858d7b2824+d536b04327,g8ee334c5b4+d7f9608c2f,g9963eaa53e+b3dc1655d3,g998f4353bf+d536b04327,g99cad8db69+8ef2408349,g9ddcbc5298+9a081db1e4,ga1e77700b3+2cbb763275,gadfd92a7e4+aec2f3b930,gae0086650b+585e252eca,gb0e22166c9+0e73c8378f,gb3b7280ab2+cb5fdb229e,gbb8dafda3b+a327199e22,gc120e1dc64+88074880ea,gc28159a63d+6c6beb4891,gcdd4ae20e8+bd241b2308,gcde1bda545+903e937d91,gcf0d15dbbd+bd241b2308,gdaeeff99f8+f9a426f77a,gddc38dedce+585e252eca,ge79ae78c31+6c6beb4891,gfbcc870c63+b310236976,w.2024.23
LSST Data Management Base Package
Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | Protected Member Functions | List of all members
lsst.pex.config.listField.ListField Class Reference
Inheritance diagram for lsst.pex.config.listField.ListField:
lsst.pex.config.config.Field lsst.pex.config.listField.List

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("Unsupported dtype %s" % _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()

lsst.pex.config.listField.ListField._compare ( self,
instance1,
instance2,
shortcut,
rtol,
atol,
output )
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("isnone for %s" % 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("size for %s" % 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 = "%s is not a valid value" % str(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: