Utilities

Parsing utilities

Parse unweildy D-Bus structures in to Python native objects and names. Available under sdbus.utils.parse subpackage.

sdbus.utils.parse.parse_properties_changed(interface: InterfacesInputElements, properties_changed_data: DBUS_PROPERTIES_CHANGED_TYPING, on_unknown_member: OnUnknownMember = 'error') → dict[str, Any]

Parse data from properties_changed signal.

Parses changed properties from a single D-Bus object. The object’s interface class must be known in advance and passed as a first argument.

Member names will be translated to python defined names. Invalidated properties will have a value of None.

Parameters:

  • interface – Takes either D-Bus interface class or its object.

  • properties_changed_data – Tuple caught from signal.

  • on_unknown_member – If an unknown D-Bus property was encountered either raise an "error" (default), "ignore" the property or "reuse" the D-Bus name for the member.

Returns:

Dictionary of changed properties with keys translated to python names. Invalidated properties will have value of None.

sdbus.utils.parse.parse_interfaces_added(interfaces: InterfacesInput, interfaces_added_data: tuple[str, dict[str, dict[str, Any]]], on_unknown_interface: OnUnknownInterface = 'error', on_unknown_member: OnUnknownMember = 'error', *, use_interface_subsets: bool = False) → tuple[str, InterfacesBaseTypes | None, dict[str, Any]]

Parse data from interfaces_added signal.

Takes the possible interface classes and the signal data. Returns the path of new object, the class of the added object (if it matched one of passed interface classes) and the dictionary of python named properties and their values.

The passed interfaces can be async or blocking, the class or an instantiated object, a single item or an iterable of interfaces.

Parameters:

  • interfaces – Possible interfaces that were added.

  • interfaces_added_data – Tuple caught from signal.

  • on_unknown_interface – If an unknown D-Bus interface was encountered either raise an "error" (default) or return "none" instead of interface class.

  • on_unknown_member – If an unknown D-Bus property was encountered either raise an "error" (default), "ignore" the property or "reuse" the D-Bus name for the member.

  • use_interface_subsets – Use the subset of interfaces as a valid match. For example, the class that implements org.example.foo would be matched with an data consising of both org.example.foo and org.example.bar. The classes implementing more interfaces will have higher priority over the ones implementing fewer.

Returns:

Path of new added object, object’s class (or None) and dictionary of python translated members and their values.

sdbus.utils.parse.parse_interfaces_removed(interfaces: InterfacesInput, interfaces_removed_data: tuple[str, list[str]], on_unknown_interface: OnUnknownInterface = 'error', *, use_interface_subsets: bool = False) → tuple[str, InterfacesBaseTypes | None]

Parse data from interfaces_added signal.

Takes the possible interface classes and the signal data. Returns the path and the matched class of removed object. (if it matched one of passed interface classes)

The passed interfaces can be async or blocking, the class or an instantiated object, a single item or an iterable of interfaces.

Parameters:

  • interfaces – Possible interfaces that were removed.

  • interfaces_added_data – Tuple caught from signal.

  • on_unknown_member – If an unknown D-Bus interface was encountered either raise an "error" (default) or return "none" instead of interface class.

  • use_interface_subsets – Use the subset of interfaces as a valid match. For example, the class that implements org.example.foo would be matched with an data consising of both org.example.foo and org.example.bar. The classes implementing more interfaces will have higher priority over the ones implementing fewer.

Returns:

Path of removed object and object’s class (or None).

sdbus.utils.parse.parse_get_managed_objects(interfaces: InterfacesInput, managed_objects_data: dict[str, dict[str, dict[str, Any]]], on_unknown_interface: OnUnknownInterface = 'error', on_unknown_member: OnUnknownMember = 'error', *, use_interface_subsets: bool = False) → ParseGetManaged

Parse data from get_managed_objects call.

Takes the possible interface classes and the method’s returned data. Returns a dictionary where keys a paths of the managed objects and value is a tuple of class of the object and dictionary of its python named properties and their values.

The passed interfaces can be async or blocking, the class or an instantiated object, a single item or an iterable of interfaces.

Parameters:

  • interfaces – Possible interfaces of the managed objects.

  • managed_objects_data – Data returned by get_managed_objects call.

  • on_unknown_interface – If an unknown D-Bus interface was encountered either raise an "error" (default) or return "none" instead of interface class.

  • on_unknown_member – If an unknown D-Bus property was encountered either raise an "error" (default), "ignore" the property or "reuse" the D-Bus name for the member.

  • use_interface_subsets – Use the subset of interfaces as a valid match. For example, the class that implements org.example.foo would be matched with an data consising of both org.example.foo and org.example.bar. The classes implementing more interfaces will have higher priority over the ones implementing fewer.

Returns:

Dictionary where keys are paths and values are tuples of managed objects classes and their properties data.

New in version 0.12.0.

Inspect utilities

Inspect D-Bus objects and retrieve their D-Bus related attributes such as D-Bus object paths and etc… Available under sdbus.utils.inspect subpackage.

sdbus.utils.inspect.inspect_dbus_bus(obj: DbusInterfaceBase | DbusInterfaceBaseAsync) → SdBus | None

Return D-Bus bus used by the object.

If called on D-Bus proxies or exported local D-Bus objects returns bus object.

If called on local D-Bus objects that had not been exported returns None.

If called on an object that is unrelated to D-Bus raises TypeError.

Parameters:

obj – Object to inspect.

Returns:

D-Bus bus object.

New in version 0.14.1.

sdbus.utils.inspect.inspect_dbus_path(obj: DbusInterfaceBase | DbusInterfaceBaseAsync, bus: SdBus | None = None) → str

Return the D-Bus path of an object.

If called on a D-Bus proxy returns path of the proxied object.

If called on a local D-Bus object returns the exported D-Bus path. If object is not exported raises LookupError.

If called on an object that is unrelated to D-Bus raises TypeError.

The object’s path is inspected in the context of the given bus and if the object is attached to a different bus the LookupError will be raised. If the bus argument is not given or is None the default bus will be checked against.

Parameters:

  • obj – Object to inspect.

  • bus – Bus to inspect against. If not given or is None the default bus will be used.

Returns:

D-Bus path of the object.

New in version 0.13.0.