lsst.pex.config.listField.ListField Class Reference

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)
	__class_getitem__ (cls, tuple[type,...]|type|ForwardRef params)
	rename (self, instance)
	freeze (self, instance)
	save (self, outfile, instance)
Field[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")
	__delete__ (self, instance, at=None, label="deletion")
	validateItem (self, i, x)
	list (self)
	__contains__ (self, x)
	__len__ (self)
None	__setitem__ (self, int i, FieldTypeVar x, Any at=None, str label="setitem", bool setHistory=True)
None	__setitem__ (self, slice i, Iterable[FieldTypeVar] x, Any at=None, str label="setitem", bool setHistory=True)
	__setitem__ (self, i, x, at=None, label="setitem", setHistory=True)
FieldTypeVar	__getitem__ (self, int i)
MutableSequence[FieldTypeVar]	__getitem__ (self, slice i)
	__getitem__ (self, i)
	__delitem__ (self, i, at=None, label="delitem", setHistory=True)
	__iter__ (self)
	insert (self, i, x, at=None, label="insert", setHistory=True)
	__repr__ (self)
	__str__ (self)
	__eq__ (self, other)
	__ne__ (self, other)
	__setattr__ (self, attr, value, at=None, label="assignment")
	__reduce__ (self)

Public Attributes
	listCheck = listCheck
	itemCheck = itemCheck
	itemtype = dtype
	length = length
	minLength = minLength
	maxLength = maxLength
	dtype = dtype
	doc = doc
	deprecated = deprecated
	default = default
	check = check
	optional = optional
	source = source

Static Public Attributes
dict	supportedTypes = {str, bool, float, int, complex}

Protected Member Functions
List[FieldTypeVar]|None	_copy_storage (self, Config old, Config new)
	_compare (self, instance1, instance2, shortcut, rtol, atol, output)
	_setup (self, doc, dtype, default, check, optional, source, deprecated)
	_validateValue (self, value)
	_collectImports (self, instance, imports)
Config	_config (self)
List	_copy (self, Config config)

Static Protected Member Functions
Mapping[str, Any]	_parseTypingArgs (tuple[type,...]|tuple[str,...] params, Mapping[str, Any] kwds)

Protected Attributes
	_field = field
	_config_ = weakref.ref(config)
Config	_history = self._config._history.setdefault(self._field.name, [])
list	_list = []
	_config

Properties
	history = property(lambda x: x._history)

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 278 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 )

Definition at line 324 of file listField.py.

    ):
        if dtype is None:
            raise ValueError(
                "dtype must either be supplied as an argument or as a type argument to the class"
            )
        if dtype not in Field.supportedTypes:
            raise ValueError(f"Unsupported dtype {_typeStr(dtype)}")
        if length is not None:
            if length <= 0:
                raise ValueError(f"'length' ({length}) must be positive")
            minLength = None
            maxLength = None
        else:
            if maxLength is not None and maxLength <= 0:
                raise ValueError(f"'maxLength' ({maxLength}) must be positive")
            if minLength is not None and maxLength is not None and minLength > maxLength:
                raise ValueError(
                    f"'maxLength' ({maxLength}) must be at least as large as 'minLength' ({minLength})"
                )
 
        if listCheck is not None and not callable(listCheck):
            raise ValueError("'listCheck' must be callable")
        if itemCheck is not None and not callable(itemCheck):
            raise ValueError("'itemCheck' must be callable")
 
        source = getStackFrame()
        self._setup(
            doc=doc,
            dtype=List,
            default=default,
            check=None,
            optional=optional,
            source=source,
            deprecated=deprecated,
        )
 
        self.listCheck = listCheck
        """Callable used to check the list as a whole.
        """
 
        self.itemCheck = itemCheck
        """Callable used to validate individual items as they are inserted
        into the list.
        """
 
        self.itemtype = dtype
        """Data type of list items.
        """
 
        self.length = length
        """Number of items that must be present in the list (or `None` to
        disable checking the list's length).
        """
 
        self.minLength = minLength
        """Minimum number of items that must be present in the list (or `None`
        to disable checking the list's minimum length).
        """
 
        self.maxLength = maxLength
        """Maximum number of items that must be present in the list (or `None`
        to disable checking the list's maximum length).
        """
 

