BaseProxyObject: lazily introspect children as needed

The D-Bus specification says:

  “If a child <node> has any sub-elements, then they must represent a
   complete introspection of the child. If a child <node> is empty, then
   it may or may not have sub-elements; the child must be introspected
   in order to find out. The intent is that if an object knows that its
   children are "fast" to introspect it can go ahead and return their
   information, but otherwise it can omit it.”

However, BaseProxyObject.get_children() has been assuming that all child
<node> elements provide a complete introspection of their corresponding
child objects. This causes child objects to appear to have no interfaces
or children of their own, even when they in fact do.

To implement the spec, replace BaseProxyObject.introspection with a
lazily-computed property whose value is initialized as the intr.Node
passed to the BaseProxyObject constructor (or parsed by it), if one was
specified, or is otherwise computed upon first use by introspecting the
child object (synchronously). The synchronous introspection required
pulling the introspect_sync method up from glib.MessageBus into
BaseMessageBus as an abstract method and then implementing it in
aio.MessageBus by using asyncio.loop.run_until_complete(…).

Author: whitslack

src/dbus_fast/aio/message_bus.py

@@ -318,6 +318,16 @@ async def introspect(
         finally:
             timer_handle.cancel()
 
+    def introspect_sync(
+        self,
+        bus_name: str,
+        path: str,
+        *args, **kwargs
+    ) -> intr.Node:
+        return self._loop.run_until_complete(
+            self.introspect(bus_name, path, *args, **kwargs)
+        )
+
     async def request_name(
         self, name: str, flags: NameFlag = NameFlag.NONE
     ) -> RequestNameReply:

src/dbus_fast/aio/proxy_object.py

@@ -195,7 +195,7 @@ def __init__(
         self,
         bus_name: str,
         path: str,
-        introspection: intr.Node | str | ET.Element,
+        introspection: intr.Node | str | ET.Element | None,
         bus: BaseMessageBus,
     ) -> None:
         super().__init__(bus_name, path, introspection, bus, ProxyInterface)

src/dbus_fast/glib/proxy_object.py

@@ -307,7 +307,7 @@ def __init__(
         self,
         bus_name: str,
         path: str,
-        introspection: Union[intr.Node, str, ET.Element],
+        introspection: intr.Node | str | ET.Element | None,
         bus: BaseMessageBus,
     ):
         super().__init__(bus_name, path, introspection, bus, ProxyInterface)

src/dbus_fast/message_bus.py

@@ -309,6 +309,9 @@ def reply_notify(reply: Message | None, err: Exception | None) -> None:
             reply_notify,
         )
 
