picos.containers

Domain-specific container types.

Outline

Classes

DetailedType	Container for a pair of Python class and subtype.
OrderedSet	A set that remembers its insertion order.
RecordTree	Labeled tree for storing records.
RecordTreeToken	Base class for special RecordTree value tokens.

Classes

DetailedType

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.

__init__(theClass, subtype)

Construct a DetailedType.

Parameters

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

• subtype (object) – Additional type information.

equals(other)

Whether two detailed types are the same.

OrderedSet

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

RecordTree

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

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.

__init__(recordsOrDict=(), addValues=False)

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.

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.

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.

RecordTreeToken

class picos.containers.RecordTreeToken

Bases: object

Base class for special RecordTree value tokens.

__init__()

Raise a TypeError on instanciation.