Member Function Documentation

__class_getitem__()

lsst.pex.config.config.Field.__class_getitem__ ( cls, tuple[type, ...] | type | ForwardRef params )

inherited

Definition at line 464 of file config.py.

    def __class_getitem__(cls, params: tuple[type, ...] | type | ForwardRef):
        return _PexConfigGenericAlias(cls, params)
 

__contains__()

lsst.pex.config.listField.List.__contains__ ( self, x )

inherited

Definition at line 149 of file listField.py.

    def __contains__(self, x):
        return x in self._list
 

__delete__()

lsst.pex.config.config.Field.__delete__ ( self, instance, at = None, label = "deletion" )

inherited

Delete an attribute from a `lsst.pex.config.Config` instance.

Parameters
----------
instance : `lsst.pex.config.Config`
    The config instance that contains this field.
at : `list` of `lsst.pex.config.callStack.StackFrame`
    The call stack (created by
    `lsst.pex.config.callStack.getCallStack`).
label : `str`, optional
    Event label for the history.

Notes
-----
This is invoked by the owning `~lsst.pex.config.Config` object and
should not be called directly.

Definition at line 808 of file config.py.

    def __delete__(self, instance, at=None, label="deletion"):
        """Delete an attribute from a `lsst.pex.config.Config` instance.
 
        Parameters
        ----------
        instance : `lsst.pex.config.Config`
            The config instance that contains this field.
        at : `list` of `lsst.pex.config.callStack.StackFrame`
            The call stack (created by
            `lsst.pex.config.callStack.getCallStack`).
        label : `str`, optional
            Event label for the history.
 
        Notes
        -----
        This is invoked by the owning `~lsst.pex.config.Config` object and
        should not be called directly.
        """
        if at is None:
            at = getCallStack()
        self.__set__(instance, None, at=at, label=label)
 

__delitem__()

lsst.pex.config.listField.List.__delitem__ ( self, i, at = None, label = "delitem", setHistory = True )

inherited

Definition at line 199 of file listField.py.

    def __delitem__(self, i, at=None, label="delitem", setHistory=True):
        if self._config._frozen:
            raise FieldValidationError(self._field, self._config, "Cannot modify a frozen Config")
        del self._list[i]
        if setHistory:
            if at is None:
                at = getCallStack()
            self.history.append((list(self._list), at, label))
 

__eq__()

lsst.pex.config.listField.List.__eq__ ( self, other )

inherited

Definition at line 240 of file listField.py.

    def __eq__(self, other):
        if other is None:
            return False
        try:
            if len(self) != len(other):
                return False
 
            for i, j in zip(self, other, strict=True):
                if i != j:
                    return False
            return True
        except AttributeError:
            # other is not a sequence type
            return False
 

__get__() [1/3]

FieldTypeVar lsst.pex.config.config.Field.__get__ ( self, Config instance, Any owner = None, Any at = None, str label = "default" )

inherited

Definition at line 717 of file config.py.

    ) -> FieldTypeVar: ...
 

__get__() [2/3]

lsst.pex.config.config.Field.__get__ ( self, instance, owner = None, at = None, label = "default" )

inherited

Define how attribute access should occur on the Config instance
This is invoked by the owning config object and should not be called
directly.

When the field attribute is accessed on a Config class object, it
returns the field object itself in order to allow inspection of
Config classes.

When the field attribute is access on a config instance, the actual
value described by the field (and held by the Config instance) is
returned.

