lsst.daf.base.propertyContainer.propertyContainerContinued Namespace Reference

Classes
class	PropertyList
class	PropertySet
class	ReturnStyle

Functions
	getPropertySetState (container, asLists=False)
	getPropertyListState (container, asLists=False)
	setPropertySetState (container, state)
	setPropertyListState (container, state)
	_propertyContainerElementTypeName (container, name)
	_propertyContainerGet (container, name, returnStyle)
	_iterable (a)
	_guessIntegerType (container, name, value)
	_propertyContainerSet (container, name, value, typeMenu, *args)
	_propertyContainerAdd (container, name, value, typeMenu, *args)
	_makePropertySet (state)
	_makePropertyList (state)

Variables
TypeAlias	NestedMetadataDict = Mapping[str, Union[str, float, int, bool, "NestedMetadataDict"]]
dict	_TYPE_MAP = {}
	type_obj = getattr(PropertySet, "TYPE_" + checkType)

Function Documentation

_guessIntegerType()

lsst.daf.base.propertyContainer.propertyContainerContinued._guessIntegerType ( container, name, value )

protected

Given an existing container and name, determine the type
that should be used for the supplied value. The supplied value
is assumed to be a scalar.

On Python 3 all ints are LongLong but we need to be able to store them
in Int containers if that is what is being used (testing for truncation).
Int is assumed to mean 32bit integer (2147483647 to -2147483648).

If there is no pre-existing value we have to decide what to do. For now
we pick Int if the value is less than maxsize.

Parameters
----------
container : `lsst.daf.base.PropertySet` or `lsst.daf.base.PropertyList`
    Container from which to get the value

name : `str`
    Name of item

value : `object`
    Value to be assigned a type. Can be an iterable.

Returns
-------
useType : `str` or none
    Type to use for the supplied value. `None` if the input is
    `bool` or a non-integral value.

Definition at line 259 of file propertyContainerContinued.py.

def _guessIntegerType(container, name, value):
    """Given an existing container and name, determine the type
    that should be used for the supplied value. The supplied value
    is assumed to be a scalar.
 
    On Python 3 all ints are LongLong but we need to be able to store them
    in Int containers if that is what is being used (testing for truncation).
    Int is assumed to mean 32bit integer (2147483647 to -2147483648).
 
    If there is no pre-existing value we have to decide what to do. For now
    we pick Int if the value is less than maxsize.
 
    Parameters
    ----------
    container : `lsst.daf.base.PropertySet` or `lsst.daf.base.PropertyList`
        Container from which to get the value
 
    name : `str`
        Name of item
 
    value : `object`
        Value to be assigned a type. Can be an iterable.
 
    Returns
    -------
    useType : `str` or none
        Type to use for the supplied value. `None` if the input is
        `bool` or a non-integral value.
    """
    maxInt = 2147483647
    minInt = -2147483648
    maxLongLong = 2**63 - 1
    minLongLong = -2**63
    maxU64 = 2**64 - 1
    minU64 = 0
 
    # Go through the values to find the range of supplied integers,
    # stopping early if we don't have an integer.
    min = None
    max = None
    for v in _iterable(value):
        # Do not try to convert a bool to an integer
        if not isinstance(v, numbers.Integral) or isinstance(v, bool):
            return None
 
        if min is None:
            min = v
            max = v
        elif v < min:
            min = v
        elif v > max:
            max = v
 
    # Safety net
    if min is None or max is None:
        raise RuntimeError(f"Internal logic failure calculating integer range of {value}")
 
    def _choose_int_from_range(int_value, current_type):
        # If this is changing type from non-integer the current type
        # does not matter.
        if current_type not in {"Int", "LongLong", "UnsignedLongLong"}:
            current_type = None
 
        if int_value <= maxInt and int_value >= minInt and current_type in (None, "Int"):
            # Use Int only if in range and either no current type or the
            # current type is an Int.
            use_type = "Int"
        elif int_value >= minLongLong and int_value < 0:
            # All large negatives must be LongLong if they did not fit
            # in Int clause above.
            use_type = "LongLong"
        elif int_value >= 0 and int_value <= maxLongLong and current_type in (None, "Int", "LongLong"):
            # Larger than Int or already a LongLong
            use_type = "LongLong"
        elif int_value <= maxU64 and int_value >= minU64:
            use_type = "UnsignedLongLong"
        else:
            raise RuntimeError("Unable to guess integer type for storing out of "
                               f"range value: {int_value}")
        return use_type
 
    if container.exists(name):
        containerType = _propertyContainerElementTypeName(container, name)
    else:
        containerType = None
 
    useTypeMin = _choose_int_from_range(min, containerType)
    useTypeMax = _choose_int_from_range(max, containerType)
 
    if useTypeMin == useTypeMax:
        return useTypeMin
 
    # When different the combinations are:
    # Int + LongLong
    # Int + UnsignedLongLong
    # LongLong + UnsignedLongLong
 
    choices = {useTypeMin, useTypeMax}
    if choices == {"Int", "LongLong"}:
        return "LongLong"
 
    # If UnsignedLongLong is required things will break if the min
    # is negative. They will break whatever we choose if that is the case
    # but we have no choice but to return the UnsignedLongLong regardless.
    if "UnsignedLongLong" in choices:
        return "UnsignedLongLong"
 
    raise RuntimeError(f"Logic error in guessing integer type from {min} and {max}")
 
 

