The D-Bus library is a messaging library used by various desktop environments (GNOME, KDE, etc) for interprocess communication.
There's a Python binding for it, but documentation is non-existent so I've collected these examples in hopes that they'll be useful and that people will update them as needed.
Warning: the D-Bus APIs change a lot, breaking code. These examples were run with version 0.60 of the Python interface (0.60-6ubuntu8, on Ubuntu Dapper); they probably won't run on other versions.
This draft tutorial is the clearest introduction to D-Bus that I've seen.
The dbus-viewer program lets you browse through the services and interfaces available on your system.
# You must initialize the gobject/dbus support for threading # before doing anything. import gobject gobject.threads_init() from dbus import glib glib.init_threads() # Create a session bus. import dbus bus = dbus.SessionBus() # Create an object that will proxy for a particular remote object. remote_object = bus.get_object("org.freedesktop.DBus", # Connection name "/org/freedesktop/DBus" # Object's path ) # Introspection returns an XML document containing information # about the methods supported by an interface. print ("Introspection data:\n") print remote_object.Introspect()
Introspection data: <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> <node> <interface name="org.freedesktop.DBus.Introspectable"> <method name="Introspect"> <arg name="data" direction="out" type="s"/> </method> </interface> <interface name="org.freedesktop.DBus"> <method name="RequestName"> <arg direction="in" type="s"/> <arg direction="in" type="u"/> <arg direction="out" type="u"/> </method> ...
If you get any of the connection or object names wrong, the exceptions you get are very obscure. For example, when I add an incorrect trailing slash to the object in the example above (making "/org/freedesktop/DBus/"), the exceptions are:
8223: arguments to dbus_message_new_method_call() were incorrect, assertion "_dbus_check_is_valid_path (path)" failed in file dbus-message.c line 797. This is normally a bug in some application using the D-BUS library. 8223: arguments to dbus_message_set_destination() were incorrect, assertion "message != NULL" failed in file dbus-message.c line 2728. This is normally a bug in some application using the D-BUS library. 8223: arguments to dbus_connection_send_with_reply() were incorrect, assertion "message != NULL" failed in file dbus-connection.c line 2430. This is normally a bug in some application using the D-BUS library. Traceback (most recent call last): File "/home/amk/db.py", line 19, in ? data = remote_object.Introspect() File "/usr/lib/python2.4/site-packages/dbus/proxies.py", line 201, in __getattr__ self._pending_introspect.block() AttributeError: 'NoneType' object has no attribute 'block'
Notice that the exception is triggered in the .Introspect() call, not in the erroneous bus.get_object() call.
Calling an interface method
After executing the introspection example:
# Get a particular interface iface = dbus.Interface(remote_object, 'org.freedesktop.DBus') print iface.ListNames()
[u'org.freedesktop.DBus', u':1.3', u'org.freedesktop.Notifications', u'org.gnome.PowerManager', u':1.24', u':1.4', u':1.0', u'org.gnome.ScreenSaver', u':1.5', u':1.1', u':1.48', u':1.2']
The following example makes your system hibernate:
# Get the power management object power = bus.get_object('org.gnome.PowerManager', '/org/gnome/PowerManager') iface = dbus.Interface(power, 'org.gnome.PowerManager') # Hibernate the system if iface.CanHibernate(): iface.Hibernate()