treevalue.tree.general

FastTreeValue

class treevalue.tree.general.FastTreeValue

Overview:

Fast tree value, can do almost anything with this.

__add__(other)

Overview:

Add tree values together.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 11, 'b': 22, 'x': {'c': 30, 'd': 40}})
>>> t1 + t2  # FastTreeValue({'a': 12, 'b': 24, 'x': {'c': 33, 'd': 44}})

__and__(other)

Overview:

Bitwise and tree values.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 2, 'b': 3, 'x': {'c': 4, 'd': 5}})
>>> t1 & t2  # FastTreeValue({'a': 0, 'b': 2, 'x': {'c': 0, 'd': 4}})

__call__(*args, **kwargs)

Overview:

Call of tree values.

Example:

>>> class Container:
>>>     def __init__(self, value):
>>>         self.__value = value
>>>
>>>     def append(self, v):
>>>         return self.__value + v
>>>
>>> t = FastTreeValue({'a': Container(1), 'b': Container(2)})
>>> t.append(2)  # FastTreeValue({'a': 3, 'b': 4})
>>> t.append(FastTreeValue({'a': 10, 'b': 20}))  # FastTreeValue({'a': 11, 'b': 22})

__delattr__()

Delete attribute from tree value.

Parameters:

item – Name of the attribute.

Example:

>>> from treevalue import TreeValue
>>> t = TreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> del t.a
>>> t
<TreeValue 0x7fd2251ae320>
├── 'b' --> 2
└── 'x' --> <TreeValue 0x7fd2553f00b8>
    ├── 'c' --> 3
    └── 'd' --> 4
>>> del t.x.c
>>> t
<TreeValue 0x7fd2251ae320>
├── 'b' --> 2
└── 'x' --> <TreeValue 0x7fd2553f00b8>
    └── 'd' --> 4

__delitem__(key)

Overview:

Delete item of tree values.

Examples:

>>> from treevalue import FastTreeValue, raw
>>> t1 = FastTreeValue({'a': [1, 2], 'b': [2, 3], 'x': {'c': [3, 4], 'd': [4, 5]}})
>>> del t1[0]
>>> t1
<FastTreeValue 0x7fa9c8c366a0>
├── 'a' --> [2]
├── 'b' --> [3]
└── 'x' --> <FastTreeValue 0x7fa9c8a7b0b8>
    ├── 'c' --> [4]
    └── 'd' --> [5]
>>> del t1['b']
>>> t1
<FastTreeValue 0x7fa9c8c366a0>
├── 'a' --> [2]
└── 'x' --> <FastTreeValue 0x7fa9c8a7b0b8>
    ├── 'c' --> [4]
    └── 'd' --> [5]

Note

If you need to delete the string items from the node values, you can use double bracket. For example

>>> from treevalue import FastTreeValue, raw
>>> tv4 = FastTreeValue({
...     'a': raw({'a': 1, 'y': 2}),
...     'c': {'x': raw({'a': 3, 'y': 4})},
...     'g': {'x': raw({'a': 31, 'y': 42})},
... })
>>> del tv4['g']  # key delete
>>> tv4
<FastTreeValue 0x7fa9c8c36978>
├── 'a' --> {'a': 1, 'y': 2}
└── 'c' --> <FastTreeValue 0x7fa9c8c36d30>
    └── 'x' --> {'a': 3, 'y': 4}
>>> del tv4[['a']]  # value delete
>>> tv4
<FastTreeValue 0x7fa9c8c36978>
├── 'a' --> {'y': 2}
└── 'c' --> <FastTreeValue 0x7fa9c8c36d30>
    └── 'x' --> {'y': 4}

__eq__()

Check the equality of two tree values.

Parameters:

other – Another tree value object.

Returns:

Equal or not.

Example:

>>> from treevalue import TreeValue, clone, FastTreeValue
>>> t = TreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t == TreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})      # True
>>> t == TreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 5}})      # False
>>> t == FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})  # False (type not match)

__floordiv__(other)

Overview:

Floor divide tree values.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 10, 'b': 25, 'x': {'c': 30, 'd': 40}})
>>> t2 // t1  # FastTreeValue({'a': 10, 'b': 12, 'x': {'c': 10, 'd': 10}})

__getattribute__()

Get item from this tree value.

Parameters:

item – Name of attribute.

Returns:

Target attribute value; if item is exist in keys(), return its value.

Example:

>>> from treevalue import TreeValue
>>> t = TreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t.a
1
>>> t.b
2
>>> t.x
<TreeValue 0x7fd2553e3fd0>
├── 'c' --> 3
└── 'd' --> 4
>>> t.x.c
3
>>> t.keys  # this is a method
<bound method TreeValue.keys of <TreeValue 0x7fd2553f00b8>>
>>> t.ff  # this key is not exist
AttributeError: Attribute 'ff' not found.

__getitem__(item)

Overview:

Get item of tree values.