+    def introspect_sync(self, bus_name: str, path: str) -> intr.Node:
+        raise NotImplementedError("this must be implemented in the inheriting class")
+
     def _emit_interface_added(self, path: str, interface: ServiceInterface) -> None:
         """Emit the ``org.freedesktop.DBus.ObjectManager.InterfacesAdded`` signal.
 

src/dbus_fast/proxy_object.py

@@ -234,6 +234,8 @@ class BaseProxyObject:
     :ivar path: The object path exported on the client that owns the bus name.
     :vartype path: str
     :ivar introspection: Parsed introspection data for the proxy object.
+    May be ``None`` if introspection has not yet been performed, in which case
+    the object will be introspected lazily upon first use.
     :vartype introspection: :class:`Node <dbus_fast.introspection.Node>`
     :ivar bus: The message bus this proxy object is connected to.
     :vartype bus: :class:`BaseMessageBus <dbus_fast.message_bus.BaseMessageBus>`
@@ -252,7 +254,7 @@ def __init__(
         self,
         bus_name: str,
         path: str,
-        introspection: intr.Node | str | ET.Element,
+        introspection: intr.Node | str | ET.Element | None,
         bus: message_bus.BaseMessageBus,
         ProxyInterface: type[BaseProxyInterface],
     ) -> None:
@@ -264,12 +266,12 @@ def __init__(
         if not issubclass(ProxyInterface, BaseProxyInterface):
             raise TypeError("ProxyInterface must be an instance of BaseProxyInterface")
 
-        if type(introspection) is intr.Node:
-            self.introspection = introspection
+        if introspection is None or type(introspection) is intr.Node:
+            self._introspection = introspection
         elif type(introspection) is str:
-            self.introspection = intr.Node.parse(introspection)
+            self._introspection = intr.Node.parse(introspection)
         elif type(introspection) is ET.Element:
-            self.introspection = intr.Node.from_xml(introspection)
+            self._introspection = intr.Node.from_xml(introspection)
         else:
             raise TypeError(
                 "introspection must be xml node introspection or introspection.Node class"
@@ -279,13 +281,39 @@ def __init__(
         self.path = path
         self.bus = bus
         self.ProxyInterface = ProxyInterface
-        self.child_paths = [f"{path}/{n.name}" for n in self.introspection.nodes]
+        self._child_paths = None
 
         self._interfaces = {}
 
         # lazy loaded by get_children()
         self._children = None
 
+    @property
+    def introspection(self) -> intr.Node:
+        """Access the introspection of this object, performing it (synchronously) if necessary.
+
+        :raises:
+            - :class:`InvalidBusNameError <dbus_fast.InvalidBusNameError>` - If this object's bus name is not valid.
+            - :class:`InvalidObjectPathError <dbus_fast.InvalidObjectPathError>` - If this object's path is not valid.
+            - :class:`InvalidIntrospectionError <dbus_fast.InvalidIntrospectionError>` - If the introspection data for the node is not valid.
+        """
+        if self._introspection is None:
+            self._introspection = self.bus.introspect_sync(self.bus_name, self.path)
+        return self._introspection
+
+    @property
+    def child_paths(self) -> List[str]:
+        """Access the list of paths of this object's children, fetching it (synchronously) if necessary.
+
+        :raises:
+            - :class:`InvalidBusNameError <dbus_fast.InvalidBusNameError>` - If this object's bus name is not valid.
+            - :class:`InvalidObjectPathError <dbus_fast.InvalidObjectPathError>` - If this object's path is not valid.
+            - :class:`InvalidIntrospectionError <dbus_fast.InvalidIntrospectionError>` - If the introspection data for the node is not valid.
+        """
+        if self._child_paths is None:
+            self._child_paths = [f"{self.path}/{n.name}" for n in self.introspection.nodes]
+        return self._child_paths
+
     def get_interface(self, name: str) -> BaseProxyInterface:
         """Get an interface exported on this proxy object and connect it to the bus.
 
@@ -352,7 +380,8 @@ def get_children(self) -> list[BaseProxyObject]:
         if self._children is None:
             self._children = [
                 self.__class__(self.bus_name, f"{self.path}/{child.name}",
-                        child, self.bus)
+                        child if child.interfaces or child.nodes else None,
+                        self.bus)
                 for child in self.introspection.nodes
             ]
 

tests/test_introspection.py

@@ -10,7 +10,7 @@
 )
 from dbus_fast import introspection as intr
 from dbus_fast.constants import ErrorType
-from dbus_fast.errors import DBusError, InterfaceNotFoundError
+from dbus_fast.errors import DBusError
 from dbus_fast.message_bus import BaseMessageBus
 from dbus_fast.proxy_object import BaseProxyObject, BaseProxyInterface
 
@@ -200,7 +200,7 @@ class MockProxyObject(BaseProxyObject):
     def __init__(self,
         bus_name: str,
         path: str,
-        introspection: intr.Node | str | ET.Element,
+        introspection: intr.Node | str | ET.Element | None,
         bus: BaseMessageBus
     ) -> None:
         super().__init__(bus_name, path, introspection, bus, MockProxyInterface)
@@ -254,7 +254,6 @@ def test_inline_child():
     assert bus.introspect_count == 1
 
 
-@pytest.mark.xfail(reason='buggy BaseProxyObject.get_children', raises=InterfaceNotFoundError, strict=True)
 def test_noninline_child():
     obj0_node = intr.Node.parse(strict_data)
     bus = MockMessageBus({