Merge pull request #5 from opendilab/dev/graphviz

Development for the issue #2 and issue #4

.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       matrix:
         os:
-          - 'ubuntu-latest'
+          - 'ubuntu-18.04'
         python-version:
           - '3.6'
           - '3.7'
@@ -27,8 +27,9 @@ jobs:
         if: ${{ runner.os == 'Linux' }}
         run: |
           sudo apt-get update
-          sudo apt-get install -y tree cloc wget curl make
+          sudo apt-get install -y tree cloc wget curl make graphviz
           sudo apt-get install -y libxml2-dev libxslt-dev python-dev  # need by pypy3
+          dot -V
       - name: Set up python ${{ matrix.python-version }}
         uses: actions/setup-python@v2
         with:

.gitignore

@@ -1193,6 +1193,7 @@ fabric.properties
 .idea/caches/build_file_checksums.ser
 
 /test_*
+/*.btv
 .python-version
 /docs/build
 /public

README.md

@@ -63,6 +63,10 @@ The result should be
     └── 'd' --> 4
 ```
 
+And `t` is structure should be like this
+
+![t_graph](https://opendilab.github.io/treevalue/main/_images/simple_demo.dat.svg)
+
 For more quick start explanation and further usage, take a look at:
 
 * [Quick Start](https://opendilab.github.io/treevalue/main/tutorials/quick_start/index.html)

docs/Makefile

@@ -14,9 +14,15 @@ GRAPHVIZ    := $(MAKE) -f "${GRAPHVIZ_MK}" SOURCE=${SOURCEDIR}
 DEMOS_MK    := ${SOURCEDIR}/demos.mk
 DEMOS       := $(MAKE) -f "${DEMOS_MK}" SOURCE=${SOURCEDIR}
 
+_CURRENT_PATH       := ${PATH}
+_PROJ_DIR           := $(shell readlink -f ${CURDIR}/..)
+_LIBS_DIR           := $(shell readlink -f ${SOURCEDIR}/_libs)
+_SHIMS_DIR          := $(shell readlink -f ${SOURCEDIR}/_shims)
+
 .EXPORT_ALL_VARIABLES:
 
-PYTHONPATH = $(shell readlink -f ${CURDIR}/..)
+PYTHONPATH = ${_PROJ_DIR}:${_LIBS_DIR}
+PATH       = ${_SHIMS_DIR}:${_CURRENT_PATH}
 NO_CONTENTS_BUILD = true
 
 # Catch-all target: route all unknown targets to Sphinx using the new

docs/source/_libs/dm.py

@@ -0,0 +1,14 @@
+import importlib.util
+import os
+from types import ModuleType
+
+
+def get_module(filename) -> ModuleType:
+    _, _simple_filename = os.path.split(filename)
+    _module_name, _ = _simple_filename.split('.', maxsplit=1)
+
+    spec = importlib.util.spec_from_file_location(_module_name, filename)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    return module

docs/source/_shims/treevalue

@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+
+from treevalue.entry.cli import treevalue_cli
+
+if __name__ == '__main__':
+    treevalue_cli()

docs/source/api_doc/config/meta.rst

@@ -3,4 +3,36 @@ treevalue.config.meta
 
 .. automodule:: treevalue.config.meta
 
+\_\_TITLE\_\_
+------------------
 
+.. autodata:: treevalue.config.meta.__TITLE__
+    :annotation:
+
+
+\_\_VERSION\_\_
+------------------
+
+.. autodata:: treevalue.config.meta.__VERSION__
+    :annotation:
+
+
+\_\_DESCRIPTION\_\_
+----------------------
+
+.. autodata:: treevalue.config.meta.__DESCRIPTION__
+    :annotation:
+
+
+\_\_AUTHOR\_\_
+------------------
+
+.. autodata:: treevalue.config.meta.__AUTHOR__
+    :annotation:
+
+
+\_\_AUTHOR_EMAIL\_\_
+----------------------
+
+.. autodata:: treevalue.config.meta.__AUTHOR_EMAIL__
+    :annotation:

docs/source/api_doc/tree/common.rst

@@ -7,7 +7,7 @@ BaseTree
 -----------
 
 .. autoclass:: treevalue.tree.common.base.BaseTree
-    :members: __getitem__, __setitem__, __delitem__, json, view, clone, items, keys, values, actual, __len__, __hash__, __eq__, __repr__, __bool__, __str__
+    :members: __getitem__, __setitem__, __delitem__, json, view, clone, items, keys, values, actual, __len__, __hash__, __eq__, __repr__, __bool__, __str__, copy_from
 
 
 .. _apidoc_tree_common_tree:
@@ -16,7 +16,7 @@ Tree
 ---------
 
 .. autoclass:: treevalue.tree.common.tree.Tree
-    :members: __init__, __getitem__, __setitem__, __delitem__, json, view, clone, items, keys, values, actual, __len__, __hash__, __eq__, __repr__, __bool__, __str__
+    :members: __init__, __getitem__, __setitem__, __delitem__, json, view, clone, items, keys, values, actual, __len__, __hash__, __eq__, __repr__, __bool__, __str__, copy_from
 
 
 .. _apidoc_tree_common_raw:
@@ -33,5 +33,5 @@ TreeView
 -------------
 
 .. autoclass:: treevalue.tree.common.view.TreeView
-    :members: __init__, __getitem__, __setitem__, __delitem__, json, view, clone, items, keys, values, actual, __len__, __hash__, __eq__, __repr__, __bool__, __str__
+    :members: __init__, __getitem__, __setitem__, __delitem__, json, view, clone, items, keys, values, actual, __len__, __hash__, __eq__, __repr__, __bool__, __str__, copy_from
 

docs/source/api_doc/tree/func.rst

@@ -50,20 +50,12 @@ TreeMode
 MISSING_NOT_ALLOW
 -------------------------
 
-.. data:: treevalue.tree.func.MISSING_NOT_ALLOW
+.. autodata:: treevalue.tree.func.func.MISSING_NOT_ALLOW
+    :annotation:
 
-    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
 ----------------------------
 
-.. data:: 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.
+.. autodata:: treevalue.tree.func.func.AUTO_DETECT_RETURN_TYPE
+    :annotation:

docs/source/api_doc/tree/general.rst

@@ -7,7 +7,7 @@ FastTreeValue
 -------------------
 
 .. autoclass:: treevalue.tree.general.FastTreeValue
-    :members: _attr_extern, json, view, clone, __add__, __radd__, __sub__, __rsub__, __mul__, __rmul__, __matmul__, __rmatmul__, __truediv__, __rtruediv__, __floordiv__, __rfloordiv__, __mod__, __rmod__, __pow__, __rpow__, __and__, __rand__, __or__, __ror__, __xor__, __rxor__, __lshift__, __rlshift__, __rshift__, __rrshift__, __pos__, __neg__, __invert__, __getitem__, __setitem__, __delitem__, __call__, __getattr__, __setattr__, __delattr__, __repr__, __iter__, __hash__, __eq__, map, type, mask, filter, __str__, reduce, rise, union, subside
+    :members: _attr_extern, json, view, clone, __add__, __radd__, __sub__, __rsub__, __mul__, __rmul__, __matmul__, __rmatmul__, __truediv__, __rtruediv__, __floordiv__, __rfloordiv__, __mod__, __rmod__, __pow__, __rpow__, __and__, __rand__, __or__, __ror__, __xor__, __rxor__, __lshift__, __rlshift__, __rshift__, __rrshift__, __pos__, __neg__, __invert__, __getitem__, __setitem__, __delitem__, __call__, __getattr__, __setattr__, __delattr__, __repr__, __iter__, __hash__, __eq__, map, type, mask, filter, __str__, reduce, rise, union, subside, __getstate__, __setstate__, __iadd__, __isub__, __imul__, __imatmul__, __ifloordiv__, __itruediv__, __ipow__, __imod__, __iand__, __ior__, __ixor__, __ilshift__, __irshift__, graph, graphics, func
 
 
 .. _apidoc_tree_general_generaltreevalue:

docs/source/api_doc/tree/graphics.demo.py

@@ -0,0 +1,27 @@
+import numpy as np
+
+from treevalue import FastTreeValue, graphics, TreeValue
+
+
+class MyFastTreeValue(FastTreeValue):
+    pass
+
+
+if __name__ == '__main__':
+    t = MyFastTreeValue({
+        'a': 1,
+        'b': np.array([[5, 6], [7, 8]]),
+        'x': {
+            'c': 3,
+            'd': 4,
+            'e': np.array([[1, 2], [3, 4]])
+        },
+    })
+    t2 = TreeValue({'ppp': t.x, 'x': {'t': t, 'y': t.x}})
+
+    g = graphics(
+        (t, 't'), (t2, 't2'),
+        title="This is a demo of 2 trees.",
+        cfg={'bgcolor': '#ffffff00'},
+    )
+    g.render('graphics.dat.gv', format='svg')

docs/source/api_doc/tree/graphics_dup_value.demo.py

@@ -0,0 +1,40 @@
+import numpy as np
+
+from treevalue import FastTreeValue, graphics
+
+
+class MyFastTreeValue(FastTreeValue):
+    pass
+
+
+if __name__ == '__main__':
+    t = MyFastTreeValue({
+        'a': [4, 3, 2, 1],
+        'b': np.array([[5, 6], [7, 8]]),
+        'x': {
+            'c': np.array([[5, 7], [8, 6]]),
+            'd': {'a', 'b', 'c'},
+            'e': np.array([[1, 2], [3, 4]])
+        },
+    })
+    t1 = MyFastTreeValue({
+        'aa': t.a,
+        'bb': np.array([[5, 6], [7, 8]]),
+        'xx': {
+            'cc': t.x.c,
+            'dd': t.x.d,
+            'ee': np.array([[1, 2], [3, 4]])
+        },
+    })
+
+    g = graphics(
+        (t, 't'), (t1, 't1'),
+        (MyFastTreeValue({'a': t, 'b': t1, 'c': [1, 2], 'd': t1.xx}), 't2'),
+        # Here is the dup value, with several types
+        # np.ndarray and list type will use the same value node,
+        # but set type is not in this tuple, so will not share the same node.
+        dup_value=(np.ndarray, list),
+        title="This is a demo of 2 trees with dup value.",
+        cfg={'bgcolor': '#ffffff00'},
+    )
+    g.render('graphics_dup_value.dat.gv', format='svg')

docs/source/api_doc/tree/tree.rst

@@ -7,7 +7,7 @@ TreeValue
 ---------------
 
 .. autoclass:: treevalue.tree.tree.tree.TreeValue
-    :members: __init__, __getattr__, __setattr__, __delattr__, __contains__, __repr__, __iter__, __hash__, __eq__, _attr_extern, __len__, __bool__, __str__
+    :members: __init__, __getattr__, __setattr__, __delattr__, __contains__, __repr__, __iter__, __hash__, __eq__, _attr_extern, __len__, __bool__, __str__, __getstate__, __setstate__
 
 
 .. _apidoc_tree_tree_jsonify:
@@ -101,8 +101,87 @@ reduce\_
 NO_RISE_TEMPLATE
 --------------------
 
-.. data:: treevalue.tree.tree.utils.NO_RISE_TEMPLATE
+.. autodata:: treevalue.tree.tree.utils.NO_RISE_TEMPLATE
+    :annotation:
+
+
+.. _apidoc_tree_tree_graphics:
+
+graphics
+----------------
+
+.. autofunction:: treevalue.tree.tree.graph.graphics
+
+Here is an example of ``graphics`` function. The source code is
+
+.. literalinclude:: graphics.demo.py
+    :language: python
+    :linenos:
+
+The generated graphviz source code should be
+
+.. literalinclude:: graphics.dat.gv
+    :language: text
+    :linenos:
+
+The graph should be
+
+.. image:: graphics.dat.gv.svg
+    :align: center
+
+Also, ``graphics`` function can support value duplication. For if \
+the value nodes are using the same object, they will be displayed \
+in the same node of the generated graph, such as the source code
+below
+
+.. literalinclude:: graphics_dup_value.demo.py
+    :language: python
+    :linenos:
+
+The graph of the case with ``dup_value`` should be
+
+.. image:: graphics_dup_value.dat.gv.svg
+    :align: center
+
+The return value's type of function ``graphics`` is \
+class ``graphviz.dot.Digraph``, from the opensource \
+library ``graphviz``, for further information of \
+this project and ``graphviz.dot.Digraph``'s usage, \
+take a look at:
+
+* `Official site of Graphviz <https://graphviz.org/>`_.
+* `User Guide of Graphviz <https://graphviz.readthedocs.io/en/stable/manual.html#formats>`_.
+* `API Reference of Graphviz <https://graphviz.readthedocs.io/en/stable/api.html>`_.
+
+
+.. _apidoc_tree_tree_dump:
+
+dump
+-------------
+
+.. autofunction:: treevalue.tree.tree.io.dump
+
+
+.. _apidoc_tree_tree_dumps:
+
+dumps
+-------------
+
+.. autofunction:: treevalue.tree.tree.io.dumps
+
+
+.. _apidoc_tree_tree_load:
+
+load
+-------------
+
+.. autofunction:: treevalue.tree.tree.io.load
+
+
+.. _apidoc_tree_tree_loads:
+
+loads
+-------------
+
+.. autofunction:: treevalue.tree.tree.io.loads
 
-    Means no template is given to the rise function, \
-    and the decorated function will automatically try \
-    to match the format patterns as template.

docs/source/api_doc/utils/build_graph.demo.py

@@ -0,0 +1,8 @@
+from treevalue.utils import build_graph
+
+if __name__ == '__main__':
+    t = {'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}}
+    g = build_graph((t, 't'), graph_title="Demo of build_graph.")
+
+    print(g.source)
+    print(g.render('build_graph_demo.dat.gv', format='svg'))

docs/source/api_doc/utils/build_graph_complex.demo.py

@@ -0,0 +1,9 @@
+from treevalue.utils import build_graph
+
+if __name__ == '__main__':
+    t1 = {'a': 1, 'b': 2, 'x': {'c': 3, 'd': 4}}
+    t2 = {'f': 4, 'y': t1['x'], 'z': {'e': [5, 7], 'f': "string"}}
+    g = build_graph((t1, 't1'), (t2, 't2'), graph_title="Complex demo of build_graph.")
+
+    print(g.source)
+    print(g.render('build_graph_complex_demo.dat.gv', format='svg'))

docs/source/api_doc/utils/clazz.rst

@@ -24,3 +24,9 @@ common_direct_base
 
 .. autofunction:: treevalue.utils.clazz.common_direct_base
 
+
+get_class_full_name
+----------------------
+
+.. autofunction:: treevalue.utils.clazz.get_class_full_name
+

docs/source/api_doc/utils/color.rst

@@ -0,0 +1,10 @@
+treevalue.utils.color
+===========================
+
+Color
+----------------
+
+.. autoclass:: treevalue.utils.color.Color
+    :members: __init__, alpha, rgb, hsv, hls, __repr__, __str__, __getstate__, __setstate__, __hash__, __eq__, from_hsv, from_hls
+
+

docs/source/api_doc/utils/exception.rst

@@ -0,0 +1,8 @@
+treevalue.utils.exception
+================================
+
+str_traceback
+-----------------
+
+.. autofunction:: treevalue.utils.exception.str_traceback
+