Examples:

>>> from treevalue import FastTreeValue
>>> t1 = FastTreeValue({'a': [1, 2], 'b': [2, 3], 'x': {'c': [3, 4], 'd': [4, 5]}})
>>> t1['a']  # key access
[1, 2]
>>> t1[0]  # value access
<FastTreeValue 0x7fa9c8c36cf8>
├── 'a' --> 1
├── 'b' --> 2
└── 'x' --> <FastTreeValue 0x7fa9c8c369e8>
    ├── 'c' --> 3
    └── 'd' --> 4
>>> t1[-1]
<FastTreeValue 0x7fa9c8a72dd8>
├── 'a' --> 2
├── 'b' --> 3
└── 'x' --> <FastTreeValue 0x7fa9c8c36978>
    ├── 'c' --> 4
    └── 'd' --> 5
>>> t1[::-1]
<FastTreeValue 0x7fa9c8c36d30>
├── 'a' --> [2, 1]
├── 'b' --> [3, 2]
└── 'x' --> <FastTreeValue 0x7fa9c8c36cf8>
    ├── 'c' --> [4, 3]
    └── 'd' --> [5, 4]
>>> t1['x'][0]  # mixed access
<FastTreeValue 0x7fa9c8a7b0b8>
├── 'c' --> 3
└── 'd' --> 4

Note

If you need to get the string items from the node values, you can use double bracket. For example

>>> from treevalue import FastTreeValue, raw
>>> tv4 = FastTreeValue({
...     'a': raw({'a': 1, 'y': 2}),
...     'c': {'x': raw({'a': 3, 'y': 4})},
... })
>>> tv4['a']  # key access
{'a': 1, 'y': 2}
>>> tv4[['a']]  # value access
<FastTreeValue 0x7fa9c8c36588>
├── 'a' --> 1
└── 'c' --> <FastTreeValue 0x7fa9c8a7b0b8>
    └── 'x' --> 3

__getstate__()

Serialize operation, can support pickle.dumps.

Returns:

A treevalue.tree.common.TreeStorage object, used for serialization.

Examples:

>>> import pickle
>>> from treevalue import TreeValue
>>>
>>> t = TreeValue({'a': 1, 'b': 2, 'x': {'c': 3}})
>>> bin_ = pickle.dumps(t)  # dump it to binary
>>> pickle.loads(bin_)      #  TreeValue({'a': 1, 'b': 2, 'x': {'c': 3}})

__hash__()

Hash value of current object.

Returns:

Hash value of current object.

Note

If the structure and hash values of two tree values are exactly the same, their hash value is guaranteed to be the same.

__iadd__(other)

Overview:

Self version of __add__. Original id of self will be kept.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 11, 'b': 22, 'x': {'c': 30, 'd': 40}})
>>> t1 += t2
>>> t1 # t1's id will not change, FastTreeValue({'a': 12, 'b': 24, 'x': {'c': 33, 'd': 44}})

__iand__(other)

Overview:

Self version of __and__. Original id of self will be kept.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 2, 'b': 3, 'x': {'c': 4, 'd': 5}})
>>> t1 &= t2
>>> t1 # t1's id will not change, FastTreeValue({'a': 0, 'b': 2, 'x': {'c': 0, 'd': 4}})

__ifloordiv__(other)

Overview:

Self version of __floordiv__. Original id of self will be kept.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 10, 'b': 25, 'x': {'c': 30, 'd': 40}})
>>> t2 //= t1
>>> t2 # t2's id will not change, FastTreeValue({'a': 10, 'b': 12, 'x': {'c': 10, 'd': 10}})

__ilshift__(other)

Overview:

Self version of __xor__. Original id of self will be kept.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 2, 'b': 3, 'x': {'c': 4, 'd': 5}})
>>> t1 <<= t2
>>> t1 # t1's id will not change, FastTreeValue({'a': 4, 'b': 16, 'x': {'c': 48, 'd': 128}})

__imatmul__(other)

Overview:

Self version of __matmul__. Original id of self will be kept.

__imod__(other)

Overview:

Self version of __mod__. Original id of self will be kept.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 10, 'b': 25, 'x': {'c': 30, 'd': 40}})
>>> t2 %= t1
>>> t2 # t2's id will not change, FastTreeValue({'a': 0, 'b': 1, 'x': {'c': 0, 'd': 0}})

__imul__(other)

Overview:

Self version of __mul__. Original id of self will be kept.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 11, 'b': 22, 'x': {'c': 30, 'd': 40}})
>>> t1 *= t2
>>> t1 # t1's id will not change, FastTreeValue({'a': 11, 'b': 44, 'x': {'c': 90, 'd': 160}})

__invert__()

Overview:

Bitwise invert tree values.

Examples:

>>> t1 = FastTreeValue({'a': 1, 'b': -2, 'x': {'c': 3, 'd': -4}})
>>> ~t1  # FastTreeValue({'a': -2, 'b': 1, 'x': {'c': -4, 'd': 3}})