Definition at line 721 of file config.py.

    def __get__(self, instance, owner=None, at=None, label="default"):
        """Define how attribute access should occur on the Config instance
        This is invoked by the owning config object and should not be called
        directly.
 
        When the field attribute is accessed on a Config class object, it
        returns the field object itself in order to allow inspection of
        Config classes.
 
        When the field attribute is access on a config instance, the actual
        value described by the field (and held by the Config instance) is
        returned.
        """
        if instance is None:
            return self
        else:
            # try statements are almost free in python if they succeed
            try:
                return instance._storage[self.name]
            except AttributeError:
                if not isinstance(instance, Config):
                    return self
                else:
                    raise AttributeError(
                        f"Config {instance} is missing _storage attribute, likely incorrectly initialized"
                    ) from None
 

__get__() [3/3]

Field[FieldTypeVar] lsst.pex.config.config.Field.__get__ ( self, None instance, Any owner = None, Any at = None, str label = "default" )

inherited

Definition at line 712 of file config.py.

    ) -> Field[FieldTypeVar]: ...
 

__getitem__() [1/3]

lsst.pex.config.listField.List.__getitem__ ( self, i )

inherited

Definition at line 196 of file listField.py.

    def __getitem__(self, i):
        return self._list[i]
 

__getitem__() [2/3]

FieldTypeVar lsst.pex.config.listField.List.__getitem__ ( self, int i )

inherited

Definition at line 191 of file listField.py.

    def __getitem__(self, i: int) -> FieldTypeVar: ...
 

__getitem__() [3/3]

MutableSequence[FieldTypeVar] lsst.pex.config.listField.List.__getitem__ ( self, slice i )

inherited

Definition at line 194 of file listField.py.

    def __getitem__(self, i: slice) -> MutableSequence[FieldTypeVar]: ...
 

__iter__()

lsst.pex.config.listField.List.__iter__ ( self )

inherited

Definition at line 208 of file listField.py.

    def __iter__(self):
        return iter(self._list)
 

__len__()

lsst.pex.config.listField.List.__len__ ( self )

inherited

Definition at line 152 of file listField.py.

    def __len__(self):
        return len(self._list)
 

__ne__()

lsst.pex.config.listField.List.__ne__ ( self, other )

inherited

Definition at line 255 of file listField.py.

    def __ne__(self, other):
        return not self.__eq__(other)
 

__reduce__()

lsst.pex.config.listField.List.__reduce__ ( self )

inherited

Definition at line 270 of file listField.py.

    def __reduce__(self):
        raise UnexpectedProxyUsageError(
            f"Proxy container for config field {self._field.name} cannot "
            "be pickled; it should be converted to a built-in container before "
            "being assigned to other objects or variables."
        )
 
 

__repr__()

lsst.pex.config.listField.List.__repr__ ( self )

inherited

Definition at line 234 of file listField.py.

    def __repr__(self):
        return repr(self._list)
 

__set__()

None lsst.pex.config.listField.ListField.__set__	(		self,
		Config	instance,
		Iterable[FieldTypeVar] | None	value,
		Any	at = None,
		str	label = "assignment" )

Definition at line 440 of file listField.py.

    ) -> None:
        if instance._frozen:
            raise FieldValidationError(self, instance, "Cannot modify a frozen Config")
 
        if at is None:
            at = getCallStack()
 
        if value is not None:
            value = List(instance, self, value, at, label)
        else:
            history = instance._history.setdefault(self.name, [])
            history.append((value, at, label))
 
        instance._storage[self.name] = value
 

__setattr__()

lsst.pex.config.listField.List.__setattr__ ( self, attr, value, at = None, label = "assignment" )

inherited

Definition at line 258 of file listField.py.

    def __setattr__(self, attr, value, at=None, label="assignment"):
        if hasattr(getattr(self.__class__, attr, None), "__set__"):
            # This allows properties to work.
            object.__setattr__(self, attr, value)
        elif attr in self.__dict__ or attr in ["_field", "_config_", "_history", "_list", "__doc__"]:
            # This allows specific private attributes to work.
            object.__setattr__(self, attr, value)
        else:
            # We throw everything else.
            msg = f"{_typeStr(self._field)} has no attribute {attr}"
            raise FieldValidationError(self._field, self._config, msg)
 

