gruvi.dbus – D-BUS Client and Server

The gruvi.dbus module implements a D-BUS client and server.

The implementation uses parts of the txdbus project. A cut down copy of txdbus, containing only those parts needed by Gruvi, is available as gruvi.txdbus. You need this if you are providing a message handler (see below).

Both a client and a server/bus-side implementation are provided. The bus-side implementation is very bare bones and apart from the “Hello” message it does not implement any of the “org.freedestkop.DBus” interface. It also does not implement any message routing. The server side is provided mostly for testing purposes (but it could serve as the basis for a real D-BUS server).

The client side of a D-BUS connection is implemented by DbusClient and the server/bus-side by DbusServer. Both implement a procedural interface. Messages can be send using e.g. DbusClient.send_message() or DbusClient.call_method(). An object-oriented interface that represents D-BUS objects as Python objects, like the one txdbus provides, is currently not available. The procedural interface can be used as a basis for your own object-oriented interface though.

To receive notifications or to respond to method calls, you need to provide a message handler to the client or the server constructor. The signature of the message handler is: message_handler(message, protocol). Here, the message argument is an instance of gruvi.txdbus.DbusMessages, and the protocol will be the DbusProtocol instance for the current connection.

Message handlers runs in their own fiber, which allows them to call into switchpoints. There is one fiber for every connection.

Usage example:

client = gruvi.DbusClient()
client.connect('session')
result = client.call_method('org.freedesktop.DBus', '/org/freedesktop/DBus',
                            'org.freedesktop.DBus', 'ListNames')
for name in result[0]:
    print('Name: {}'.format(name))
exception DbusError

Exception that is raised in case of D-BUS protocol errors.

exception DbusMethodCallError(method, reply)

Exception that is raised when a error reply is received for a D-BUS method call.

class DbusProtocol(message_handler=None, server_side=False, server_guid=None, timeout=None)

D-BUS Protocol.

switchpoint get_unique_name()

Return the unique name of the D-BUS connection.

switchpoint send_message(message)

Send a D-BUS message.

The message argument must be gruvi.txdbus.DbusMessage instance.

switchpoint call_method(service, path, interface, method, signature=None, args=None, no_reply=False, auto_start=False, timeout=-1)

Call a D-BUS method and wait for its reply.

This method calls the D-BUS method with name method that resides on the object at bus address service, at path path, on interface interface.

The signature and args are optional arguments that can be used to add parameters to the method call. The signature is a D-BUS signature string, while args must be a sequence of python types that can be converted into the types specified by the signature. See the D-BUS specification for a reference on signature strings.

The flags no_reply and auto_start control the NO_REPLY_EXPECTED and NO_AUTO_START flags on the D-BUS message.

The return value is the result of the D-BUS method call. This will be a possibly empty sequence of values.

class DbusClient(message_handler=None, timeout=30)

A D-BUS client.

The message_handler argument specifies an optional message handler.

The optional timeout argument specifies a default timeout for protocol operations in seconds.

switchpoint connect(address='session')

Connect to address and wait until the connection is established.

The address argument must be a D-BUS server address, in the format described in the D-BUS specification. It may also be one of the special addresses 'session' or 'system', to connect to the D-BUS session and system bus, respectively.

protocol

Return the protocol, or None if not connected.

switchpoint call_method(service, path, interface, method, signature=None, args=None, no_reply=False, auto_start=False, timeout=-1)

A shorthand for self.protocol.call_method().

switchpoint get_unique_name()

A shorthand for self.protocol.get_unique_name().

switchpoint send_message(message)

A shorthand for self.protocol.send_message().

class DbusServer(message_handler, timeout=30)

A D-BUS server.

The message_handler argument specifies the message handler.

The optional timeout argument specifies a default timeout for protocol operations in seconds.

switchpoint listen(address='session')

Start listening on address for new connection.

The address argument must be a D-BUS server address, in the format described in the D-BUS specification. It may also be one of the special addresses 'session' or 'system', to connect to the D-BUS session and system bus, respectively.