__ior__(other)

Overview:

Self version of __or__. Original id of self will be kept.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 2, 'b': 3, 'x': {'c': 4, 'd': 5}})
>>> t1 |= t2
>>> t1 # t1's id will not change, FastTreeValue({'a': 3, 'b': 3, 'x': {'c': 7, 'd': 5}})

__ipow__(other)

Overview:

Self version of __pow__. Original id of self will be kept.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 2, 'b': 3, 'x': {'c': 4, 'd': 5}})
>>> t1 **= t2
>>> t1 # t1's id will not change, FastTreeValue({'a': 1, 'b': 8, 'x': {'c': 81, 'd': 1024}})

__irshift__(other)

Overview:

Self version of __xor__. Original id of self will be kept.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 20, 'b': 30, 'x': {'c': 40, 'd': 50}})
>>> t2 >>= t1
>>> t2 # t2's id will not change, FastTreeValue({'a': 10, 'b': 7, 'x': {'c': 5, 'd': 3}})

__isub__(other)

Overview:

Self version of __sub__. Original id of self will be kept.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 11, 'b': 22, 'x': {'c': 30, 'd': 40}})
>>> t1 -= t2
>>> t1 # t1's id will not change, FastTreeValue({'a': -10, 'b': -20, 'x': {'c': -27, 'd': -36}})

__iter__()

Get iterator of this tree value.

Returns:

An iterator for the keys.

Examples:

>>> from treevalue import TreeValue
>>> t = TreeValue({'a': 1, 'b': 2, 'x': 3})
>>> for key in t:
...     print(key)
a
b
x

Note

The method __iter__()’s bahaviour should be similar to dict.__iter__.

__itruediv__(other)

Overview:

Self version of __truediv__. Original id of self will be kept.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 10, 'b': 25, 'x': {'c': 30, 'd': 40}})
>>> t1 /= t2
>>> t1 # t1's id will not change, FastTreeValue({'a': 0.1, 'b': 0.08, 'x': {'c': 0.1, 'd': 0.1}})

__ixor__(other)

Overview:

Self version of __xor__. Original id of self will be kept.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 2, 'b': 3, 'x': {'c': 4, 'd': 5}})
>>> t1 ^= t2
>>> t1 # t1's id will not change, FastTreeValue({'a': 3, 'b': 1, 'x': {'c': 7, 'd': 1}})

__lshift__(other)

Overview:

Left shift tree values.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 2, 'b': 3, 'x': {'c': 4, 'd': 5}})
>>> t1 << t2  # FastTreeValue({'a': 4, 'b': 16, 'x': {'c': 48, 'd': 128}})

__matmul__(other)

Overview:

Matrix tree values together, can be used in numpy or torch.

__mod__(other)

Overview:

Mod tree values.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 10, 'b': 25, 'x': {'c': 30, 'd': 40}})
>>> t2 % t1  # FastTreeValue({'a': 0, 'b': 1, 'x': {'c': 0, 'd': 0}})

__mul__(other)

Overview:

Multiply tree values together.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 11, 'b': 22, 'x': {'c': 30, 'd': 40}})
>>> t1 * t2  # FastTreeValue({'a': 11, 'b': 44, 'x': {'c': 90, 'd': 160}})

__neg__()

Overview:

Negative tree values.

Examples:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> -t1  # FastTreeValue({'a': -1, 'b': -2, 'x': {'c': -3, 'd': -4}})

__or__(other)

Overview:

Bitwise or tree values.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 2, 'b': 3, 'x': {'c': 4, 'd': 5}})
>>> t1 | t2  # FastTreeValue({'a': 3, 'b': 3, 'x': {'c': 7, 'd': 5}})

__pos__()

Overview:

Positive tree values.

Examples:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> +t1  # FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})

__pow__(power)

Overview:

Mod tree values.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 2, 'b': 3, 'x': {'c': 4, 'd': 5}})
>>> t1 ** t2  # FastTreeValue({'a': 1, 'b': 8, 'x': {'c': 81, 'd': 1024}})

__radd__(other)

Overview:

Right version of __add__.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> 1 + t1  # FastTreeValue({'a': 2, 'b': 3, 'x': {'c': 4, 'd': 5}})

__rand__(other)

Overview:

Right version of __and__.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> 5 & t1  # FastTreeValue({'a': 1, 'b': 0, 'x': {'c': 1, 'd': 4}})

__repr__()

Get representation format of tree value.

Returns:

Represenation string.

Example:

>>> t = TreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t
<TreeValue 0x7f672fc53320>
├── 'a' --> 1
├── 'b' --> 2
└── 'x' --> <TreeValue 0x7f672fc53390>
    ├── 'c' --> 3
    └── 'd' --> 4

__rfloordiv__(other)

Overview:

