[ports] Add tests for including subtrees in other files

Author: sea-bass

docs/ports.rst

@@ -227,6 +227,67 @@ Example::
    <Greeting name="hello_node" name_key="{target}" prefix="Howdy"/>
    <!--       ^^^ behaviour name   ^^^ port remap    ^^^ ctor kwarg  -->
 
+.. _ports-xml-includes-label:
+
+Composing trees from multiple files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Subtrees do not have to live in the same file as the tree that uses them.
+A top-level ``<Include>`` (or ``<Import>``) element pulls all ``<BehaviorTree>``
+definitions from another XML file into the current document before parsing,
+so you can maintain a library of reusable subtrees in separate files:
+
+.. code-block:: xml
+
+   <!-- subtree_library.xml -->
+   <root>
+     <BehaviorTree ID="LibraryTree">
+       <Sequence>
+         <Producer name="LibProducer" output="{lib_out}"/>
+       </Sequence>
+     </BehaviorTree>
+   </root>
+
+.. code-block:: xml
+
+   <!-- main_tree.xml -->
+   <root main_tree_to_execute="MainTree">
+     <Include src="subtree_library.xml"/>
+     <BehaviorTree ID="MainTree">
+       <Sequence>
+         <SubTree ID="LibraryTree" name="Library" lib_out="{final}"/>
+         <Consumer name="FinalConsumer" input="{final}"/>
+       </Sequence>
+     </BehaviorTree>
+   </root>
+
+The path in ``src=`` (``file=`` is accepted as an alias) is resolved in order:
+
+1. As an absolute path, if it is one.
+2. Relative to the directory of the *including* XML file.
+3. Against each directory in the ``search_paths`` argument of
+   :func:`~py_trees.parsers.behaviour_tree_xml.parse_behaviour_tree_xml`.
+
+So if the library file lives somewhere other than next to the main file --- say a
+shared ``subtrees/`` directory --- pass that directory via ``search_paths``:
+
+.. code-block:: python
+
+   root = parse_behaviour_tree_xml(
+       "main_tree.xml",
+       search_paths=["/path/to/subtrees"],
+   )
+
+A few more rules to be aware of:
+
+* Includes are only recognised as **top-level** children of ``<root>``; an
+  ``<Include>`` nested inside a ``<BehaviorTree>`` is an error.
+* Includes are processed **recursively** --- an included file may itself include
+  further files --- and cycles are detected and skipped.
+* All BehaviorTree IDs must be unique across the main file and everything it
+  includes; a collision raises ``ValueError``.
+* ``main_tree_to_execute`` may refer to a tree defined in an included file.
+
 Scope, limitations, and how to extend
 -------------------------------------
 

tests/test_ports_xml_parser.py

@@ -181,7 +181,7 @@ def test_xml_parser_remapping(self) -> None:
 
     def test_grandparent_xml(self) -> None:
         """Test XML parser with grandparent-child relationships and correct value propagation."""
-        xml_path = os.path.join(os.path.dirname(__file__), "grandparent_test.xml")
+        xml_path = os.path.join(os.path.dirname(__file__), "xml", "grandparent_test.xml")
         root_node = parse_behaviour_tree_xml(xml_path, logger=StdoutLogger())
         btree = py_trees.trees.BehaviourTree(root_node)
         btree.tick()
@@ -888,6 +888,33 @@ def test_import_with_search_paths(self) -> None:
             assert isinstance(c, Consumer)
             self.assertEqual(c.consumed_value, "Producer[/L:L.MySeq.P]")
 
+    def test_include_subtree_file_with_search_paths(self) -> None:
+        """A subtree <Include>d from a sibling directory resolves via 'search_paths'.
+
+        Uses the on-disk fixtures in tests/xml/: the main tree includes
+        'subtree_library.xml', which lives in tests/xml/subtrees/ and is therefore
+        only found when that directory is passed via 'search_paths'.
+        """
+        xml_dir = os.path.join(os.path.dirname(__file__), "xml")
+        main_path = os.path.join(xml_dir, "main_tree_with_include.xml")
+        root = parse_behaviour_tree_xml(
+            main_path,
+            logger=StdoutLogger(),
+            search_paths=[os.path.join(xml_dir, "subtrees")],
+        )
+        tree = py_trees.trees.BehaviourTree(root)
+        tree.tick()
+        consumer = find_node_by_name(root, "FinalConsumer", strip_prefix=True)
+        assert isinstance(consumer, Consumer)
+        self.assertEqual(consumer.consumed_value, "Producer[/Library:Library.LibSeq.LibProducer]")
+
+    def test_include_subtree_file_without_search_paths_fails(self) -> None:
+        """Without 'search_paths', the include in tests/xml/ cannot be resolved."""
+        xml_dir = os.path.join(os.path.dirname(__file__), "xml")
+        main_path = os.path.join(xml_dir, "main_tree_with_include.xml")
+        with self.assertRaises(FileNotFoundError):
+            parse_behaviour_tree_xml(main_path, logger=StdoutLogger())
+
     def test_imported_bt_missing_id(self) -> None:
         """Imported file containing a <BehaviorTree> without an ID raises ValueError."""
         lib_path = self._write_temp_xml("""<root><BehaviorTree><Sequence/></BehaviorTree></root>""")

tests/grandparent_test.xml tests/xml/grandparent_test.xmltests/grandparent_test.xml renamed to tests/xml/grandparent_test.xml

@@ -0,0 +1,14 @@
+<root main_tree_to_execute="MainTree">
+  <!--
+    The included file lives in the sibling 'subtrees' directory, so it can only
+    be resolved by passing search_paths=[.../tests/xml/subtrees] to
+    parse_behaviour_tree_xml(). Without it, parsing raises FileNotFoundError.
+  -->
+  <Include src="subtree_library.xml"/>
+  <BehaviorTree ID="MainTree">
+    <Sequence>
+      <SubTree ID="LibraryTree" name="Library" lib_out="{final}"/>
+      <Consumer name="FinalConsumer" input="{final}"/>
+    </Sequence>
+  </BehaviorTree>
+</root>

tests/xml/main_tree_with_include.xml

@@ -0,0 +1,7 @@
+<root>
+  <BehaviorTree ID="LibraryTree">
+    <Sequence name="LibSeq">
+      <Producer name="LibProducer" output="{lib_out}"/>
+    </Sequence>
+  </BehaviorTree>
+</root>