ENH: include save_tree_to_path from #54

beams/tests/test_tree_generator.py

@@ -6,7 +6,8 @@
 from epics import caget
 
 from beams.behavior_tree.CheckAndDo import CheckAndDo
-from beams.tree_config import get_tree_from_path
+from beams.tree_config import (CheckAndDoItem, get_tree_from_path,
+                               save_tree_item_to_path)
 
 
 def test_tree_obj_ser():
@@ -66,3 +67,12 @@ def test_father_tree_execution(request):
     check_insert = caget("RET:INSERT")
 
     assert check_insert == 1
+
+
+def test_save_tree_item_round_trip(tmp_path: Path):
+    filepath = tmp_path / "temp_egg.json"
+    item = CheckAndDoItem(name="test_save_tree_item_round_trip")
+    save_tree_item_to_path(path=filepath, root=item)
+    loaded_tree = get_tree_from_path(path=filepath)
+    assert isinstance(loaded_tree.root, CheckAndDo)
+    assert loaded_tree.root.name == item.name

beams/tree_config.py

@@ -10,7 +10,7 @@
 from typing import Any, Callable, List, Optional, Union
 
 import py_trees
-from apischema import deserialize
+from apischema import deserialize, serialize
 from epics import caget, caput
 from py_trees.behaviour import Behaviour
 from py_trees.behaviours import (CheckBlackboardVariableValue,
@@ -27,14 +27,37 @@
 
 
 def get_tree_from_path(path: Path) -> py_trees.trees.BehaviourTree:
-    """Deserialize a json file, return the tree it specifies"""
+    """
+    Deserialize a json file, return the tree it specifies.
+
+    This can be used internally to conveniently and consistently load
+    serialized json files as ready-to-run behavior trees.
+    """
     with open(path, "r") as fd:
         deser = json.load(fd)
         tree_item = deserialize(BehaviorTreeItem, deser)
 
     return tree_item.get_tree()
 
 
+def save_tree_item_to_path(path: Union[Path, str], root: BaseItem):
+    """
+    Serialize a behavior tree item to a json file.
+
+    This can be used to generate serialized trees from python scripts.
+    The user needs to create various interwoven tree items, pick the
+    correct item to be the root node, and then use this function to
+    save the serialized file.
+
+    These files are ready to be consumed by get_tree_from_path.
+    """
+    ser = serialize(BehaviorTreeItem(root=root))
+
+    with open(path, "w") as fd:
+        json.dump(ser, fd, indent=2)
+        fd.write("\n")
+
+
 @dataclass
 class BehaviorTreeItem:
     root: BaseItem

docs/source/upcoming_release_notes/58-enh_add_serialize_helper.rst

@@ -0,0 +1,23 @@
+58 enh_add_serialize_helper
+###########################
+
+API Breaks
+----------
+- N/A
+
+Features
+--------
+- Add ``save_tree_item_to_path``, a helper function for serializing user-made
+  behavior trees into the format usable by ``get_tree_from_path``.
+
+Bugfixes
+--------
+- N/A
+
+Maintenance
+-----------
+- Improve docstring on ``get_tree_from_path``.
+
+Contributors
+------------
+- zllentz