Right version of __floordiv__.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> 6 // t1  # FastTreeValue({'a': 6, 'b': 3, 'x': {'c': 2, 'd': 1}})

__rlshift__(other)

Overview:

Right version of __lshift__.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> 3 << t1  # FastTreeValue({'a': 6, 'b': 12, 'x': {'c': 24, 'd': 48}})

__rmatmul__(other)

Overview:

Right version of __matmul__.

__rmod__(other)

Overview:

Right version of __mod__.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> 6 % t1  # FastTreeValue({'a': 0, 'b': 0, 'x': {'c': 0, 'd': 2}})

__rmul__(other)

Overview:

Right version of __mul__.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> 2 * t1  # FastTreeValue({'a': 2, 'b': 4, 'x': {'c': 6, 'd': 8}})

__ror__(other)

Overview:

Right version of __or__.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> 5 | t1  # FastTreeValue({'a': 5, 'b': 7, 'x': {'c': 7, 'd': 5}})

__rpow__(other)

Overview:

Right version of __pow__.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> 2 ** t1  # FastTreeValue({'a': 2, 'b': 4, 'x': {'c': 8, 'd': 16}})

__rrshift__(other)

Overview:

Right version of __rshift__.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> 64 >> t1  # FastTreeValue({'a': 32, 'b': 16, 'x': {'c': 8, 'd': 4}})

__rshift__(other)

Overview:

Left shift tree values.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 20, 'b': 30, 'x': {'c': 40, 'd': 50}})
>>> t2 >> t1  # FastTreeValue({'a': 10, 'b': 7, 'x': {'c': 5, 'd': 3}})

__rsub__(other)

Overview:

Right version of __sub__.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> 1 - t1  # FastTreeValue({'a': 0, 'b': -1, 'x': {'c': -2, 'd': -3}})

__rtruediv__(other)

Overview:

Right version of __truediv__.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> 6 / t1  # FastTreeValue({'a': 6, 'b': 3, 'x': {'c': 2, 'd': 1.5}})

__rxor__(other)

Overview:

Right version of __xor__.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> 5 ^ t1  # FastTreeValue({'a': 4, 'b': 7, 'x': {'c': 6, 'd': 1}})

__setattr__()

Set sub node to this tree value.

Parameters:

• key – Name of the attribute.

• value – Sub value.

Example:

>>> from treevalue import TreeValue
>>> t = TreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t.a = 3  # set a value
>>> t
<TreeValue 0x7fd2553f0048>
├── 'a' --> 3
├── 'b' --> 2
└── 'x' --> <TreeValue 0x7fd2553f0080>
    ├── 'c' --> 3
    └── 'd' --> 4
>>> t.b = {'x': 1, 'y': 2}  # set a dict
>>> t
<TreeValue 0x7fd2553f0048>
├── 'a' --> 3
├── 'b' --> {'x': 1, 'y': 2}
└── 'x' --> <TreeValue 0x7fd2553f0080>
    ├── 'c' --> 3
    └── 'd' --> 4
>>> t.b = TreeValue({'x': 1, 'y': 2})  # set a tree
>>> t
<TreeValue 0x7fd2553f0048>
├── 'a' --> 3
├── 'b' --> <TreeValue 0x7fd2553e3fd0>
│   ├── 'x' --> 1
│   └── 'y' --> 2
└── 'x' --> <TreeValue 0x7fd2553f0080>
    ├── 'c' --> 3
    └── 'd' --> 4

__setitem__(key, value)

Overview:

Set item of tree values.

Examples:

>>> from treevalue import FastTreeValue
>>> t1 = FastTreeValue({'a': [1, 2], 'b': [2, 3], 'x': {'c': [3, 4], 'd': [4, 5]}})
>>> t1[0] = -2
>>> t1
<FastTreeValue 0x7fa9c8c36518>
├── 'a' --> [-2, 2]
├── 'b' --> [-2, 3]
└── 'x' --> <FastTreeValue 0x7fa9c8a72dd8>
    ├── 'c' --> [-2, 4]
    └── 'd' --> [-2, 5]
>>> t1[0] = FastTreeValue({'a': 2, 'b': 3, 'x': {'c': 4, 'd': 5}})
>>> t1
<FastTreeValue 0x7fa9c8c36518>
├── 'a' --> [2, 2]
├── 'b' --> [3, 3]
└── 'x' --> <FastTreeValue 0x7fa9c8a72dd8>
    ├── 'c' --> [4, 4]
    └── 'd' --> [5, 5]
>>> t1['b'] = [22, 33]
>>> t1
<FastTreeValue 0x7fa9c8c36518>
├── 'a' --> [2, 2]
├── 'b' --> [22, 33]
└── 'x' --> <FastTreeValue 0x7fa9c8a72dd8>
    ├── 'c' --> [4, 4]
    └── 'd' --> [5, 5]

Note

If you need to set the string items from the node values, you can use double bracket. For example