__setitem__() [1/3]

lsst.pex.config.listField.List.__setitem__ ( self, i, x, at = None, label = "setitem", setHistory = True )

inherited

Definition at line 170 of file listField.py.

    def __setitem__(self, i, x, at=None, label="setitem", setHistory=True):
        if self._config._frozen:
            raise FieldValidationError(self._field, self._config, "Cannot modify a frozen Config")
        if isinstance(i, slice):
            k, stop, step = i.indices(len(self))
            for j, xj in enumerate(x):
                xj = _autocast(xj, self._field.itemtype)
                self.validateItem(k, xj)
                x[j] = xj
                k += step
        else:
            x = _autocast(x, self._field.itemtype)
            self.validateItem(i, x)
 
        self._list[i] = x
        if setHistory:
            if at is None:
                at = getCallStack()
            self.history.append((list(self._list), at, label))
 

__setitem__() [2/3]

None lsst.pex.config.listField.List.__setitem__ ( self, int i, FieldTypeVar x, Any at = None, str label = "setitem", bool setHistory = True )

inherited

Definition at line 156 of file listField.py.

    ) -> None: ...
 

__setitem__() [3/3]

None lsst.pex.config.listField.List.__setitem__ ( self, slice i, Iterable[FieldTypeVar] x, Any at = None, str label = "setitem", bool setHistory = True )

inherited

Definition at line 161 of file listField.py.

    ) -> None: ...
 

__str__()

lsst.pex.config.listField.List.__str__ ( self )

inherited

Definition at line 237 of file listField.py.

    def __str__(self):
        return str(self._list)
 

_collectImports()

lsst.pex.config.config.Field._collectImports ( self, instance, imports )

protectedinherited

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 in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.

Definition at line 626 of file config.py.

    def _collectImports(self, instance, imports):
        """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
        """
        pass
 

_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 486 of file listField.py.

    def _compare(self, instance1, instance2, shortcut, rtol, atol, output):
        """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`.
        """
        l1 = getattr(instance1, self.name)
        l2 = getattr(instance2, self.name)
        name = getComparisonName(
            _joinNamePath(instance1._name, self.name), _joinNamePath(instance2._name, self.name)
        )
        if l1 is None or l2 is None:
            return compareScalars(name, l1, l2, output=output)
        if not compareScalars(f"{name} (len)", len(l1), len(l2), output=output):
            return False
        equal = True
        for n, v1, v2 in zip(range(len(l1)), l1, l2, strict=True):
            result = compareScalars(
                f"{name}[{n}]", v1, v2, dtype=self.dtype, rtol=rtol, atol=atol, output=output
            )
 
            if not result and shortcut:
                return False
            equal = equal and result
        return equal

_config()

Config lsst.pex.config.listField.List._config ( self )

protectedinherited

Definition at line 103 of file listField.py.

    def _config(self) -> Config:
        # Config Fields should never outlive their config class instance
        # assert that as such here
        value = self._config_()
        assert value is not None
        return value
 

_copy()

List lsst.pex.config.listField.List._copy ( self, Config config )

protectedinherited

Definition at line 146 of file listField.py.

    def _copy(self, config: Config) -> List:
        return type(self)(config, self._field, self._list.copy(), at=None, label="copy", setHistory=False)
 

_copy_storage()

List[FieldTypeVar] | None lsst.pex.config.listField.ListField._copy_storage ( self, Config old, Config new )

protected

Copy the storage for this field in the given field into an object
suitable for storage in a new copy of that config.

Any frozen storage should be unfrozen.

Reimplemented from lsst.pex.config.config.Field.