_iterable()

lsst.daf.base.propertyContainer.propertyContainerContinued._iterable ( a )

protected

Make input iterable.

Takes whatever is given to it and yields it back one element at a time.
If it is not an iterable or it is a string or PropertySet/List,
yields itself.

Definition at line 243 of file propertyContainerContinued.py.

def _iterable(a):
    """Make input iterable.
 
    Takes whatever is given to it and yields it back one element at a time.
    If it is not an iterable or it is a string or PropertySet/List,
    yields itself.
    """
    if isinstance(a, (str, PropertyList, PropertySet)):
        yield a
        return
    try:
        yield from a
    except Exception:
        yield a
 
 

_makePropertyList()

lsst.daf.base.propertyContainer.propertyContainerContinued._makePropertyList ( state )

protected

Make a `PropertyList` from the state returned by
`getPropertyListState`

Parameters
----------
state : `list`
    The data returned by `getPropertySetState`.

Definition at line 430 of file propertyContainerContinued.py.

def _makePropertyList(state):
    """Make a `PropertyList` from the state returned by
    `getPropertyListState`
 
    Parameters
    ----------
    state : `list`
        The data returned by `getPropertySetState`.
    """
    pl = PropertyList()
    setPropertyListState(pl, state)
    return pl
 
 
@continueClass

_makePropertySet()

lsst.daf.base.propertyContainer.propertyContainerContinued._makePropertySet ( state )

protected

Make a `PropertySet` from the state returned by `getPropertySetState`

Parameters
----------
state : `list`
    The data returned by `getPropertySetState`.

Definition at line 417 of file propertyContainerContinued.py.

def _makePropertySet(state):
    """Make a `PropertySet` from the state returned by `getPropertySetState`
 
    Parameters
    ----------
    state : `list`
        The data returned by `getPropertySetState`.
    """
    ps = PropertySet()
    setPropertySetState(ps, state)
    return ps
 
 

_propertyContainerAdd()

lsst.daf.base.propertyContainer.propertyContainerContinued._propertyContainerAdd ( container, name, value, typeMenu, * args )

protected

Add a single Python value of unknown type

Definition at line 393 of file propertyContainerContinued.py.

def _propertyContainerAdd(container, name, value, typeMenu, *args):
    """Add a single Python value of unknown type
    """
    try:
        exemplar = next(_iterable(value))
    except StopIteration:
        # Adding an empty iterable to an existing entry is a no-op
        # since there is nothing to add.
        return
    t = type(exemplar)
    addType = _guessIntegerType(container, name, exemplar)
 
    if addType is not None or t in typeMenu:
        if addType is None:
            addType = typeMenu[t]
        return getattr(container, "add" + addType)(name, value, *args)
    # Allow for subclasses
    for checkType in typeMenu:
        if (checkType is None and exemplar is None) or \
                (checkType is not None and isinstance(exemplar, checkType)):
            return getattr(container, "add" + typeMenu[checkType])(name, value, *args)
    raise TypeError("Unknown value type for key '%s': %s" % (name, t))
 
 