>>> from treevalue import FastTreeValue, raw
>>> tv4 = FastTreeValue({
...     'a': raw({'a': 1, 'y': 2}),
...     'c': {'x': raw({'a': 3, 'y': 4})},
... })
>>> tv4['a'] = {'a': 11, 'y': 22}  # key access
>>> tv4
<FastTreeValue 0x7fa9c8c36588>
├── 'a' --> {'a': 11, 'y': 22}
└── 'c' --> <FastTreeValue 0x7fa9c8c369e8>
    └── 'x' --> {'a': 3, 'y': 4}
>>> tv4[['a']] = -2  # value access
>>> tv4
<FastTreeValue 0x7fa9c8c36588>
├── 'a' --> {'a': -2, 'y': 22}
└── 'c' --> <FastTreeValue 0x7fa9c8c369e8>
    └── 'x' --> {'a': -2, 'y': 4}

__setstate__(state)

Deserialize operation, can support pickle.loads.

Parameters:

state – treevalue.tree.common.TreeStorage object, which should be used when deserialization.

Examples:

>>> import pickle
>>> from treevalue import TreeValue
>>>
>>> t = TreeValue({'a': 1, 'b': 2, 'x': {'c': 3}})
>>> bin_ = pickle.dumps(t)  # dump it to binary
>>> pickle.loads(bin_)      #  TreeValue({'a': 1, 'b': 2, 'x': {'c': 3}})

__str__()

Return str(self).

__sub__(other)

Overview:

Substract tree values.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 11, 'b': 22, 'x': {'c': 30, 'd': 40}})
>>> t1 - t2  # FastTreeValue({'a': -10, 'b': -20, 'x': {'c': -27, 'd': -36}})

__truediv__(other)

Overview:

True divide tree values.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 10, 'b': 25, 'x': {'c': 30, 'd': 40}})
>>> t1 / t2  # FastTreeValue({'a': 0.1, 'b': 0.08, 'x': {'c': 0.1, 'd': 0.1}})

__xor__(other)

Overview:

Bitwise or tree values.

Example:

>>> t1 = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = FastTreeValue({'a': 2, 'b': 3, 'x': {'c': 4, 'd': 5}})
>>> t1 ^ t2  # FastTreeValue({'a': 3, 'b': 1, 'x': {'c': 7, 'd': 1}})

_attr_extern(key)

Overview:

External protected function for support the unfounded attributes. In FastTreeValue it is extended to support the access to values’ attribute.

Arguments:

• key (str): Attribute name.

Returns:

• return (:obj:): TreeValue of the values’ attribute.

Example:

>>> class Container:
>>>     def __init__(self, value):
>>>         self.__value = value
>>>
>>>     @property
>>>     def value(self):
>>>         return self.__value
>>>
>>>     def append(self, v):
>>>         return self.__value + v
>>>
>>> t = FastTreeValue({'a': Container(1), 'b': Container(2)})
>>> t.value   # FastTreeValue({'a': 1, 'b': 2})
>>> t.append  # FastTreeValue({'a': <method 'append' of Container(1)>, 'b': <method 'append' of Container(2)>})

clone(copy_value: Union[None, bool, Callable, Any] = None)

Overview:

Create a fully clone of the current tree.

Returns:

• tree (_TreeValue): Cloned tree value object.

• copy_value (Union[None, bool, Callable, Any]): Deep copy value or not, default is None which means do not deep copy the values. If deep copy is required, just set it to True.

Example:

>>> t = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t.x.clone()  # FastTreeValue({'c': 3, 'd': 4})

filter(func, remove_empty: bool = True)

Overview:

Filter the element in the tree with a predict function.

Arguments:

• func (:obj:): Function for filtering

• remove_empty (bool): Remove empty tree node automatically, default is True.

Returns:

• tree (_TreeValue): Filtered tree value object.

Example:

>>> t = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t.filter(lambda x: x < 3)                  # FastTreeValue({'a': 1, 'b': 2})
>>> t.filter(lambda x: x < 3, False)           # FastTreeValue({'a': 1, 'b': 2, 'x': {}})
>>> t.filter(lambda x: x % 2 == 1)             # FastTreeValue({'a': 1, 'x': {'c': 3}})
>>> t.filter(lambda x, p: p[0] in {'b', 'x'})  # FastTreeValue({'b': 2, 'x': {'c': 3, 'd': 4}})

classmethod func(mode: str = 'strict', inherit: bool = True, missing: Union[Any, Callable] = <SingletonMark 'missing_not_allow'>, delayed: bool = False, subside: Optional[Union[Mapping, bool]] = None, rise: Optional[Union[Mapping, bool]] = None)

Overview:

Wrap a common function to tree-supported function based on this type.

Arguments:

• mode (str): Mode of the wrapping, default is strict.

• inherit (bool): Allow inherit in wrapped function, default is True.

• missing (Union[Any, Callable]): Missing value or lambda generator of when missing, default is MISSING_NOT_ALLOW, which means raise KeyError when missing detected.

