Merge pull request #26 from opendilab/dev/potc

dev(hansbug): add support for treevalue[potc]

README.md

@@ -32,7 +32,7 @@ You can simply install it with `pip` command line from the official PyPI site.
 pip install treevalue
 ```
 
-For more information about installation, you can refer to [Installation](https://opendilab.github.io/treevalue/main/tutorials/installation/index.html#).
+For more information about installation, you can refer to the [installation guide](https://opendilab.github.io/treevalue/main/tutorials/installation/index.html).
 
 ## Documentation
 
@@ -197,6 +197,29 @@ Test benchmark code can be found here:
 * [Comparison with jax-libtree](https://github.com/opendilab/treevalue/blob/main/test/compare/jax/test_jax.py)
 * [Comparison with tianshou Batch](https://github.com/opendilab/treevalue/blob/main/test/compare/tianshou/test_tianshou_batch.py)
 
+## Extension
+
+If you need to translate `treevalue` object to runnable source code, you may use the [potc-treevalue](https://github.com/potc-dev/potc-treevalue) plugin with the installation command below
+
+```shell
+pip install potc-treevalue
+```
+
+Or just install it with `treevalue` itself
+
+```shell
+pip install treevalue[potc]
+```
+
+In potc, you can translate the objects to runnable python source code, which can be loaded to objects afterwards by the python interpreter, like the following graph
+
+![potc system](docs/source/_static/potc-doing.svg)
+
+For more information, you can refer to
+
+* [potc-dev/potc](https://github.com/potc-dev/potc)
+* [potc-dev/potc-treevalue](https://github.com/potc-dev/potc-treevalue)
+* [Potc Plugin Installation](https://opendilab.github.io/treevalue/main/tutorials/plugins/index.html#potc-support)
 
 ## Contribution
 

docs/source/_static/potc-doing.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="310"
+   height="310"
+   viewBox="0 0 194.3793 194.3793"
+   version="1.1"
+   id="svg5"
+   sodipodi:docname="potc-doing.svg"
+   inkscape:version="1.1.1 (3bf5ae0d25, 2021-09-20)"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <sodipodi:namedview
+     id="namedview7"
+     pagecolor="#ffffff"
+     bordercolor="#323232"
+     borderopacity="1"
+     inkscape:pageshadow="0"
+     inkscape:pageopacity="0"
+     inkscape:pagecheckerboard="true"
+     inkscape:document-units="px"
+     showgrid="false"
+     borderlayer="true"
+     inkscape:showpageshadow="true"
+     showborder="true"
+     inkscape:zoom="1"
+     inkscape:cx="161"
+     inkscape:cy="328.5"
+     inkscape:window-width="1920"
+     inkscape:window-height="1001"
+     inkscape:window-x="-9"
+     inkscape:window-y="-9"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="layer1"
+     width="197mm"
+     scale-x="0.52703"
+     units="px"
+     viewbox-height="195" />
+  <defs
+     id="defs2">
+    <marker
+       style="overflow:visible"
+       id="marker1316"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="Arrow2Lend"
+       inkscape:isstock="true">
+      <path
+         transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         style="fill:context-stroke;fill-rule:evenodd;stroke:context-stroke;stroke-width:0.625;stroke-linejoin:round"
+         id="path1076" />
+    </marker>
+    <marker
+       style="overflow:visible"
+       id="marker15262"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="Arrow2Lend"
+       inkscape:isstock="true">
+      <path
+         transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         style="fill:context-stroke;fill-rule:evenodd;stroke:context-stroke;stroke-width:0.625;stroke-linejoin:round"
+         id="path15260" />
+    </marker>
+    <marker
+       style="overflow:visible"
+       id="marker15252"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="Arrow1Lend"
+       inkscape:isstock="true">
+      <path
+         transform="matrix(-0.8,0,0,-0.8,-10,0)"
+         style="fill:context-stroke;fill-rule:evenodd;stroke:context-stroke;stroke-width:1pt"
+         d="M 0,0 5,-5 -12.5,0 5,5 Z"
+         id="path15250" />
+    </marker>
+    <marker
+       style="overflow:visible"
+       id="Arrow1Lend"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="Arrow1Lend"
+       inkscape:isstock="true">
+      <path
+         transform="matrix(-0.8,0,0,-0.8,-10,0)"
+         style="fill:context-stroke;fill-rule:evenodd;stroke:context-stroke;stroke-width:1pt"
+         d="M 0,0 5,-5 -12.5,0 5,5 Z"
+         id="path14354" />
+    </marker>
+    <marker
+       style="overflow:visible"
+       id="Arrow2Lend"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="Arrow2Lend"
+       inkscape:isstock="true">
+      <path
+         transform="matrix(-1.1,0,0,-1.1,-1.1,0)"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         style="fill:context-stroke;fill-rule:evenodd;stroke:context-stroke;stroke-width:0.625;stroke-linejoin:round"
+         id="path14372" />
+    </marker>
+    <marker
+       style="overflow:visible"
+       id="Arrow1Lstart"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="Arrow1Lstart"
+       inkscape:isstock="true">
+      <path
+         transform="matrix(0.8,0,0,0.8,10,0)"
+         style="fill:context-stroke;fill-rule:evenodd;stroke:context-stroke;stroke-width:1pt"
+         d="M 0,0 5,-5 -12.5,0 5,5 Z"
+         id="path14351" />
+    </marker>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       inkscape:label="Drop Shadow"
+       id="filter14120"
+       x="-0.11204367"
+       y="-0.27115467"
+       width="1.2520983"
+       height="1.610098">
+      <feFlood
+         flood-opacity="0.498039"
+         flood-color="rgb(0,0,0)"
+         result="flood"
+         id="feFlood14110" />
+      <feComposite
+         in="flood"
+         in2="SourceGraphic"
+         operator="in"
+         result="composite1"
+         id="feComposite14112" />
+      <feGaussianBlur
+         in="composite1"
+         stdDeviation="5"
+         result="blur"
+         id="feGaussianBlur14114" />
+      <feOffset
+         dx="3"
+         dy="3"
+         result="offset"
+         id="feOffset14116" />
+      <feComposite
+         in="SourceGraphic"
+         in2="offset"
+         operator="over"
+         result="composite2"
+         id="feComposite14118" />
+    </filter>
+    <filter
+       style="color-interpolation-filters:sRGB"
+       inkscape:label="Drop Shadow"
+       id="filter14150"
+       x="-0.11504064"
+       y="-0.30774402"
+       width="1.2588414"
+       height="1.692424">
+      <feFlood
+         flood-opacity="0.498039"
+         flood-color="rgb(0,0,0)"
+         result="flood"
+         id="feFlood14140" />
+      <feComposite
+         in="flood"
+         in2="SourceGraphic"
+         operator="in"
+         result="composite1"
+         id="feComposite14142" />
+      <feGaussianBlur
+         in="composite1"
+         stdDeviation="5"
+         result="blur"
+         id="feGaussianBlur14144" />
+      <feOffset
+         dx="3"
+         dy="3"
+         result="offset"
+         id="feOffset14146" />
+      <feComposite
+         in="SourceGraphic"
+         in2="offset"
+         operator="over"
+         result="composite2"
+         id="feComposite14148" />
+    </filter>
+  </defs>
+  <g
+     inkscape:label="图层 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <g
+       id="g5166"
+       transform="translate(12.122605,-0.05363983)">
+      <g
+         id="g13626"
+         style="filter:url(#filter14120)"
+         transform="translate(16.458305,4.5870873)">
+        <rect
+           style="fill:#f6b5fc;fill-opacity:0.839542;fill-rule:evenodd;stroke-width:0.291935;stroke-miterlimit:4;stroke-dasharray:none"
+           id="rect31"
+           width="107.1011"
+           height="44.255184"
+           x="13.725255"
+           y="14.507528" />
+        <text
+           xml:space="preserve"
+           style="font-style:normal;font-weight:normal;font-size:10.5833px;line-height:1.25;font-family:sans-serif;fill:#00002f;fill-opacity:0.843137;stroke:none;stroke-width:0.264583"
+           x="47.409298"
+           y="31.980234"
+           id="text1630"><tspan
+             sodipodi:role="line"
+             id="tspan1628"
+             style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:10.5833px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#00002f;fill-opacity:0.843137;stroke-width:0.264583"
+             x="47.409298"
+             y="31.980234">Object</tspan></text>
+        <text
+           xml:space="preserve"
+           style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.76111px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000068;fill-opacity:0.843137;stroke:none;stroke-width:0.264583"
+           x="22.442272"
+           y="46.848244"
+           id="text5854"><tspan
+             sodipodi:role="line"
+             id="tspan5852"
+             style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.76111px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000068;fill-opacity:0.843137;stroke-width:0.264583"
+             x="22.442272"
+             y="46.848244">Existing python objects</tspan></text>
+      </g>
+      <g
+         id="g13560"
+         transform="translate(-135.30756,12.161354)"
+         style="filter:url(#filter14150)">
+        <rect
+           style="fill:#b5fcdf;fill-opacity:0.839542;stroke-width:0.182715;stroke-miterlimit:4;stroke-dasharray:none"
+           id="rect8153"
+           width="104.31097"
+           height="38.993446"
+           x="168.31702"
+           y="121.74933" />
+        <text
+           xml:space="preserve"
+           style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:10.5833px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#3a052b;fill-opacity:0.836676;stroke:none;stroke-width:0.264583"
+           x="206.46889"
+           y="136.89786"
+           id="text10085"><tspan
+             sodipodi:role="line"
+             id="tspan10083"
+             style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:10.5833px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#3a052b;fill-opacity:0.836676;stroke-width:0.264583"
+             x="206.46889"
+             y="136.89786">Code</tspan></text>
+        <text
+           xml:space="preserve"
+           style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.76111px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#5b0843;fill-opacity:0.835294;stroke:none;stroke-width:0.264583"
+           x="176.17181"
+           y="150.36322"
+           id="text13323"><tspan
+             sodipodi:role="line"
+             id="tspan13321"
+             style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.76111px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#5b0843;fill-opacity:0.835294;stroke-width:0.264583"
+             x="176.17181"
+             y="150.36322">Runnable python code</tspan></text>
+      </g>
+      <g
+         id="g5140"
+         transform="translate(-59.003831,-2.1455939)">
+        <path
+           style="fill:none;stroke:#30031a;stroke-width:0.565;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:3.2;stroke-dasharray:none;stroke-opacity:0.802292;marker-end:url(#marker15262);paint-order:normal"
+           d="m 163.82858,65.924171 c 18.23435,35.627099 -1.9637,69.571039 -1.9637,69.571039"
+           id="path15083" />
+        <text
+           xml:space="preserve"
+           style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:8.46667px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#30031a;fill-opacity:0.803922;stroke:none;stroke-width:0.264583"
+           x="184.21156"
+           y="93.483849"
+           id="text16760"><tspan
+             sodipodi:role="line"
+             id="tspan16758"
+             style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:8.46667px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#30031a;fill-opacity:0.803922;stroke-width:0.264583"
+             x="184.21156"
+             y="93.483849">Translated</tspan><tspan
+             sodipodi:role="line"
+             style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:8.46667px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#30031a;fill-opacity:0.803922;stroke-width:0.264583"
+             x="184.21156"
+             y="104.06718"
+             id="tspan16762">by <tspan
+   style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:8.46667px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#30031a;fill-opacity:0.803922"
+   id="tspan19836">potc</tspan></tspan></text>
+      </g>
+      <g
+         id="g5133"
+         transform="translate(-59.003831,-2.1455939)">
+        <path
+           style="fill:none;stroke:#200348;stroke-width:0.565;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:3.2;stroke-dasharray:none;stroke-opacity:0.848138;marker-end:url(#marker1316)"
+           d="m 126.85823,135.44061 c -19.04214,-33.5249 -0.80459,-69.999998 -0.80459,-69.999998"
+           id="path208" />
+        <text
+           xml:space="preserve"
+           style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:8.46667px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#200348;fill-opacity:0.847059;stroke:none;stroke-width:0.265;stroke-miterlimit:3.2;stroke-dasharray:none"
+           x="62.222221"
+           y="97.08812"
+           id="text2838"><tspan
+             sodipodi:role="line"
+             id="tspan2836"
+             style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:8.46667px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#200348;fill-opacity:0.847059;stroke-width:0.265;stroke-miterlimit:3.2;stroke-dasharray:none"
+             x="62.222221"
+             y="97.08812">Loaded</tspan><tspan
+             sodipodi:role="line"
+             style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:8.46667px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#200348;fill-opacity:0.847059;stroke-width:0.265;stroke-miterlimit:3.2;stroke-dasharray:none"
+             x="62.222221"
+             y="107.67146"
+             id="tspan2840">by <tspan
+   style="font-weight:bold"
+   id="tspan3808">python</tspan></tspan></text>
+      </g>
+    </g>
+  </g>
+</svg>

docs/source/index.rst

@@ -19,6 +19,7 @@ structure processing when the calculation is tree-based.
     tutorials/basic_usage/index
     tutorials/advanced_usage/index
     tutorials/cli_usage/index
+    tutorials/plugins/index
 
 
 .. toctree::

docs/source/tutorials/plugins/index.rst

+Plugins
+===============
+
+Potc support
+---------------------
+
+`Potc <https://github.com/potc-dev/potc>`_  is a package that can convert any object into executable source code.
+For ``treevalue``, potc can support the source code transformation of treevalue objects through
+the installation of additional plugins. So we can execute the following installation command
+
+.. code:: shell
+
+    pip install treevalue[potc]
+
+After this installation, you will be able to directly convert treevalue to an object without any additional operations.
+Such as
+
+.. literalinclude:: ./potc_demo.demo.py
+    :language: python
+    :linenos:
+
+The output should be
+
+.. literalinclude:: ./potc_demo.demo.py.txt
+    :language: text
+    :linenos:
+
+Also, you can use the following CLI command to get the same output results as above.
+
+.. code:: shell
+
+    potc export -v 'test_simple.t' -v 'test_simple.st' -v 'test_simple.r'
+
+For further information, you can refer to
+
+* `potc-dev/potc <https://github.com/potc-dev/potc>`_
+* `potc-dev/potc-treevalue <https://github.com/potc-dev/potc-treevalue>`_