_propertyContainerElementTypeName()

lsst.daf.base.propertyContainer.propertyContainerContinued._propertyContainerElementTypeName ( container, name )

protected

Return name of the type of a particular element

Parameters
----------
container : `lsst.daf.base.PropertySet` or `lsst.daf.base.PropertyList`
    Container including the element
name : `str`
    Name of element

Definition at line 168 of file propertyContainerContinued.py.

def _propertyContainerElementTypeName(container, name):
    """Return name of the type of a particular element
 
    Parameters
    ----------
    container : `lsst.daf.base.PropertySet` or `lsst.daf.base.PropertyList`
        Container including the element
    name : `str`
        Name of element
    """
    try:
        t = container.typeOf(name)
    except LookupError as e:
        # KeyError is more commonly expected when asking for an element
        # from a mapping.
        raise KeyError(str(e)) from None
 
    return _TYPE_MAP.get(t, None)
 
 

_propertyContainerGet()

lsst.daf.base.propertyContainer.propertyContainerContinued._propertyContainerGet ( container, name, returnStyle )

protected

Get a value of unknown type as a scalar or array

Parameters
----------
container : `lsst.daf.base.PropertySet` or `lsst.daf.base.PropertyList`
    Container from which to get the value
name : `str`
    Name of item
returnStyle : `ReturnStyle`
    Control whether numeric or string data is returned as an array
    or scalar (the other types, ``PropertyList``, ``PropertySet``
        and ``PersistablePtr``, are always returned as a scalar):
    - ReturnStyle.ARRAY: return numeric or string data types
        as an array of values.
    - ReturnStyle.SCALAR: return numeric or string data types
        as a single value; if the item has multiple values then
        return the last value.
    - ReturnStyle.AUTO: (deprecated) return numeric or string data
        as a scalar if there is just one item, or as an array
        otherwise.

Raises
------
KeyError
    Raised if the specified key does not exist in the container.
TypeError
    Raised if the value retrieved is of an unexpected type.
ValueError
    Raised if the value for ``returnStyle`` is not correct.

Definition at line 188 of file propertyContainerContinued.py.

def _propertyContainerGet(container, name, returnStyle):
    """Get a value of unknown type as a scalar or array
 
    Parameters
    ----------
    container : `lsst.daf.base.PropertySet` or `lsst.daf.base.PropertyList`
        Container from which to get the value
    name : `str`
        Name of item
    returnStyle : `ReturnStyle`
        Control whether numeric or string data is returned as an array
        or scalar (the other types, ``PropertyList``, ``PropertySet``
            and ``PersistablePtr``, are always returned as a scalar):
        - ReturnStyle.ARRAY: return numeric or string data types
            as an array of values.
        - ReturnStyle.SCALAR: return numeric or string data types
            as a single value; if the item has multiple values then
            return the last value.
        - ReturnStyle.AUTO: (deprecated) return numeric or string data
            as a scalar if there is just one item, or as an array
            otherwise.
 
    Raises
    ------
    KeyError
        Raised if the specified key does not exist in the container.
    TypeError
        Raised if the value retrieved is of an unexpected type.
    ValueError
        Raised if the value for ``returnStyle`` is not correct.
    """
    if not container.exists(name):
        raise KeyError(name + " not found")
    if returnStyle not in ReturnStyle:
        raise ValueError("returnStyle {} must be a ReturnStyle".format(returnStyle))
 
    elemType = _propertyContainerElementTypeName(container, name)
    if elemType and elemType != "PropertySet":
        value = getattr(container, "getArray" + elemType)(name)
        if returnStyle == ReturnStyle.ARRAY or (returnStyle == ReturnStyle.AUTO and len(value) > 1):
            return value
        return value[-1]
 
    if container.isPropertySetPtr(name):
        try:
            return container.getAsPropertyListPtr(name)
        except Exception:
            return container.getAsPropertySetPtr(name)
    try:
        return container.getAsPersistablePtr(name)
    except Exception:
        pass
    raise TypeError('Unknown PropertySet value type for ' + name)
 
 