• delayed (bool): Enable delayed mode or not, the calculation will be delayed when enabled, default is False, which means to all the calculation at once.

• subside (Union[Mapping, bool, None]): Subside enabled to function’s arguments or not, and subside configuration, default is None which means do not use subside. When subside is True, it will use all the default arguments in subside function.

• rise (Union[Mapping, bool, None]): Rise enabled to function’s return value or not, and rise configuration, default is None which means do not use rise. When rise is True, it will use all the default arguments in rise function. (Not recommend to use auto mode when your return structure is not so strict.)

Returns:

• decorator (Callable): Wrapper for tree-supported function.

Example:

>>> from treevalue import FastTreeValue
>>>
>>> @FastTreeValue.func()
>>> def ssum(a, b):
>>>     return a + b  # the a and b will be integers, not TreeValue
>>>
>>> t1 = TreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = TreeValue({'a': 11, 'b': 22, 'x': {'c': 33, 'd': 5}})
>>> ssum(1, 2)    # 3
>>> ssum(t1, t2)  # FastTreeValue({'a': 12, 'b': 24, 'x': {'c': 36, 'd': 9}})

graph(root: Optional[str] = None, title: Optional[str] = None, cfg: Optional[dict] = None, dup_value: Union[bool, Callable, treevalue.tree.general.general.general_tree_value.<locals>._GeneralTreeValue.type, Tuple[Type, ...]] = False, repr_gen: Optional[Callable] = None, node_cfg_gen: Optional[Callable] = None, edge_cfg_gen: Optional[Callable] = None) → graphviz.graphs.Digraph

Overview:

Draw graph of this tree value.

Args:

• root (Optional[str]): Root name of the graph, default is None, this name will be automatically generated.

• title (Optional[str]): Title of the graph, default is None, this title will be automatically generated from root argument.

• cfg (Optional[dict]): Configuration of the graph.

• dup_value (Union[bool, Callable, type, Tuple[Type, ...]]): Value duplicator, set True to make value with same id use the same node in graph, you can also define your own node id algorithm by this argument. Default is False which means do not use value duplicator.

• repr_gen (Optional[Callable]): Representation format generator, default is None which means using repr function.

• node_cfg_gen (Optional[Callable]): Node configuration generator, default is None which means no configuration.

• edge_cfg_gen (Optional[Callable]): Edge configuration generator, default is None which means no configuration.

Returns:

• graph (Digraph): Generated graph of tree values.

classmethod graphics(*trees, title: Optional[str] = None, cfg: Optional[dict] = None, dup_value: Union[bool, Callable, treevalue.tree.general.general.general_tree_value.<locals>._GeneralTreeValue.type, Tuple[Type, ...]] = False, repr_gen: Optional[Callable] = None, node_cfg_gen: Optional[Callable] = None, edge_cfg_gen: Optional[Callable] = None) → graphviz.graphs.Digraph

Overview:

Draw graph by tree values. Multiple tree values is supported.

Args:

• trees: Given tree values, tuples of Tuple[TreeValue, str] or tree values are both accepted.

• title (Optional[str]): Title of the graph.

• cfg (Optional[dict]): Configuration of the graph.

• dup_value (Union[bool, Callable, type, Tuple[Type, ...]]): Value duplicator, set True to make value with same id use the same node in graph, you can also define your own node id algorithm by this argument. Default is False which means do not use value duplicator.

• repr_gen (Optional[Callable]): Representation format generator, default is None which means using repr function.

• node_cfg_gen (Optional[Callable]): Node configuration generator, default is None which means no configuration.

• edge_cfg_gen (Optional[Callable]): Edge configuration generator, default is None which means no configuration.

Returns:

• graph (Digraph): Generated graph of tree values.

items()

Get pairs of keys and values of this treevalue object, like the items.

Returns:

A mapping object for tree value’s items.

Examples:

>>> from treevalue import TreeValue
>>> 
>>> t = TreeValue({'a': 1, 'b': 3, 'c': '233'})
>>> t.items()
treevalue_items([('a', 1), ('b', 3), ('c', '233')])
>>> len(t.items())
3
>>> list(t.items())
[('a', 1), ('b', 3), ('c', '233')]
>>> list(reversed(t.items()))  # only supported on python3.8+
[('c', '233'), ('b', 3), ('a', 1)]
>>> ('a', 1) in t.items()
True
>>> ('c', '234') in t.values()
False

Note

reversed() is only available in python 3.8 or higher versions.

json()

Overview:

Dump current TreeValue object to json data.

Returns:

• json (dict): Dumped json data.

Example:

>>> t = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t.json()  # {'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}}

keys()

Get keys of this treevalue object, like the dict.

Returns:

A mapping object for tree value’s keys.

Examples:

