client/python: LazyBrowseNode walker for lazy hierarchy browse

clients/python/src/zb_mom_ww_mxgateway/galaxy.py

@@ -21,9 +21,10 @@ from .auth import merge_metadata
 from .errors import MxGatewayError, map_rpc_error
 from .generated import galaxy_repository_pb2 as galaxy_pb
 from .generated import galaxy_repository_pb2_grpc as galaxy_pb_grpc
-from .options import ClientOptions, create_channel
+from .options import BrowseChildrenOptions, ClientOptions, create_channel
 
 _DISCOVER_HIERARCHY_PAGE_SIZE = 5000
+_BROWSE_CHILDREN_PAGE_SIZE = 500
 
 
 class GalaxyRepositoryClient:
@@ -139,6 +140,73 @@ class GalaxyRepositoryClient:
                 )
             seen_page_tokens.add(page_token)
 
+    async def browse(
+        self,
+        options: BrowseChildrenOptions | None = None,
+    ) -> list["LazyBrowseNode"]:
+        """Return the root browse nodes for lazy hierarchy traversal.
+
+        Each returned ``LazyBrowseNode`` wraps a Galaxy object whose direct
+        children can be loaded on demand by ``await node.expand()``.
+        """
+
+        effective = options or BrowseChildrenOptions()
+        return [
+            node
+            async for node in self._iter_browse_children(
+                parent_gobject_id=None,
+                options=effective,
+            )
+        ]
+
+    async def _iter_browse_children(
+        self,
+        *,
+        parent_gobject_id: int | None,
+        options: BrowseChildrenOptions,
+    ) -> AsyncIterator["LazyBrowseNode"]:
+        page_token = ""
+        seen_page_tokens: set[str] = set()
+        while True:
+            request = galaxy_pb.BrowseChildrenRequest(
+                page_size=_BROWSE_CHILDREN_PAGE_SIZE,
+                page_token=page_token,
+                alarm_bearing_only=options.alarm_bearing_only,
+                historized_only=options.historized_only,
+            )
+            if parent_gobject_id is not None:
+                request.parent_gobject_id = parent_gobject_id
+            if options.category_ids:
+                request.category_ids.extend(options.category_ids)
+            if options.template_chain_contains:
+                request.template_chain_contains.extend(options.template_chain_contains)
+            if options.tag_name_glob:
+                request.tag_name_glob = options.tag_name_glob
+            if options.include_attributes is not None:
+                request.include_attributes = options.include_attributes
+
+            reply = await self._unary(
+                "browse children",
+                self.raw_stub.BrowseChildren,
+                request,
+            )
+
+            for index, obj in enumerate(reply.children):
+                hint = (
+                    index < len(reply.child_has_children)
+                    and bool(reply.child_has_children[index])
+                )
+                yield LazyBrowseNode(self, obj, hint, options)
+
+            page_token = reply.next_page_token
+            if not page_token:
+                return
+            if page_token in seen_page_tokens:
+                raise MxGatewayError(
+                    f"galaxy browse children returned repeated page token {page_token!r}"
+                )
+            seen_page_tokens.add(page_token)
+
     def watch_deploy_events(
         self,
         last_seen_deploy_time: datetime | None = None,
@@ -202,6 +270,63 @@ class GalaxyRepositoryClient:
             raise map_rpc_error(operation, error) from error
 
 
+class LazyBrowseNode:
+    """One node in a lazy-loaded Galaxy browse tree.
+
+    Calling ``expand`` once fetches direct children (paginating as needed)
+    and populates ``children``. Subsequent calls are no-ops so callers can
+    drive UI expand toggles without de-duping.
+    """
+
+    def __init__(
+        self,
+        client: "GalaxyRepositoryClient",
+        obj: galaxy_pb.GalaxyObject,
+        has_children_hint: bool,
+        options: BrowseChildrenOptions,
+    ) -> None:
+        """Initialize a node bound to its owning client and filter set."""
+        self._client = client
+        self._object = obj
+        self._has_children_hint = has_children_hint
+        self._options = options
+        self._children: list[LazyBrowseNode] = []
+        self._is_expanded = False
+
+    @property
+    def object(self) -> galaxy_pb.GalaxyObject:
+        """Return the underlying ``GalaxyObject`` proto for this node."""
+        return self._object
+
+    @property
+    def has_children_hint(self) -> bool:
+        """Return the server hint about whether this node has children."""
+        return self._has_children_hint
+
+    @property
+    def children(self) -> list["LazyBrowseNode"]:
+        """Return a copy of the loaded child nodes (empty until expanded)."""
+        return list(self._children)
+
+    @property
+    def is_expanded(self) -> bool:
+        """Return whether ``expand`` has already populated ``children``."""
+        return self._is_expanded
+
+    async def expand(self) -> None:
+        """Fetch direct children of this node; no-op on subsequent calls."""
+        if self._is_expanded:
+            return
+        new_children: list[LazyBrowseNode] = []
+        async for child in self._client._iter_browse_children(
+            parent_gobject_id=self._object.gobject_id,
+            options=self._options,
+        ):
+            new_children.append(child)
+        self._children.extend(new_children)
+        self._is_expanded = True
+
+
 async def _canceling_iterator(call: Any) -> AsyncIterator[galaxy_pb.DeployEvent]:
     try:
         async for event in call:

clients/python/src/zb_mom_ww_mxgateway/options.py

@@ -2,7 +2,8 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from collections.abc import Sequence
+from dataclasses import dataclass, field
 from pathlib import Path
 
 import grpc
@@ -51,6 +52,23 @@ class ClientOptions:
         )
 
 
+@dataclass(frozen=True)
+class BrowseChildrenOptions:
+    """Filters and shape options for ``GalaxyRepositoryClient.browse``.
+
+    Mirrors the AND-combined filter set on ``BrowseChildrenRequest`` so a
+    single instance can be re-used across an entire lazy browse session
+    (the filter set is part of the page-token contract).
+    """
+
+    category_ids: Sequence[int] = field(default_factory=tuple)
+    template_chain_contains: Sequence[str] = field(default_factory=tuple)
+    tag_name_glob: str | None = None
+    include_attributes: bool | None = None
+    alarm_bearing_only: bool = False
+    historized_only: bool = False
+
+
 def create_channel(options: ClientOptions) -> grpc.aio.Channel:
     """Create a plaintext or TLS `grpc.aio` channel from client options."""