picos.containers

Domain-specific container types.

Classes

class picos.containers.DetailedType(theClass, subtype)

Bases: object

Container for a pair of Python class and subtype.

A container for a pair of a python class type and some logical subtype data structure, together called a detailed type.

A detailed type is used when the mathematical type of an object must be distinguished more precisely than at the level of the python classes used to represent such mathematical objects. For instance, a single python class would be used for a type of expressions of varying dimensionality and subtypes would be used to distinguish further based on dimension.

Instances of this class are treated exceptionally when used as a label of a RecordTree: They are expanded into the class and the subtype as two seperate labels, making it convenient to store detailed types in trees.

__add__(other)

__eq__(other)

Return self==value.

__init__(theClass, subtype)

Construct a DetailedType.

Parameters

• theClass (type) – The Python class part of the detailed type.

• subtype (object) – Additional type information.

__radd__(other)

equals(other)

Whether two detailed types are the same.

class picos.containers.OrderedSet(iterable=())

Bases: collections.abc.MutableSet

A set that remembers its insertion order.

>>> from picos.containers import OrderedSet as oset
>>> o = oset([4, 3, 2, 1]); o
OrderedSet([4, 3, 2, 1])
>>> 3 in o
True
>>> o.update([5, 4, 3]); o
OrderedSet([4, 3, 2, 1, 5])
>>> list(o)
[4, 3, 2, 1, 5]

__init__(iterable=())

Intialize the ordered set.

Parameters

iterable – Iterable to take initial elements from.

add(element)

Add an element to the set.

clear()

Clear the set.

discard(element)

Discard an element from the set.

If the element is not contained, do nothing.

update(*iterables)

Update the set with elements from a number of iterables.

property difference

Return the difference of two or more sets as a new set.

(i.e. all elements that are in this set but not the others.)

property difference_update

Remove all elements of another set from this set.

property intersection

Return the intersection of two sets as a new set.

(i.e. all elements that are in both sets.)

property intersection_update

Update a set with the intersection of itself and another.

property issubset

Report whether another set contains this set.

property issuperset

Report whether this set contains another set.

property symmetric_difference

Return the symmetric difference of two sets as a new set.

(i.e. all elements that are in exactly one of the sets.)

property symmetric_difference_update

Update a set with the symmetric difference of itself and another.

property union

Return the union of sets as a new set.

(i.e. all elements that are in either set.)

class picos.containers.RecordTree(recordsOrDict=(), addValues=False, freeze=True)

Bases: object

Labeled tree for storing records.

An immutable labeled tree with values at the leaf nodes, where labels and values are arbitrary hashable python objects.

An n-tuple whose first (n-1) elements are labels and whose last element is a value is called a record. Thus, every path from the root node to a leaf node represents one record.

DetailedType labels are treated exceptionally: They are expanded into the class and the subtype as two seperate labels.

class ALL

Bases: picos.containers.RecordTreeToken

Special RecordTree value: Any subtrees.

A special value that behaves as an arbitrary subtree during subtree checks.

class NONE

Bases: picos.containers.RecordTreeToken

Special RecordTree value: No subtrees.

If inserted at some (inner) node of the tree, the whole subtree starting at that node is deleted. If that node’s parent node has no other children, then the parent node is deleted as well. This process is repeated iteratively up to the root node, which is never deleted.

This is the only value that may be inserted at an inner node.

This value cannot itself be stored in the tree as its insertion is always read as a deletion.

__eq__(other)

Return self==value.

__ge__(other)

Perform entrywise greater-or-equal-than comparison.

Each left hand side path must be present on the right hand side, and the associated left hand side value must compare greater-or-equal-than the right hand side value.

__init__(recordsOrDict=(), addValues=False, freeze=True)

Construct a RecordTree.

Parameters

• recordsOrDict (dict or list(tuple)) – Data stored in the tree.

• addValues (bool or list(tuple)) – Add the (numeric) values of records stored in the same place in the tree, instead of replacing the value. If this is exactly a list of path tuples (precise types are required), then add values only for records below any of these paths instead. In either case, resulting values of zero are not stored in the tree.

• freeze (bool) – Whether to transform mutable labels and values into hashable ones.

__le__(other)

Perform entrywise lower-or-equal-than comparison.

Each left hand side path must be present on the right hand side, and the associated left hand side value must compare lower-or-equal-than the right hand side value.

__lshift__(other)

Perform subtree comparison.

Each left hand side path must be present on the right hand side. If the special ALL type is found as a value in the right hand side tree, it is treated as “all possible subtrees”. All other values are not considered.

copy()

Create a shallow copy; the tree is copied, the values are not.

get(path)

Return an empty RecordTree if the path does not exist.

mismatch(other)

A subtree of self that renders self << other False.

Returns RecordTree

The smallest subtree T of self such that self without the records in T is a subtree of other. The returned tree is a direct instance of the RecordTree base class.

updated(recordsOrDict, addValues=False)

Create a shallow copy with modified records.

Example

>>> from picos.modeling.footprint import RecordTree as T
>>> t = T({(1, 1, 1): 3, (1, 1, 2): 4, (1, 2, 1): 5}); t
RecordTree({(1, 1, 1): 3, (1, 1, 2): 4, (1, 2, 1): 5})
>>> t.updated({(1, 1, 1): "a", (2, 2): "b"}) # Change or add a record.
RecordTree({(1, 1, 1): 'a', (1, 1, 2): 4, (1, 2, 1): 5, (2, 2): 'b'})
>>> t.updated({(1,1,1): T.NONE}) # Delete a single record.
RecordTree({(1, 1, 2): 4, (1, 2, 1): 5})
>>> t.updated({(1,1): T.NONE}) # Delete multiple records.
RecordTree({(1, 2, 1): 5})
>>> t.updated([(1, 1, 1, T.NONE), (1, 1, 1, 1, 6)]) # Delete, then add.
RecordTree({(1, 1, 2): 4, (1, 1, 1, 1): 6, (1, 2, 1): 5})
>>> try: # Not possible to implicitly turn a leaf into an inner node.
...     t.updated([(1, 1, 1, 1, 6)])
... except LookupError as error:
...     print(error)
Can't set value '6' at '(1, 1, 1, 1)': Path already contains a leaf.

property dict

Return the tree as a read-only, tuple-indexed dictionary view.

Every key/value pair of the returned dictionary is a record.

property items

Return an iterator over path/value pairs representing records.

property paths

Return an iterator over paths, each representing one record.

property records

Return an iterator over tuples, each representing one record.

property set

Return a frozen set of tuples, each representing one record.

property text

Return the full tree as a multiline string.

class picos.containers.RecordTreeToken

Bases: object

Base class for special RecordTree value tokens.

__init__()

Raise a TypeError on instanciation.

class picos.containers.frozendict

Bases: dict

An immutable, hashable dictionary.

copy()

Since frozendict are immutable, returns self.

classmethod fromkeys(iterable, value=None)

Overwrite dict.fromkeys.

property clear

property pop

If the key is not found, return the default if given; otherwise, raise a KeyError.

property popitem

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

property setdefault

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

property update

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]