D-Bus#

There are several classes that can help you interact with D-Bus.

class ignis.dbus.DBusService(name: str, object_path: str, info: gi.repository.Gio.DBusInterfaceInfo, on_name_acquired: Callable | None = None, on_name_lost: Callable | None = None)#

A class that helps create a D-Bus service.

from gi.repository import Gio, GLib
from ignis.dbus import DBusService

def _MyMethod(invocation: Gio.DBusMethodInvocation, prop1: str, prop2: str, *args) -> GLib.Variant:
    print("do something")
    return GLib.Variant("(is)", (42, "hello"))

def _MyProperty() -> GLib.Variant:
    return GLib.Variant("(b)", (False,))

dbus = DBusService(...)
dbus.register_dbus_method("MyMethod", _MyMethod)
dbus.register_dbus_property("MyProperty", _MyProperty)
property name: str#

  • required, read-only

The well-known name to own.

property object_path: str#

  • required, read-only

An object path.

property info: gi.repository.Gio.DBusInterfaceInfo#

  • required, read-only

An instance of Gio.DBusInterfaceInfo

You can get it from XML using load_interface_xml().

property on_name_acquired: Callable#

  • optional, read-write

The function to call when name is acquired.

property on_name_lost: Callable#

  • optional, read-write

The function to call when name is lost.

property connection: gi.repository.Gio.DBusConnection#

  • not argument, read-only

The instance of Gio.DBusConnection for this service.

property methods: dict[str, Callable]#

  • not argument, read-only

The dictionary of registred DBus methods. See register_dbus_method().

property properties: dict[str, Callable]#

  • not argument, read-only

The dictionary of registred DBus properties. See register_dbus_property().

register_dbus_method(name: str, method: Callable) → None#

Register a D-Bus method for this service.

Parameters:

  • name (str) -- The name of the method to register.

  • method (Callable) -- A function to call when the method is invoked (from D-Bus).

Return type:

None

DBus methods:

  • Must accept Gio.DBusMethodInvocation as the first argument.

  • Must accept all other arguments typical for this method (specified by interface info).

  • Must return GLib.Variant or None, as specified by interface info.

register_dbus_property(name: str, method: Callable) → None#

Register D-Bus property for this service.

Parameters:

  • name (str) -- The name of the property to register.

  • method (Callable) -- A function to call when the property is accessed (from DBus).

Return type:

None

DBus properties:
emit_signal(signal_name: str, parameters: GLib.Variant | None = None) → None#

Emit a D-Bus signal on this service.

Parameters:

  • signal_name -- The name of the signal to emit.

  • parameters (default: None) -- The GLib.Variant containing paramaters to pass with the signal.

unown_name() → None#

Release ownership of the name.

Return type:

None

class ignis.dbus.DBusProxy(bus_type: Literal['session', 'system'], gproxy: gi.repository.Gio.DBusProxy)#

A class to interact with D-Bus services (create a D-Bus proxy). Unlike Gio.DBusProxy, this class also provides convenient pythonic property access.

To call a D-Bus method, use the standart pythonic way. The first argument always needs to be the DBus signature tuple of the method call. Next arguments must match the provided D-Bus signature. If the D-Bus method does not accept any arguments, do not pass them.

from ignis.dbus import DBusProxy
proxy = DBusProxy.new(...)
result = proxy.MyMethod("(is)", 42, "hello")
print(result)

To get a D-Bus property:

from ignis.dbus import DBusProxy
proxy = DBusProxy.new(...)
print(proxy.MyValue)

To set a D-Bus property:

from ignis.dbus import DBusProxy
proxy = DBusProxy.new(...)
# pass GLib.Variant as new property value
proxy.MyValue = GLib.Variant("s", "Hello world!")
Parameters:

  • bus_type (Literal['session', 'system']) -- The type of the bus.

  • gproxy (DBusProxy) -- An instance of Gio.DBusProxy.

classmethod new(name: str, object_path: str, interface_name: str, info: gi.repository.Gio.DBusInterfaceInfo, bus_type: Literal['session', 'system'] = 'session') → DBusProxy#

Synchronously initialize a new instance.