_propertyContainerSet()

lsst.daf.base.propertyContainer.propertyContainerContinued._propertyContainerSet ( container, name, value, typeMenu, * args )

protected

Set a single Python value of unknown type

Definition at line 369 of file propertyContainerContinued.py.

def _propertyContainerSet(container, name, value, typeMenu, *args):
    """Set a single Python value of unknown type
    """
    try:
        exemplar = next(_iterable(value))
    except StopIteration:
        # Do nothing if nothing provided. This matches the behavior
        # of the explicit setX() methods.
        return
    t = type(exemplar)
    setType = _guessIntegerType(container, name, value)
 
    if setType is not None or t in typeMenu:
        if setType is None:
            setType = typeMenu[t]
        return getattr(container, "set" + setType)(name, value, *args)
    # Allow for subclasses
    for checkType in typeMenu:
        if (checkType is None and exemplar is None) or \
                (checkType is not None and isinstance(exemplar, checkType)):
            return getattr(container, "set" + typeMenu[checkType])(name, value, *args)
    raise TypeError("Unknown value type for key '%s': %s" % (name, t))
 
 

getPropertyListState()

lsst.daf.base.propertyContainer.propertyContainerContinued.getPropertyListState	(		container,
			asLists = False )

Get the state of a PropertyList in a form that can be pickled.

Parameters
----------
container : `PropertyList`
    The property container.
asLists : `bool`, optional
    If False, the default, `tuple` will be used for the contents. If true
    a `list` will be used.

