treevalue.tree.func

func_treelize

treevalue.tree.func.func_treelize(mode: str = 'strict', return_type: Optional[Type[TreeClassType_]] = <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)

Overview:

Wrap a common function to tree-supported function.

Arguments:

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

• return_type (Optional[Type[TreeClassType_]]): 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}})

method_treelize

treevalue.tree.func.method_treelize(mode: str = 'strict', return_type: Optional[Type[TreeClassType_]] = <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, self_copy: bool = False)

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 (str): Mode of the wrapping, default is strict.

• return_type (Optional[Type[TreeClassType_]]): 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.)

• self_copy (bool): Self copy mode, if enabled, the result data will be copied to self argument and self will be returned as result. Default is False, which means do not do self copy.

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

classmethod_treelize

treevalue.tree.func.classmethod_treelize(mode: str = 'strict', return_type: Optional[Type[TreeClassType_]] = <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)

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 (str): Mode of the wrapping, default is strict.

• return_type (Optional[Type[TreeClassType_]]): 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)})

MISSING_NOT_ALLOW

treevalue.tree.func.MISSING_NOT_ALLOW

Overview:

Singleton mark for some situation. Can be used when some default value is needed, especially when None has meaning which is not default.

Example:

>>> NO_VALUE = SingletonMark("no_value")
>>> NO_VALUE is SingletonMark("no_value")  # True

Note

SingletonMark is a value-based singleton class, can be used to create an unique value, especially in the cases which None is not suitable for the default value.

AUTO_DETECT_RETURN_TYPE

treevalue.tree.func.AUTO_DETECT_RETURN_TYPE

Overview:

Singleton mark for some situation. Can be used when some default value is needed, especially when None has meaning which is not default.

Example:

>>> NO_VALUE = SingletonMark("no_value")
>>> NO_VALUE is SingletonMark("no_value")  # True

Note

SingletonMark is a value-based singleton class, can be used to create an unique value, especially in the cases which None is not suitable for the default value.