Parameters:

  • name (str) -- A bus name (well-known or unique).

  • object_path (str) -- An object path.

  • interface_name (str) -- A D-Bus interface name.

  • info (DBusInterfaceInfo) -- A Gio.DBusInterfaceInfo instance. You can get it from XML using load_interface_xml.

  • bus_type (Literal['session', 'system'], default: 'session') -- The type of the bus.

Return type:

DBusProxy

classmethod new_async(name: str, object_path: str, interface_name: str, info: gi.repository.Gio.DBusInterfaceInfo, bus_type: Literal['session', 'system'] = 'session', callback: Callable | None = None, *user_data) → None#

Asynchronously initialize a new instance.

Parameters:

  • name (str) -- A bus name (well-known or unique).

  • object_path (str) -- An object path.

  • interface_name (str) -- A D-Bus interface name.

  • info (DBusInterfaceInfo) -- A Gio.DBusInterfaceInfo instance. You can get it from XML using load_interface_xml.

  • bus_type (Literal['session', 'system'], default: 'session') -- The type of the bus.

  • callback (Callable | None, default: None) -- A function to call when the initialization is complete. The function will receive a newly initialized instance of this class.

  • *user_data -- User data to pass to callback.

Return type:

None

property name: str#

  • read-only

A bus name (well-known or unique).

property object_path: str#

  • read-only

An object path.

property interface_name: str#

  • read-only

A D-Bus interface name.

property info: gi.repository.Gio.DBusInterfaceInfo#

  • read-only

A Gio.DBusInterfaceInfo instance.

You can get it from XML using load_interface_xml.

property bus_type: Literal['session', 'system']#

  • read-only

The type of the bus.

property gproxy: gi.repository.Gio.DBusProxy#

  • read-only

The Gio.DBusProxy instance.

property connection: gi.repository.Gio.DBusConnection#

  • read-only

The instance of Gio.DBusConnection for this proxy.

property methods: list[str]#

  • read-only

A list of methods exposed by D-Bus service.

property properties: list[str]#

  • read-only

A list of properties exposed by D-Bus service.

property has_owner: bool#

  • read-only

Whether the name has an owner.

signal_subscribe(signal_name: str, callback: Callable | None = None) → int#

Subscribe to D-Bus signal.

Parameters:

  • signal_name (str) -- The signal name to subscribe.

  • callback (Callable | None, default: None) -- A function to call when signal is emitted.

Return type:

int

Returns:

A subscription ID that can be used with signal_unsubscribe()

signal_unsubscribe(id: int) → None#

Unsubscribe from D-Bus signal.

Parameters:

id (int) -- The ID of the subscription.

Return type:

None

get_dbus_property(property_name: str) → Any#

Get the value of a D-Bus property by its name.

Parameters:

property_name (str) -- The name of the property.

Return type:

Any

get_dbus_property_async(property_name: str, callback: Callable | None = None, *user_data) → None#

Asynchronously get the value of a D-Bus property by its name.

Parameters:

  • property_name (str) -- The name of the property.

  • callback (Callable | None, default: None) -- A function to call when the retrieval is complete. The function will receive the property's value or GLib.Error in case of an error.

  • *user_data -- User data to pass to callback.

Return type:

None

set_dbus_property(property_name: str, value: gi.repository.GLib.Variant) → None#

Set a D-Bus property's value.

Parameters:

  • property_name (str) -- The name of the property to set.

  • value (Variant) -- The new value for the property.

Return type:

None

set_dbus_property_async(property_name: str, value: gi.repository.GLib.Variant, callback: Callable | None = None, *user_data) → None#

Asynchronously set a D-Bus property's value.

Parameters:

  • property_name (str) -- The name of the property to set.

  • value (Variant) -- The new value for the property.

  • callback (Callable | None, default: None) -- A function to call when the operation is complete.

  • *user_data -- User data to pass to callback.

Return type:

None

watch_name(on_name_appeared: Callable | None = None, on_name_vanished: Callable | None = None) → None#

Watch name.

Parameters:

  • on_name_appeared (Callable | None, default: None) -- A function to call when name appeared.

  • on_name_vanished (Callable | None, default: None) -- A function to call when name vanished.

Return type:

None

unwatch_name() → None#

Unwatch name.

Return type:

None