Returns
-------
state : `list` of `tuple` or `list` of `list`
    The state, as a list of tuples (or lists), each of which contains
    the following 4 items:

    name (a `str`):
        the name of the item
    elementTypeName (a `str`):
        the suffix of a ``setX`` method name
        which is appropriate for the data type. For example integer
        data has ``elementTypeName="Int"` which corresponds to
        the ``setInt`` method.
    value
        the data for the item, in a form compatible
        with the set method named by ``elementTypeName``
    comment (a `str`): the comment. This item is only present
        if ``container`` is a PropertyList.

Definition at line 92 of file propertyContainerContinued.py.

def getPropertyListState(container, asLists=False):
    """Get the state of a PropertyList in a form that can be pickled.
 
    Parameters
    ----------
    container : `PropertyList`
        The property container.
    asLists : `bool`, optional
        If False, the default, `tuple` will be used for the contents. If true
        a `list` will be used.
 
    Returns
    -------
    state : `list` of `tuple` or `list` of `list`
        The state, as a list of tuples (or lists), each of which contains
        the following 4 items:
 
        name (a `str`):
            the name of the item
        elementTypeName (a `str`):
            the suffix of a ``setX`` method name
            which is appropriate for the data type. For example integer
            data has ``elementTypeName="Int"` which corresponds to
            the ``setInt`` method.
        value
            the data for the item, in a form compatible
            with the set method named by ``elementTypeName``
        comment (a `str`): the comment. This item is only present
            if ``container`` is a PropertyList.
    """
    sequence = list if asLists else tuple
    return [sequence((name, _propertyContainerElementTypeName(container, name),
            _propertyContainerGet(container, name, returnStyle=ReturnStyle.AUTO),
            container.getComment(name)))
            for name in container.getOrderedNames()]
 
 

getPropertySetState()

lsst.daf.base.propertyContainer.propertyContainerContinued.getPropertySetState	(		container,
			asLists = False )

Get the state of a PropertySet in a form that can be pickled.

Parameters
----------
container : `PropertySet`
    The property container.
asLists : `bool`, optional
    If False, the default, `tuple` will be used for the contents. If true
    a `list` will be used.

Returns
-------
state : `list` of `tuple` or `list` of `list`
    The state, as a list of tuples (or lists), each of which contains
    the following 3 items:

    name (a `str`)
        the name of the item
    elementTypeName (a `str`)
        the suffix of a ``setX`` method name
        which is appropriate for the data type. For example integer
        data has ``elementTypeName="Int"` which corresponds to
        the ``setInt`` method.
    value
        the data for the item, in a form compatible
        with the set method named by ``elementTypeName``

Definition at line 57 of file propertyContainerContinued.py.

def getPropertySetState(container, asLists=False):
    """Get the state of a PropertySet in a form that can be pickled.
 
    Parameters
    ----------
    container : `PropertySet`
        The property container.
    asLists : `bool`, optional
        If False, the default, `tuple` will be used for the contents. If true
        a `list` will be used.
 
    Returns
    -------
    state : `list` of `tuple` or `list` of `list`
        The state, as a list of tuples (or lists), each of which contains
        the following 3 items:
 
        name (a `str`)
            the name of the item
        elementTypeName (a `str`)
            the suffix of a ``setX`` method name
            which is appropriate for the data type. For example integer
            data has ``elementTypeName="Int"` which corresponds to
            the ``setInt`` method.
        value
            the data for the item, in a form compatible
            with the set method named by ``elementTypeName``
    """
    names = container.names(topLevelOnly=True)
    sequence = list if asLists else tuple
    return [sequence((name, _propertyContainerElementTypeName(container, name),
            _propertyContainerGet(container, name, returnStyle=ReturnStyle.AUTO)))
            for name in names]
 
 

setPropertyListState()

lsst.daf.base.propertyContainer.propertyContainerContinued.setPropertyListState	(		container,
			state )

Restore the state of a PropertyList, in place.

Parameters
----------
container : `PropertyList`
    The property container whose state is to be restored.
    It should be empty to start with and is updated in place.
state : `list`
    The state, as returned by ``getPropertyListState``

Definition at line 147 of file propertyContainerContinued.py.

def setPropertyListState(container, state):
    """Restore the state of a PropertyList, in place.
 
    Parameters
    ----------
    container : `PropertyList`
        The property container whose state is to be restored.
        It should be empty to start with and is updated in place.
    state : `list`
        The state, as returned by ``getPropertyListState``
    """
    for name, elemType, value, comment in state:
        getattr(container, "set" + elemType)(name, value, comment)
 
 

setPropertySetState()

lsst.daf.base.propertyContainer.propertyContainerContinued.setPropertySetState	(		container,
			state )

Restore the state of a PropertySet, in place.

Parameters
----------
container : `PropertySet`
    The property container whose state is to be restored.
    It should be empty to start with and is updated in place.
state : `list`
    The state, as returned by `getPropertySetState`

Definition at line 129 of file propertyContainerContinued.py.

def setPropertySetState(container, state):
    """Restore the state of a PropertySet, in place.
 
    Parameters
    ----------
    container : `PropertySet`
        The property container whose state is to be restored.
        It should be empty to start with and is updated in place.
    state : `list`
        The state, as returned by `getPropertySetState`
    """
    for name, elemType, value in state:
        if elemType is not None:
            getattr(container, "set" + elemType)(name, value)
        else:
            raise ValueError(f"Unrecognized values for state restoration: ({name}, {elemType}, {value})")
 
 

Variable Documentation

_TYPE_MAP

dict lsst.daf.base.propertyContainer.propertyContainerContinued._TYPE_MAP = {}

protected

Definition at line 47 of file propertyContainerContinued.py.

NestedMetadataDict

TypeAlias lsst.daf.base.propertyContainer.propertyContainerContinued.NestedMetadataDict = Mapping[str, Union[str, float, int, bool, "NestedMetadataDict"]]

Definition at line 43 of file propertyContainerContinued.py.

type_obj

lsst.daf.base.propertyContainer.propertyContainerContinued.type_obj = getattr(PropertySet, "TYPE_" + checkType)

Definition at line 51 of file propertyContainerContinued.py.