Definition at line 479 of file listField.py.

    def _copy_storage(self, old: Config, new: Config) -> List[FieldTypeVar] | None:
        value: List[FieldTypeVar] | None = old._storage[self.name]
        if value is not None:
            return value._copy(new)
        else:
            return None
 

_parseTypingArgs()

Mapping[str, Any] lsst.pex.config.config.Field._parseTypingArgs ( tuple[type, ...] | tuple[str, ...] params, Mapping[str, Any] kwds )

staticprotectedinherited

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 in lsst.pex.config.configurableField.ConfigurableField, and lsst.pex.config.dictField.DictField.

Definition at line 410 of file config.py.

    ) -> Mapping[str, Any]:
        """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
        """
        if len(params) > 1:
            raise ValueError("Only single type parameters are supported")
        unpackedParams = params[0]
        if isinstance(unpackedParams, str):
            _typ = ForwardRef(unpackedParams)
            # type ignore below because typeshed seems to be wrong. It
            # indicates there are only 2 args, as it was in python 3.8, but
            # 3.9+ takes 3 args.
            result = _typ._evaluate(globals(), locals(), recursive_guard=set())  # type: ignore
            if result is None:
                raise ValueError("Could not deduce type from input")
            unpackedParams = cast(type, result)
        if "dtype" in kwds and kwds["dtype"] != unpackedParams:
            raise ValueError("Conflicting definition for dtype")
        elif "dtype" not in kwds:
            kwds = {**kwds, **{"dtype": unpackedParams}}
        return kwds
 

_setup()

lsst.pex.config.config.Field._setup ( self, doc, dtype, default, check, optional, source, deprecated )

protectedinherited

Set attributes, usually during initialization.

Definition at line 486 of file config.py.

    def _setup(self, doc, dtype, default, check, optional, source, deprecated):
        """Set attributes, usually during initialization."""
        self.dtype = dtype
        """Data type for the field.
        """
 
        if not doc:
            raise ValueError("Docstring is empty.")
 
        # append the deprecation message to the docstring.
        if deprecated is not None:
            doc = f"{doc} Deprecated: {deprecated}"
        self.doc = doc
        """A description of the field (`str`).
        """
 
        self.deprecated = deprecated
        """If not None, a description of why this field is deprecated (`str`).
        """
 
        self.__doc__ = f"{doc} (`{dtype.__name__}`"
        if optional or default is not None:
            self.__doc__ += f", default ``{default!r}``"
        self.__doc__ += ")"
 
        self.default = default
        """Default value for this field.
        """
 
        self.check = check
        """A user-defined function that validates the value of the field.
        """
 
        self.optional = optional
        """Flag that determines if the field is required to be set (`bool`).
 
        When `False`, `lsst.pex.config.Config.validate` will fail if the
        field's value is `None`.
        """
 
        self.source = source
        """The stack frame where this field is defined (`list` of
        `~lsst.pex.config.callStack.StackFrame`).
        """
 

_validateValue()

lsst.pex.config.config.Field._validateValue ( self, value )

protectedinherited

Validate a value.

Parameters
----------
value : object
    The value being validated.

Raises
------
TypeError
    Raised if the value's type is incompatible with the field's
    ``dtype``.
ValueError
    Raised if the value is rejected by the ``check`` method.

Reimplemented in lsst.pex.config.choiceField.ChoiceField, and lsst.pex.config.rangeField.RangeField.

Definition at line 598 of file config.py.

    def _validateValue(self, value):
        """Validate a value.
 
        Parameters
        ----------
        value : object
            The value being validated.
 
        Raises
        ------
        TypeError
            Raised if the value's type is incompatible with the field's
            ``dtype``.
        ValueError
            Raised if the value is rejected by the ``check`` method.
        """
        if value is None:
            return
 
        if not isinstance(value, self.dtype):
            msg = (
                f"Value {value} is of incorrect type {_typeStr(value)}. Expected type {_typeStr(self.dtype)}"
            )
            raise TypeError(msg)
        if self.check is not None and not self.check(value):
            msg = f"Value {value} is not a valid value"
            raise ValueError(msg)
 

