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.

Parameters:

  • name (str) -- The well-known name to own.

  • object_path (str) -- An object path.

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

  • on_name_acquired (Callable | None, default: None) -- The function to call when name is acquired.

  • on_name_lost (Callable | None, default: None) -- The function to call when name is lost.

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)
gproperty name: str#

  • read-only

The well-known name to own.

gproperty object_path: str#

  • read-only

An object path.

gproperty info: gi.repository.Gio.DBusInterfaceInfo#

  • read-only

An instance of Gio.DBusInterfaceInfo

You can get it from XML using load_interface_xml().

gproperty on_name_acquired: Callable#

  • read-write

The function to call when name is acquired.

gproperty on_name_lost: Callable#

  • read-write

The function to call when name is lost.

gproperty connection: gi.repository.Gio.DBusConnection#

  • read-only

The instance of Gio.DBusConnection for this service.

gproperty methods: dict[str, Callable]#

  • read-only

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

gproperty properties: dict[str, Callable]#

  • 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. Add Async at the end of the method name to call it asynchronously.

from ignis.dbus import DBusProxy

# sync
proxy = DBusProxy.new(...)
result = proxy.MyMethod("(is)", 42, "hello")
print(result)

# async
async def some_func():
    proxy = DBusProxy.new_async(...)
    result = proxy.MyMethodAsync("(is)", 42, "hello")

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

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

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 -- 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:

DBusProxy

gproperty name: str#

  • read-only

A bus name (well-known or unique).

gproperty object_path: str#

  • read-only

An object path.

gproperty interface_name: str#

  • read-only

A D-Bus interface name.

gproperty info: gi.repository.Gio.DBusInterfaceInfo#

  • read-only

A Gio.DBusInterfaceInfo instance.

You can get it from XML using load_interface_xml.

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

  • read-only

The type of the bus.

gproperty gproxy: gi.repository.Gio.DBusProxy#

  • read-only

The Gio.DBusProxy instance.

gproperty connection: gi.repository.Gio.DBusConnection#

  • read-only

The instance of Gio.DBusConnection for this proxy.

gproperty methods: list[str]#

  • read-only

A list of methods exposed by D-Bus service.

gproperty properties: list[str]#

  • read-only

A list of properties exposed by D-Bus service.

gproperty 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

call(method_name: str, signature: str | None = None, *args, flags: gi.repository.Gio.DBusCallFlags = gi.repository.Gio.DBusCallFlags.NONE, timeout: int = -1) → Any#

Call a D-Bus method on self.

Parameters:

  • method_name (str) -- The name of the method.

  • signature (str | None, default: None) -- The D-Bus signature.

  • *args -- Arguments to pass to the D-Bus method.

  • flags (DBusCallFlags, default: gi.repository.Gio.DBusCallFlags.NONE) -- D-Bus call flags.

  • timeout (int, default: -1) -- The timeout in milliseconds, or -1 to use the proxy default timeout.

Return type:

Any

Returns:

The returned data from the D-Bus method.

async call_async(method_name: str, signature: str | None = None, *args, flags: gi.repository.Gio.DBusCallFlags = gi.repository.Gio.DBusCallFlags.NONE, timeout: int = -1) → Any#

Asynchronously call a D-Bus method on self.

Parameters:

  • method_name (str) -- The name of the method.

  • signature (str | None, default: None) -- The D-Bus signature.

  • *args -- Arguments to pass to the D-Bus method.

  • flags (DBusCallFlags, default: gi.repository.Gio.DBusCallFlags.NONE) -- D-Bus call flags.

  • timeout (int, default: -1) -- The timeout in milliseconds, or -1 to use the proxy default timeout.

Return type:

Any

Returns:

The returned data from the D-Bus method.

get_dbus_property(property_name: str, unpack: bool = True) → Any | GLib.Variant#

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

Parameters:

  • property_name -- The name of the property.

  • unpack (default: True) -- Whether to unpack the returned GLib.Variant.

Returns:

The value of the D-Bus property or GLib.Variant.

async get_dbus_property_async(property_name: str, unpack: bool = True) → Any | GLib.Variant#

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

Parameters:

  • property_name -- The name of the property.

  • unpack (default: True) -- Whether to unpack the returned GLib.Variant.

Returns:

The value of the D-Bus property or GLib.Variant.

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

async set_dbus_property_async(property_name: str, value: gi.repository.GLib.Variant) → 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.

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