treevalue.tree.func

func_treelize

treevalue.tree.func.func_treelize(mode: Union[str, treevalue.tree.func.func.TreeMode] = 'strict', return_type: Optional[Type[_ClassType]] = <class 'treevalue.tree.tree.tree.TreeValue'>, inherit: bool = True, missing: Union[Any, Callable] = <SingletonMark 'missing_not_allow'>, subside: Optional[Union[Mapping, bool]] = None, rise: Optional[Union[Mapping, bool]] = None)[source]
Overview:

Wrap a common function to tree-supported function.

Arguments:

  • mode (Union[str, TreeMode]): Mode of the wrapping (string or TreeMode both okay), 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 (Union[Any, Callable]): Missing value or lambda generator of when missing, default is MISSING_NOT_ALLOW, which means raise KeyError when missing detected.

  • 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:
>>> @func_treelize()
>>> 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)  # TreeValue({'a': 12, 'b': 24, 'x': {'c': 36, 'd': 9}})

tree_class

treevalue.tree.func.tree_class(return_type: Optional[Type[_ClassType]] = None)[source]
Overview:

Wrap tree configs for TreeValue class.

Arguments:

  • return_type (Optional[Type[_ClassType]]): Default return type of current class, default is None which means use the class itself.

Returns:

  • decorator (Callable): A class decorator.

method_treelize

treevalue.tree.func.method_treelize(mode: Union[str, treevalue.tree.func.func.TreeMode] = 'strict', return_type: Optional[Type[_ClassType]] = <SingletonMark 'auto_detect_return_type'>, inherit: bool = True, missing: Union[Any, Callable] = <SingletonMark 'missing_not_allow'>, subside: Optional[Union[Mapping, bool]] = None, rise: Optional[Union[Mapping, bool]] = None)[source]
Overview:

Wrap a common instance method to tree-supported method.

Attention:

  • This decorator can only used to instance method, usage with class method may cause unconditional fatal.

  • When decorated instance method is called, the self argument will be no longer the class instance, but the single element of the tree instead.

Arguments:

  • mode (Union[str, TreeMode]): Mode of the wrapping (string or TreeMode both okay), default is strict.

  • return_type (Optional[Type[_ClassType]]): Return type of the wrapped function, default is AUTO_DETECT_RETURN_VALUE, which means automatically use the decorated method’s class.

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

  • 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 method.

Example:
>>> class MyTreeValue(TreeValue):
>>>     @method_treelize()
>>>     def append(self, *args):
>>>         return sum([self, *args])  # the self will be the integers, not MyTreeValue
>>>
>>> t1 = MyTreeValue({'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}})
>>> t2 = MyTreeValue({'a': 11, 'b': 22, 'x': {'c': 33, 'd': 5}})
>>> t1.append(2)   # MyTreeValue({'a': 3, 'b': 4, 'x': {'c': 5, 'd': 6}})
>>> t1.append(t2)  # MyTreeValue({'a': 12, 'b': 24, 'x': {'c': 36, 'd': 9}})

utils_class

treevalue.tree.func.utils_class(return_type: Type[_ClassType])[source]
Overview:

Wrap tree configs for utils class.

Arguments:

  • return_type (Optional[Type[_ClassType]]): Default return type of current class.

Returns:

  • decorator (Callable): A class decorator.

Examples:
>>> class MyTreeValue(TreeValue):
>>>     pass
>>>
>>> @utils_class(return_type=MyTreeValue)
>>> class MyTreeUtils:
>>>     @classmethod
>>>     @classmethod_treelize()
>>>     def add(cls, a, b):
>>>         return a + b
>>>
>>> t1 = TreeValue({'a': 1, 'b': 2})
>>> t2 = TreeValue({'a': 3, 'b': 4})
>>> MyTreeUtils.add(t1, t2)  # MyTreeValue({'a': 4, 'b': 6})

classmethod_treelize

treevalue.tree.func.classmethod_treelize(mode: Union[str, treevalue.tree.func.func.TreeMode] = 'strict', return_type: Optional[Type[_ClassType]] = <SingletonMark 'auto_detect_return_type'>, inherit: bool = True, missing: Union[Any, Callable] = <SingletonMark 'missing_not_allow'>, subside: Optional[Union[Mapping, bool]] = None, rise: Optional[Union[Mapping, bool]] = None)[source]
Overview:

Wrap a common class method to tree-supported method.

Attention:

  • This decorator can only used to class method, usage with instance method may cause unconditional fatal.

  • When decorated instance method is called, the cls argument will still be the calling class.

Arguments:

  • mode (Union[str, TreeMode]): Mode of the wrapping (string or TreeMode both okay), default is strict.

  • return_type (Optional[Type[_ClassType]]): Return type of the wrapped function, default is AUTO_DETECT_RETURN_VALUE, which means automatically use the decorated method’s class.

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

  • 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 class method.

Example:
>>> class TestUtils:
>>>     @classmethod
>>>     @classmethod_treelize(return_type=TreeValue)
>>>     def add(cls, a, b):
>>>         return cls, a + b
>>>
>>> TestUtils.add(
>>>     TreeValue({'a': 1, 'b': 2}),
>>>     TreeValue({'a': 11, 'b': 23}),
>>> )  # TreeValue({'a': (TestUtils, 12), 'b': (TestUtils, 25)})

TreeMode

enum treevalue.tree.func.TreeMode(value)[source]
Overview:

Four mode of the tree calculation

Member Type:

int

Valid values are as follows:

STRICT = <TreeMode.STRICT: 1>

Strict mode, which means the keys should be one to one in every trees.

LEFT = <TreeMode.LEFT: 2>

Left mode, the keys of the result is relied on the left value.

INNER = <TreeMode.INNER: 3>

Inner mode, the keys of the result is relied on the intersection of the trees’ key set.

OUTER = <TreeMode.OUTER: 4>

Outer mode, the keys of the result is relied on the union of the trees’ key set.

The Enum and its members also have the following methods:

classmethod loads(data) → Optional[treevalue.tree.func.func.TreeMode]
Overview:

Load enum data from raw data.

Arguments:

  • data (Any): Data which going to be parsed.

Returns:

  • enum_data (:obj:): Parsed enum data

MISSING_NOT_ALLOW

treevalue.tree.func.MISSING_NOT_ALLOW

Default value of the missing arguments of func_treelize, method_treelize and classmethod_treelize, which means missing is not allowed (raise KeyError when missing is detected).

AUTO_DETECT_RETURN_TYPE

treevalue.tree.func.AUTO_DETECT_RETURN_TYPE

Default value of the return_type arguments of method_treelize and classmethod_treelize, which means return type will be auto configured to the current class.