>>> from treevalue import TreeValue
>>> 
>>> t = TreeValue({'a': 1, 'b': 3, 'c': '233'})
>>> t.keys()
treevalue_keys(['a', 'b', 'c'])
>>> len(t.keys())
3
>>> list(t.keys())
['a', 'b', 'c']
>>> list(reversed(t.keys()))  # only available in python3.8+
['c', 'b', 'a']
>>> 'a' in t.keys()
True
>>> 'f' in t.keys()
False

Note

reversed() is only available in python 3.8 or higher versions.

map(mapper, delayed=False)

Overview:

Do mapping on every value in this tree.

Arguments:

• func (:obj:): Function for mapping

• delayed (bool): Enable delayed mode for this mapping.

Returns:

• tree (_TreeValue): Mapped tree value object.

Example:

>>> t = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t.map(lambda x: x + 2)  # FastTreeValue({'a': 3, 'b': 4, 'x': {'c': 5, 'd': 6}})
>>> t.map(lambda: 1)        # FastTreeValue({'a': 1, 'b': 1, 'x': {'c': 1, 'd': 1}})
>>> t.map(lambda x, p: p)   # FastTreeValue({'a': ('a',), 'b': ('b',), 'x': {'c': ('x', 'c'), 'd': ('x', 'd')}})

mask(mask_: treevalue.tree.tree.tree.TreeValue, remove_empty: bool = True)

Overview:

Filter the element in the tree with a mask

Arguments:

• mask_ (TreeValue): Tree value mask object

• remove_empty (bool): Remove empty tree node automatically, default is True.

Returns:

• tree (_TreeValue): Filtered tree value object.

Example:

>>> t = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t.mask(TreeValue({'a': True, 'b': False, 'x': False}))                    # FastTreeValue({'a': 1})
>>> t.mask(TreeValue({'a': True, 'b': False, 'x': {'c': True, 'd': False}}))  # FastTreeValue({'a': 1, 'x': {'c': 3}})

reduce(func)

Overview

Reduce the tree to value.

Arguments:

• func (:obj:): Function for reducing

Returns:

• result (:obj:): Reduce result

Examples:

>>> from functools import reduce
>>>
>>> t = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t.reduce(lambda **kwargs: sum(kwargs.values()))  # 10, 1 + 2 + (3 + 4)
>>> t.reduce(lambda **kwargs: reduce(lambda x, y: x * y, list(kwargs.values())))  # 24, 1 * 2 * (3 * 4)

rise(dict_: bool = True, list_: bool = True, tuple_: bool = True, template=None)

Overview:

Make the structure (dict, list, tuple) in value rise up to the top, above the tree value.

Arguments:

• dict_ (bool): Enable dict rise, default is True.

• list_ (bool): Enable list rise, default is True.

• tuple_ (bool): Enable list rise, default is True.

• template (:obj:): Rising template, default is None, which means auto detect.

Returns:

• risen (:obj:): Risen value.

Example:

>>> t = FastTreeValue({'x': raw({'a': [1, 2], 'b': [2, 3]}), 'y': raw({'a': [5, 6, 7], 'b': [7, 8]})})
>>> dt = t.rise()
>>> # dt will be {'a': <FastTreeValue 1>, 'b': [<FastTreeValue 2>, <FastTreeValue 3>]}
>>> # FastTreeValue 1 will be FastTreeValue({'x': [1, 2], 'y': [5, 6, 7]})
>>> # FastTreeValue 2 will be FastTreeValue({'x': 2, 'y': 7})
>>> # FastTreeValue 3 will be FastTreeValue({'x': 3, 'y': 8})
>>>
>>> t2 = FastTreeValue({'x': raw({'a': [1, 2], 'b': [2, 3]}), 'y': raw({'a': [5, 6], 'b': [7, 8]})})
>>> dt2 = t2.rise()
>>> # dt2 will be {'a': [<FastTreeValue 1>, <FastTreeValue 2>], 'b': [<FastTreeValue 3>, <FastTreeValue 4>]}
>>> # FastTreeValue 1 will be FastTreeValue({'x': 1, 'y': 5})
>>> # FastTreeValue 2 will be FastTreeValue({'x': 2, 'y': 6})
>>> # FastTreeValue 3 will be FastTreeValue({'x': 2, 'y': 7})
>>> # FastTreeValue 4 will be FastTreeValue({'x': 3, 'y': 8})
>>>
>>> dt3 = t2.rise(template={'a': None, 'b': None})
>>> # dt3 will be {'a': <FastTreeValue 1>, 'b': <FastTreeValue 2>}
>>> # FastTreeValue 1 will be FastTreeValue({'x': [1, 2], 'y': [5, 6]})
>>> # FastTreeValue 2 will be FastTreeValue({'x': [2, 3], 'y': [7, 8]})

classmethod subside(value, dict_: bool = True, list_: bool = True, tuple_: bool = True, return_type: Optional[Type[_TreeValue]] = None, **kwargs)

Overview:

Drift down the structures (list, tuple, dict) down to the tree’s value.