docs/source/tutorials/plugins/potc_demo.demo.py

+from potc import transvars
+
+from treevalue import FastTreeValue, raw
+
+r = raw({'a': 1, 'b': 2, 'c': [3, 4]})
+t = FastTreeValue({
+    'a': 1, 'b': 'this is a string',
+    'c': [], 'd': {
+        'x': raw({'a': 1, 'b': (None, Ellipsis)}),
+        'y': {3, 4, 5}
+    }
+})
+st = t._detach()
+if __name__ == '__main__':
+    _code = transvars(
+        {'t': t, 'st': t._detach(), 'r': r},
+        reformat='pep8'
+    )
+    print(_code)

requirements-doc.txt

@@ -8,4 +8,5 @@ sphinx-multiversion~=0.2.4
 where~=1.0.2
 numpy>=1.19,<2
 easydict>=1.7,<2
-scikit-learn>=0.24.2
\ No newline at end of file
+scikit-learn>=0.24.2
+potc-treevalue>=0.0.1
\ No newline at end of file

requirements-potc.txt

+potc-treevalue>=0.0.1
\ No newline at end of file

test/entry/cli/test_export.py

@@ -142,11 +142,11 @@ class TestEntryCliExport:
 
             assert result.exit_code == 0
             assert os.path.exists('t1.btv')
-            assert 260 < os.path.getsize('t1.btv') < 310
+            assert 260 < os.path.getsize('t1.btv') < 330
             assert os.path.exists('t2.btv')
-            assert 280 < os.path.getsize('t2.btv') < 400
+            assert 280 < os.path.getsize('t2.btv') < 430
             assert os.path.exists('t3.btv')
-            assert 280 < os.path.getsize('t3.btv') < 350
+            assert 280 < os.path.getsize('t3.btv') < 375
 
             with open('t1.btv', 'rb') as file:
                 assert load(file, type_=FastTreeValue) == t1