freeze()

lsst.pex.config.config.Field.freeze ( self, instance )

inherited

Make this field read-only (for internal use 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 in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.

Definition at line 581 of file config.py.

    def freeze(self, instance):
        """Make this field read-only (for internal use 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.**
        """
        pass
 

insert()

lsst.pex.config.listField.List.insert ( self, i, x, at = None, label = "insert", setHistory = True )

inherited

Insert an item into the list at the given index.

Parameters
----------
i : `int`
    Index where the item is inserted.
x : object
    Item that is inserted.
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.
setHistory : `bool`, optional
    Enable setting the field's history, using the value of the ``at``
    parameter. Default is `True`.

Definition at line 211 of file listField.py.

    def insert(self, i, x, at=None, label="insert", setHistory=True):
        """Insert an item into the list at the given index.
 
        Parameters
        ----------
        i : `int`
            Index where the item is inserted.
        x : object
            Item that is inserted.
        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.
        setHistory : `bool`, optional
            Enable setting the field's history, using the value of the ``at``
            parameter. Default is `True`.
        """
        if at is None:
            at = getCallStack()
        self.__setitem__(slice(i, i), [x], at=at, label=label, setHistory=setHistory)
 

list()

lsst.pex.config.listField.List.list ( self )

inherited

Sequence of items contained by the `List` (`list`).

Definition at line 138 of file listField.py.

    def list(self):
        """Sequence of items contained by the `List` (`list`)."""
        return self._list
 

rename()

lsst.pex.config.config.Field.rename ( self, instance )

inherited

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 in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.

Definition at line 531 of file config.py.

    def rename(self, instance):
        r"""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`.
        """
        pass
 

save()

lsst.pex.config.config.Field.save ( self, outfile, instance )

inherited

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 in lsst.pex.config.configChoiceField.ConfigChoiceField, lsst.pex.config.configDictField.ConfigDictField, lsst.pex.config.configField.ConfigField, lsst.pex.config.configurableActions._configurableActionField.ConfigurableActionField, lsst.pex.config.configurableActions._configurableActionStructField.ConfigurableActionStructField, and lsst.pex.config.configurableField.ConfigurableField.

Definition at line 640 of file config.py.

    def 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.
        """
        value = self.__get__(instance)
        fullname = _joinNamePath(instance._name, self.name)
 
        if self.deprecated and value == self.default:
            return
 
        # write full documentation string as comment lines
        # (i.e. first character is #)
        doc = "# " + str(self.doc).replace("\n", "\n# ")
        if isinstance(value, float) and not math.isfinite(value):
            # non-finite numbers need special care
            outfile.write(f"{doc}\n{fullname}=float('{value!r}')\n\n")
        else:
            outfile.write(f"{doc}\n{fullname}={value!r}\n\n")
 

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 461 of file listField.py.

    def 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.
        """
        value = self.__get__(instance)
        return list(value) if value is not None else None
 

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 400 of file listField.py.

    def 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.
        """
        Field.validate(self, instance)
        value = self.__get__(instance)
        if value is not None:
            lenValue = len(value)
            if self.length is not None and not lenValue == self.length:
                msg = f"Required list length={self.length}, got length={lenValue}"
                raise FieldValidationError(self, instance, msg)
            elif self.minLength is not None and lenValue < self.minLength:
                msg = f"Minimum allowed list length={self.minLength}, got length={lenValue}"
                raise FieldValidationError(self, instance, msg)
            elif self.maxLength is not None and lenValue > self.maxLength:
                msg = f"Maximum allowed list length={self.maxLength}, got length={lenValue}"
                raise FieldValidationError(self, instance, msg)
            elif self.listCheck is not None and not self.listCheck(value):
                msg = f"{value} is not a valid value"
                raise FieldValidationError(self, instance, msg)
 

validateItem()

lsst.pex.config.listField.List.validateItem ( self, i, x )

inherited

Validate an item to determine if it can be included in the list.

Parameters
----------
i : `int`
    Index of the item in the `list`.
x : object
    Item in the `list`.

Raises
------
FieldValidationError
    Raised if an item in the ``value`` parameter does not have the
    appropriate type for this field or does not pass the field's
    `ListField.itemCheck` method.

Definition at line 110 of file listField.py.

    def validateItem(self, i, x):
        """Validate an item to determine if it can be included in the list.
 
        Parameters
        ----------
        i : `int`
            Index of the item in the `list`.
        x : object
            Item in the `list`.
 
        Raises
        ------
        FieldValidationError
            Raised if an item in the ``value`` parameter does not have the
            appropriate type for this field or does not pass the field's
            `ListField.itemCheck` method.
        """
        if not isinstance(x, self._field.itemtype) and x is not None:
            msg = (
                f"Item at position {i} with value {x} is of incorrect type {_typeStr(x)}. "
                f"Expected {_typeStr(self._field.itemtype)}"
            )
            raise FieldValidationError(self._field, self._config, msg)
 
        if self._field.itemCheck is not None and not self._field.itemCheck(x):
            msg = f"Item at position {i} is not a valid value: {x}"
            raise FieldValidationError(self._field, self._config, msg)
 

Member Data Documentation

_config

lsst.pex.config.listField.List._config

protectedinherited

Definition at line 132 of file listField.py.

_config_

lsst.pex.config.listField.List._config_ = weakref.ref(config)

protectedinherited

Definition at line 88 of file listField.py.

_field

lsst.pex.config.listField.List._field = field

protectedinherited

Definition at line 87 of file listField.py.

_history

Config lsst.pex.config.listField.List._history = self._config._history.setdefault(self._field.name, [])

protectedinherited

Definition at line 89 of file listField.py.

_list

lsst.pex.config.listField.List._list = []

protectedinherited

Definition at line 90 of file listField.py.

check

lsst.pex.config.config.Field.check = check

inherited

Definition at line 515 of file config.py.

default

lsst.pex.config.config.Field.default = default

inherited

Definition at line 511 of file config.py.

deprecated

lsst.pex.config.config.Field.deprecated = deprecated

inherited

Definition at line 502 of file config.py.

doc

lsst.pex.config.config.Field.doc = doc

inherited

Definition at line 498 of file config.py.

dtype

lsst.pex.config.config.Field.dtype = dtype

inherited

Definition at line 488 of file config.py.

itemCheck

lsst.pex.config.listField.ListField.itemCheck = itemCheck

Definition at line 376 of file listField.py.

itemtype

lsst.pex.config.listField.ListField.itemtype = dtype

Definition at line 381 of file listField.py.

length

lsst.pex.config.listField.ListField.length = length

Definition at line 385 of file listField.py.

listCheck

lsst.pex.config.listField.ListField.listCheck = listCheck

Definition at line 372 of file listField.py.

maxLength

lsst.pex.config.listField.ListField.maxLength = maxLength

Definition at line 395 of file listField.py.

minLength

lsst.pex.config.listField.ListField.minLength = minLength

Definition at line 390 of file listField.py.

optional

lsst.pex.config.config.Field.optional = optional

inherited

Definition at line 519 of file config.py.

source

lsst.pex.config.config.Field.source = source

inherited

Definition at line 526 of file config.py.

supportedTypes

dict lsst.pex.config.config.Field.supportedTypes = {str, bool, float, int, complex}

staticinherited

Definition at line 405 of file config.py.

Property Documentation

history

lsst.pex.config.listField.List.history = property(lambda x: x._history)

staticinherited

Definition at line 142 of file listField.py.

---

The documentation for this class was generated from the following file:

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-12.1.0/Linux/pex_config/gbaa8f7a6c5+38b34f4976/python/lsst/pex/config/listField.py