Improved dump/query tree (#400)

supriya/contexts/core.py

@@ -8,6 +8,7 @@
 import contextlib
 import dataclasses
 import itertools
+import shlex
 import threading
 from os import PathLike
 from typing import (
@@ -233,6 +234,9 @@ def __getstate__(self):
         del state["_thread_local"]
         return state
 
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} {self.boot_status.name} [{shlex.join(self.options)}]>"
+
     def __setstate__(self, state):
         self.__dict__.update(state)
         self._lock = threading.RLock()

supriya/contexts/entities.py

@@ -28,7 +28,7 @@
 from ..typing import AddActionLike, HeaderFormatLike, SampleFormatLike, SupportsRender
 from ..ugens import SynthDef
 from .errors import InvalidCalculationRate, InvalidMoment
-from .responses import BufferInfo, NodeInfo
+from .responses import BufferInfo, NodeInfo, QueryTreeGroup
 
 if TYPE_CHECKING:
     import numpy
@@ -798,6 +798,24 @@ class Group(Node):
 
     parallel: bool = False
 
+    def dump_tree(
+        self,
+        include_controls: bool = True,
+        sync: bool = True,
+    ) -> Union[Awaitable[Optional[QueryTreeGroup]], Optional[QueryTreeGroup]]:
+        """
+        Dump the group's node tree.
+
+        Emit ``/g_dumpTree`` requests.
+
+        :param include_controls: Flag for including synth control values.
+        :param sync: If true, communicate the request immediately. Otherwise bundle it
+            with the current request context.
+        """
+        return cast(Union["AsyncServer", "Server"], self.context).dump_tree(
+            group=self, include_controls=include_controls, sync=sync
+        )
+
     def free_children(self, synths_only: bool = False) -> None:
         """
         Free the group's children.
@@ -808,6 +826,24 @@ def free_children(self, synths_only: bool = False) -> None:
         """
         self.context.free_group_children(self, synths_only=synths_only)
 
+    def query_tree(
+        self,
+        include_controls: bool = True,
+        sync: bool = True,
+    ) -> Union[Awaitable[Optional[QueryTreeGroup]], Optional[QueryTreeGroup]]:
+        """
+        Query the group's node tree.
+
+        Emit ``/g_queryTree`` requests.
+
+        :param include_controls: Flag for including synth control values.
+        :param sync: If true, communicate the request immediately. Otherwise bundle it
+            with the current request context.
+        """
+        return cast(Union["AsyncServer", "Server"], self.context).query_tree(
+            group=self, include_controls=include_controls, sync=sync
+        )
+
     @property
     def children(self) -> List[Node]:
         """

supriya/contexts/realtime.py

@@ -92,7 +92,6 @@
     NodeInfo,
     QueryTreeGroup,
     QueryTreeInfo,
-    QueryTreeSynth,
     StatusInfo,
     VersionInfo,
 )
@@ -883,7 +882,7 @@ def query_tree(
         group: Optional[Group] = None,
         include_controls: bool = True,
         sync: bool = True,
-    ) -> Optional[Union[QueryTreeGroup, QueryTreeSynth]]:
+    ) -> Optional[QueryTreeGroup]:
         """
         Query the server's node tree.
 
@@ -1425,7 +1424,7 @@ async def query_tree(
         group: Optional[Group] = None,
         include_controls: bool = True,
         sync: bool = True,
-    ) -> Optional[Union[QueryTreeGroup, QueryTreeSynth]]:
+    ) -> Optional[QueryTreeGroup]:
         """
         Query the server's node tree.
 

supriya/contexts/responses.py

@@ -5,7 +5,7 @@
 import dataclasses
 import re
 from collections import deque
-from typing import Deque, Dict, List, Optional, Sequence, Tuple, Type, Union
+from typing import Deque, Dict, List, Optional, Sequence, Tuple, Type, Union, cast
 
 from ..enums import NodeAction
 from ..osc import OscMessage
@@ -346,8 +346,6 @@ class QueryTreeSynth:
     synthdef_name: Optional[str]
     controls: List[QueryTreeControl] = dataclasses.field(default_factory=list)
 
-    ### SPECIAL METHODS ###
-
     def __format__(self, format_spec):
         return "\n".join(
             self._get_str_format_pieces(unindexed=format_spec == "unindexed")
@@ -356,8 +354,6 @@ def __format__(self, format_spec):
     def __str__(self):
         return "\n".join(self._get_str_format_pieces())
 
-    ### PRIVATE METHODS ###
-
     def _get_str_format_pieces(self, unindexed=False):
         result = []
         node_id = self.node_id
@@ -404,9 +400,7 @@ def _get_str_format_pieces(self, unindexed=False):
     ### PUBLIC METHODS ###
 
     @classmethod
-    def from_query_tree_info(
-        cls, response: QueryTreeInfo
-    ) -> Union["QueryTreeGroup", "QueryTreeSynth"]:
+    def from_query_tree_info(cls, response: QueryTreeInfo) -> "QueryTreeGroup":
         def recurse(
             item: QueryTreeInfo.Item, items: Deque[QueryTreeInfo.Item]
         ) -> Union[QueryTreeGroup, QueryTreeSynth]:
@@ -424,11 +418,14 @@ def recurse(
                 children.append(recurse(items.popleft(), items))
             return QueryTreeGroup(node_id=item.node_id, children=children)
 
-        return recurse(
-            QueryTreeInfo.Item(
-                node_id=response.node_id, child_count=response.child_count
+        return cast(
+            QueryTreeGroup,
+            recurse(
+                QueryTreeInfo.Item(
+                    node_id=response.node_id, child_count=response.child_count
+                ),
+                deque(response.items),
             ),
-            deque(response.items),
         )
 
     @classmethod