caw export

Author: Jennings Zhang

README.md

@@ -194,6 +194,24 @@ wow
         └── e.txt
 ```
 
+#### `caw export`
+
+Export a registered pipeline to JSON.
+
+```shell
+caw export 'Automatic Fetal Brain Reconstruction Pipeline v1.0.0' > pipeline.json
+
+curl -u "chris:chris1234" "https://example.com/api/v1/pipelines/" \
+  -H 'Content-Type:application/vnd.collection+json' \
+  -H 'Accept:application/vnd.collection+json' \
+  --data "$(< pipeline.json)"
+```
+
+##### `caw export` Limitations
+
+- All plugin parameters will be exported as part of `plugin_parameter_defaults`
+- Order of lists, such as `plugin_tree` and `plugin_parameter_defaults`, may not be the same as the original
+
 ## Development
 
 ```shell
@@ -237,8 +255,6 @@ docker run --rm --net=host --userns=host -v $PWD:/usr/local/src/caw:ro \
 
 ## Roadmap
 
-Bugs will be fixed, but new features will not be added.
-
 For the next-generation _ChRIS_ client, see
 [chrs](https://github.com/FNNDSC/chrs),
 and how it compares to `caw`:

caw/commands/__init__.py

@@ -8,3 +8,4 @@
 import caw.commands.download
 import caw.commands.pipeline
 import caw.commands.search
+import caw.commands.export

caw/commands/export.py

@@ -0,0 +1,13 @@
+import typer
+
+from caw.commands.store import app, build_client
+
+
+@app.command()
+def export(name: str = typer.Argument(..., help='Name of pipeline.')):
+    """
+    Deserialize a pipeline to JSON.
+    """
+    client = build_client()
+    pipeline = client.get_pipeline(name)
+    typer.echo(pipeline.deserialize())

chris/cube/pipeline.py

@@ -1,3 +1,4 @@
+import json
 import abc
 from dataclasses import dataclass
 from chris.cube.plugin_tree import PluginTree
@@ -9,7 +10,45 @@ class Pipeline(abc.ABC):
     authors: str
     description: str
     category: str
+    locked: bool
 
     @abc.abstractmethod
     def get_root(self) -> PluginTree:
         ...
+
+    def deserialize(self) -> str:
+        """
+        Produce a JSON representation which can be uploaded to a CUBE instance.
+        """
+        data = [
+            {
+                'name': 'name',
+                'value': self.name
+            },
+            {
+                'name': 'authors',
+                'value': self.authors,
+            },
+            {
+                'name': 'category',
+                'value': self.category,
+            },
+            {
+                'name': 'description',
+                'value': self.description,
+            },
+            {
+                'name': 'locked',
+                'value': self.locked,
+            },
+            {
+                'name': 'plugin_tree',
+                'value': self.get_root().deserialize()
+            }
+        ]
+        template = {
+            'template': {
+                'data': data
+            }
+        }
+        return json.dumps(template)

chris/cube/plugin_tree.py

@@ -1,7 +1,9 @@
+import json
+from functools import cached_property
 from dataclasses import dataclass, field
-from typing import Generator, Collection, Dict, Tuple
+from typing import Generator, Collection, Dict, Tuple, Optional
 from collections import deque
-from chris.types import ParameterType, PluginInstanceId
+from chris.types import ParameterType, PluginInstanceId, PipingId
 from chris.cube.plugin import Plugin
 from chris.cube.plugin_instance import PluginInstance
 from chris.cube.resource import ConnectedResource
@@ -79,10 +81,56 @@ def __iter__(self):
         return self.dfs()
 
     def __len__(self):
+        return self.length
+
+    @cached_property
+    def length(self) -> int:
         count = 0
         for _ in self:
             count += 1
         return count
 
     def __contains__(self, __x: object) -> bool:
         return any(__x == e for e in self)
+
+    def deserialize(self) -> str:
+        """
+        Produce this Plugin Tree as JSON according to the ``plugin_tree`` schema
+        of the *ChRIS* pipeline spec.
+        """
+        return json.dumps(self.deserialize_tree())
+
+    def deserialize_tree(self) -> list:
+        data = []
+        index_map: dict[Optional[PipingId], Optional[int]] = {
+            None: None
+        }
+
+        for node in self.bfs():
+            index_map[node.piping.id] = len(data)
+            previous_index = index_map[node.piping.previous_id]
+            data.append(node.deserialize_node(previous_index))
+
+        return data
+
+    def deserialize_node(self, previous_index: Optional[int]) -> dict:
+        """
+        Deserialize just this ``PluginTree`` (and not its children).
+        """
+        plugin = self.get_plugin()
+        data = {
+            'plugin_name': plugin.name,
+            'plugin_version': plugin.version,
+            'previous_index': previous_index
+        }
+
+        if self.default_parameters:
+            data['plugin_parameter_defaults'] = [
+                {
+                    'name': name,
+                    'default': value
+                }
+                for name, value in self.default_parameters.items()
+            ]
+
+        return data

chris/cube/registered_pipeline.py

@@ -60,7 +60,6 @@ def freeze(self) -> PluginTree:
 @dataclass(frozen=True)
 class RegisteredPipeline(CUBEResource, Pipeline):
     id: PipelineId
-    locked: bool
     owner_username: CUBEUsername
     creation_date: ISOFormatDateString
     modification_date: ISOFormatDateString

chris/tests/test_deserialize.py

@@ -0,0 +1,76 @@
+import json
+from chris.client import ChrisClient
+
+expected = r"""
+{"template":
+  {"data":[{"name":"name","value":"Example branching pipeline"},
+  {"name": "authors", "value": "Jennings Zhang <[email protected]>"},
+  {"name": "category", "value": "Example"},
+  {"name": "description", "value":
+  "A more complicated but nonetheless useless pipeline."},
+  {"name":"locked","value":false},
+  {"name":"plugin_tree","value":"[
+    {\"plugin_name\":\"pl-simpledsapp\",\"plugin_version\":\"2.0.2\",\"previous_index\":null,
+      \"plugin_parameter_defaults\":[{\"name\":\"prefix\",\"default\":\"a\"}]},
+    {\"plugin_name\":\"pl-simpledsapp\",\"plugin_version\":\"2.0.2\",\"previous_index\":0,
+      \"plugin_parameter_defaults\":[{\"name\":\"prefix\",\"default\":\"b\"}]},
+    {\"plugin_name\":\"pl-simpledsapp\",\"plugin_version\":\"2.0.2\",\"previous_index\":0,
+      \"plugin_parameter_defaults\":[{\"name\":\"prefix\",\"default\":\"c\"}]},
+    {\"plugin_name\":\"pl-simpledsapp\",\"plugin_version\":\"2.0.2\",\"previous_index\":1,
+      \"plugin_parameter_defaults\":[{\"name\":\"prefix\",\"default\":\"d\"}]},
+    {\"plugin_name\":\"pl-simpledsapp\",\"plugin_version\":\"2.0.2\",\"previous_index\":2,
+      \"plugin_parameter_defaults\":[{\"name\":\"prefix\",\"default\":\"e\"}]},
+    {\"plugin_name\":\"pl-simpledsapp\",\"plugin_version\":\"2.0.2\",\"previous_index\":2,
+      \"plugin_parameter_defaults\":[{\"name\":\"prefix\",\"default\":\"f\"}]},
+    {\"plugin_name\":\"pl-simpledsapp\",\"plugin_version\":\"2.0.2\",\"previous_index\":2,
+      \"plugin_parameter_defaults\":[{\"name\":\"prefix\",\"default\":\"g\"}]},
+    {\"plugin_name\":\"pl-simpledsapp\",\"plugin_version\":\"2.0.2\",\"previous_index\":6,
+      \"plugin_parameter_defaults\":[{\"name\":\"prefix\",\"default\":\"h\"}]}
+  ]"}]}}
+"""
+expected = expected.replace('\n', ' ')
+
+
+def test_deserialize():
+    client = ChrisClient.from_login(address='http://localhost:8000/api/v1/',
+                                    username='chris', password='chris1234')
+    pipeline = client.get_pipeline('Example branching pipeline')
+    expected_plugin_tree = json.loads(json.loads(expected)['template']['data'][-1]['value'])
+    actual = pipeline.get_root().deserialize_tree()
+
+    # limitation: retrieved plugin tree will have all parameter defaults
+    for piping in actual:
+        __remove_defaults_except_prefix(piping)
+
+    assert sorted_pipings(actual) == sorted_pipings(expected_plugin_tree)
+
+
+def __remove_defaults_except_prefix(piping: dict) -> None:
+    piping['plugin_parameter_defaults'] = [
+        p for p in piping['plugin_parameter_defaults']
+        if p['name'] == 'prefix'
+    ]
+
+
+def sorted_pipings(plugin_tree: list) -> list:
+    return sorted(plugin_tree, key=SerializedPiping)
+
+
+class SerializedPiping:
+    def __init__(self, __d: dict):
+        self.plugin_name = __d['plugin_name']
+        self.plugin_version = __d['plugin_version']
+        self.previous_index = __d['previous_index']
+
+    def __lt__(self, other: 'SerializedPiping') -> bool:
+        if self.previous_index is None:
+            return True
+        if other.previous_index is None:
+            return False
+        if self.previous_index < other.previous_index:
+            return True
+        if self.plugin_name < other.plugin_name:
+            return True
+        if self.plugin_version < other.plugin_version:
+            return True
+        return False

examples/dummy_pipeline.sh

@@ -47,7 +47,7 @@ cat << EOF
 {"template":
   {"data":[{"name":"name","value":"Example branching pipeline"},
   {"name": "authors", "value": "Jennings Zhang <[email protected]>"},
-  {"name": "Category", "value": "Example"},
+  {"name": "category", "value": "Example"},
   {"name": "description", "value":
   "A more complicated but nonetheless useless pipeline."},
   {"name":"locked","value":false},

examples/upload_reconstruction_pipeline.sh

@@ -39,7 +39,7 @@ cat << EOF
 {"template":
   {"data":[{"name":"name","value":"Automatic Fetal Brain Reconstruction Pipeline v1.0.0"},
   {"name": "authors", "value": "Jennings Zhang <[email protected]>"},
-  {"name": "Category", "value": "MRI"},
+  {"name": "category", "value": "MRI"},
   {"name": "description", "value":
   "Automatic fetal brain reconstruction pipeline developed by Kiho's group at the FNNDSC. Features machine-learning based brain masking and quality assessment."},
   {"name":"locked","value":false},

setup.py

@@ -6,7 +6,7 @@
 
 setup(
     name='caw',
-    version='0.5.0',
+    version='0.6.0',
     packages=find_packages(exclude=('*.tests',)),
     url='https://github.com/FNNDSC/caw',
     license='MIT',