Arguments:

• value (:obj:): Original value object, may be nested dict, list or tuple.

• dict_ (bool): Enable dict subside, default is True.

• list_ (bool): Enable list subside, default is True.

• tuple_ (bool): Enable list subside, default is True.

• mode (:obj:): Mode of the wrapping, default is strict.

• return_type (Optional[Type[_ClassType]]): Return type of the wrapped function, will be auto detected when there is exactly one tree value type in this original value, otherwise the default will be TreeValue.

• inherit (bool): Allow inherit in wrapped function, default is True.

• missing (:obj:): Missing value or lambda generator of when missing, default is MISSING_NOT_ALLOW, which means raise KeyError when missing detected.

Returns:

• return (_TreeValue): Subsided tree value.

Example:

>>> data = {
>>>     'a': TreeValue({'a': 1, 'b': 2}),
>>>     'x': {
>>>         'c': TreeValue({'a': 3, 'b': 4}),
>>>         'd': [
>>>             TreeValue({'a': 5, 'b': 6}),
>>>             TreeValue({'a': 7, 'b': 8}),
>>>         ]
>>>     },
>>>     'k': '233'
>>> }
>>>
>>> tree = FastTreeValue.subside(data)
>>> # tree should be --> FastTreeValue({
>>> #    'a': raw({'a': 1, 'k': '233', 'x': {'c': 3, 'd': [5, 7]}}),
>>> #    'b': raw({'a': 2, 'k': '233', 'x': {'c': 4, 'd': [6, 8]}}),
>>> #}), all structures above the tree values are subsided to the bottom of the tree.

type(clazz: Type[_TreeValue]) → _TreeValue

Overview:

Transform tree value object to another tree value type. Attention that in this function, no copy will be made, the original tree value and the transformed tree value are using the same space area.

Arguments:

• return_type (Type[_TreeValue]): Target tree value type

Returns:

• tree (_TreeValue): Transformed tree value object.

Example:

>>> t = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t.type(TreeValue)  # TreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})

classmethod union(*trees, return_type=None, **kwargs)

Overview:

Union tree values together.

Arguments:

• trees (_TreeValue): Tree value objects.

• mode (:obj:): Mode of the wrapping, default is strict.

• return_type (Optional[Type[_ClassType]]): Return type of the wrapped function, default is TreeValue.

• inherit (bool): Allow inherit in wrapped function, default is True.

• missing (:obj:): Missing value or lambda generator of when missing, default is MISSING_NOT_ALLOW, which means raise KeyError when missing detected.

Returns:

• result (TreeValue): Unionised tree value.

Example:

>>> t = FastTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> tx = t.map(lambda v: v % 2 == 1)
>>> FastTreeValue.union(t, tx)  # FastTreeValue({'a': (1, True), 'b': (2, False), 'x': {'c': (3, True), 'd': (4, False)}})

values()

Get value of this treevalue object, like the dict.

Returns:

A mapping object for tree value’s values.

Examples:

>>> from treevalue import TreeValue
>>> 
>>> t = TreeValue({'a': 1, 'b': 3, 'c': '233'})
>>> t.values()
treevalue_values([1, 3, '233'])
>>> len(t.values())
3
>>> list(t.values())
[1, 3, '233']
>>> list(reversed(t.values()))  # only supported on python3.8+
['233', 3, 1]
>>> 1 in t.values()
True
>>> 'fff' in t.values()
False

Note

reversed() is only available in python 3.8 or higher versions.

walk()

Overview:

Walk the values and nodes in the tree. The order of walk is not promised, if you need the ordered walking result, just use function sorted at the outer side of walk().

Returns:

• iter: Iterator to walk the given tree, contains 2 items, the 1st one is the full path of the node, the 2nd one is the value.

Examples:

>>> from treevalue import FastTreeValue, walk
>>> tv1 = FastTreeValue({'a': 1, 'b': 2, 'c': {'x': 2, 'y': 2}})
>>> for k, v in tv1.walk():
...     print(k, v)
() <FastTreeValue 0x7f672fc533c8>
├── 'a' --> 1
├── 'b' --> 2
└── 'c' --> <FastTreeValue 0x7f672fc53438>
    ├── 'x' --> 2
    └── 'y' --> 2
('a',) 1
('b',) 2
('c',) <FastTreeValue 0x7f672fc53438>
├── 'x' --> 2
└── 'y' --> 2
('c', 'x') 2
('c', 'y') 2

general_tree_value

treevalue.tree.general.general_tree_value(base: Optional[Mapping[str, Any]] = None, methods: Optional[Mapping[str, Any]] = None)

Overview:

Get general tree value class.

Arguments:

• base (Optional[Mapping[str, Any]]): Base configuration of func_treelize.

• methods (Optional[Mapping[str, Any]]): Method configurations of func_treelize.

Returns:

• clazz (Type[TreeValue]): General tree value class.