Introduction
Tx DBus is a native-python implementation of the DBus protocol on top of the Twisted networking engine. The purpose of this tutorial is to provide an introduction to the use of Tx DBus and demonstrate the main APIs necessary to successfully incorproate it within Twisted applications.
This tutorial assumes a basic understanding of both Twisted and DBus. The Twisted project provides excellent documentation for quickly getting up to speed with the framework. As for DBus, several good resources are available:
-
DBus Overview (part of this project)
Inline Callbacks
This tutorial leverages the defer.inlineCallbacks function decorator in
an attempt to improve readability of the example code. As inline callbacks
are not well described in the Twisted documentation, this section provides
a quick overview of the feature.
Inline callbacks is an alternative callback mechanism that may be used in Twisted applications running on Python 2.5+. They assist in writing Deferred-using code that looks similar to a regular, sequential function. Through the magic of Python’s generator mechanism, this sequential-looking code is, in fact, fully asynchronous and functionally equivalent to the traditional Deferred plus explicit callbacks and errbacks mechanism. Although the inline callbacks mechanism is not quite as flexible as explicit callbacks and errbacks, it often results in simpler and more compact code.
Aside from the use of the defer.inlineCallbacks function decorator, the key
to inline callbacks is to yield all deferreds. This will pause the generator
function at the point of the yield until the asynchronous operation
completes. On completion, the generator will be resumed and the result of the
operator will be returned from the yield statement. Alternatively, if the
operation resulted in an exception, the exception will be re-thrown from the
yield statement.
The return value of functions decorated with defer.inlineCallbacks is a
deferred. Due to the nature of generator functions, inline callbacks methods
cannot use the traditional return keyword to return the result of the
asynchronous operation. Instead, they must use defer.returnValue() to
return the result. If defer.returnValue() is not used, the deferred
returned by the decorated function will result in None
from twisted.internet import defer, utils
@defer.inlineCallbacks
def checkIPUsage( ip_addr ):
ip_txt = yield utils.getProcessOutput('/sbin/ip', ['addr', 'list'])
if ip_addr in ip_txt:
# True will become the result of the Deferred
defer.returnValue( True )
else:
# Will trigger an errback
raise Exception('IP NOT FOUND')
Quick Real-World Example for the Impatient
The following example displays a notification popup on the desktop via the
the org.freedesktop.Notifications DBus API
#!/usr/bin/env python
from twisted.internet import reactor, defer
from txdbus import error, client
@defer.inlineCallbacks
def show_desktop_notification( duration, message ):
'''
Shows the message as a desktop nofification for the specified
number of seconds
'''
con = yield client.connect(reactor, 'session')
notifier = yield con.getRemoteObject('org.freedesktop.Notifications',
'/org/freedesktop/Notifications')
nid = yield notifier.callRemote('Notify',
'Example Application', 0,
'',
'Example Notification Summary',
message,
[], dict(),
duration * 1000)
def main():
d = show_desktop_notification( 5, "Hello World!" )
d.addCallback( lambda _: reactor.stop() )
reactor.callWhenRunning(main)
reactor.run()
DBus Connections
In order to make any use of DBus, a connection to the bus must first be
established. This is accomplished through the txdbus.client.connect(reactor,
busAddress="session") method which returns a Deferred to a
txdbus.client.DBusClientConnection instance. The busAddress parameter
supports two special-case addresses in addition to the standard server
addresses as defined by the DBus specification. If session (the default) or
system is passed, the client will attempt to connect to the local session or
system busses, respectively. For typical usage, these special-case addresses
will likely suffice.
Tx DBus currently supports the unix, tcp, and nonce-tcp connection
types.
from twisted.internet import reactor
from txdbus import client
def onConnected(cli):
print 'Connected to the session bus!'
dconnect = client.connect(reactor)
dconnect.addCallback(onConnected)
reactor.run()
DBus Clients
Tx DBus provides two APIs for interacting with remote objects. The generally preferred and significantly easier to use mechanism involves creating local proxies to represent remote objects. Signal registration and remote method invocation is then done by way of the proxy instances which hide most of the low-level details. Alternatively, low-level APIs exist for direct remote method invocation and message matching registration. Although generally much less convenient, the low-level APIs provide full access to the DBus internals.
As with most dynamic language bindings, Tx DBus will automatically use the DBus introspection mechanism to obtain interface definitions for remote objects if they are not explicitly provided. While introspection is certainly a convenient mechanism and appropriate for many use cases, there are some advantages to explicitly specifying the interfaces. The primary benefit is that it allows for signal registration and local proxy object creation irrespective of whether or not the target bus name is currently in use.
Remote Methods
As there is a delay involved in remote method invocation, remote calls always result in a Deferred instance. When the results eventually become available, the deferred will be callbacked/errbacked with the returned value. The format of the return value depends on the interface specification for the remote method.
If the interface does not specify any return values, the return value will be
None. If only one value is returned (structures and arrays are considered
single values), that value will be returned as the result. Otherwise, if
multiple values are returned, the result will be a Python list containing the
returned values in the order specified by the DBus signature.
There are two mechanisms for invoking remote methods. The easier of the two is to invoke the remote method through a local proxy object. This has the advantage of hiding many of the low-level DBus details and provides a simpler interface. Alternatively, the methods may be invoked directly without the use of proxy objects. In this case, however, all required parameters for the method invocation must be specified manually.
Both mechanisms use a function called callRemote() to effect the remote
method invocation. The low-level callRemote() is provided by the
txdbus.client.DBusClientConnection class and requires a large number of
arguments. The proxy object’s callRemote() method wraps the low-level method
and hides most of the details. In addition to accepting the name of the method
to invoke and a list of positional arguments, both interfaces also accept the
following optional keyword arguments that may be used to augment the remote
method invocation.
| Keyword | Description |
|---|---|
|
By default, the returned Deferred will callback/errback when
the result of the remote invocation becomes available. If this parameter
is set to |
|
If set to |
|
If specified, the returned Deferred will be errbacked with a |
|
If specified, the remote call will invoke the method on the named interface. If left unspecified and more than one interface provides a method with the same name it is "implementation" defined as to which will be invoked. |
Proxy Objects
Remote DBus objects are generally interacted with by way of local proxy objects. The following example demonstrates the creation of a proxy object and a remote method invocation.
from twisted.internet import reactor, defer
from txdbus import client, error
@defer.inlineCallbacks
def main():
try:
cli = yield client.connect(reactor)
robj = yield cli.getRemoteObject( 'org.example', '/MyObjPath' )
yield robj.callRemote('Ping')
print 'Ping Succeeded. org.example is available'
except error.DBusException, e:
print 'Ping Failed. org.example is not available'
reactor.stop()
reactor.callWhenRunning(main)
reactor.run()
The local proxy object uses the remote object’s interface definition to provide
a local representation of the remote object’s API. As no explicit interface
description was provided in the getRemoteObject() call, the interfaces must be
introspected prior to creation of the local proxy object.
Remote method invocation on proxy objects is done through their callRemote()
method. The first argument is the name of the method to be invoked and the
subsequent positional arguments are the arguments to be passed to the remote
method. The optional keyword arguments described in the Remote Methods section may be used to augment the call as desired.
Low Level Method Invocation
In addition to method invocation through proxy objects, the
txdbus.client.DBusClientConnection class provides a low-level callRemote()
function that may be used to directly invoke remote methods. However, all
parameters typically hidden by the proxy objects such as signature strings,
destination bus addresses, and the like must be explicitly specified. As with
the proxy object’s callRemote(), this method also accepts the optional
keyword arguments listed in the Remote Methods section.
The following example is equivalent to the previous one but uses the low-level
API to invoke the Ping method without the use of a proxy object.
from twisted.internet import reactor, defer
from txdbus import client, error
@defer.inlineCallbacks
def main():
try:
cli = yield client.connect(reactor)
yield cli.callRemote( '/AnyValidObjPath', 'Ping',
interface = 'org.freedesktop.DBus.Peer',
destination = 'org.example' )
print 'Ping Succeeded. org.example is available'
except error.DBusException, e:
print 'Ping Failed. org.example is not available'
reactor.stop()
reactor.callWhenRunning(main)
reactor.run()
|
Note
|
The Ping function is used here because it’s a standard interface that’s
guaranteed to exist. However, it’s worth mentioning that Ping is handled
specially and can be somewhat misleading. Although it would appear the remote
object referred to by the object path is the target of the Ping function, it
is in fact just the bus name that is being pinged. The object path is
ignored. Consequently, this function cannot be used to test for the
availability of a specific object. |
Explicit Interface Specification
The following example extends the previous two by demonstrating explicit interface specification for a remote object.
from twisted.internet import reactor, defer
from txdbus import client, error
from txdbus.interface import DBusInterface, Method
peer_iface = DBusInterface( 'org.freedesktop.DBus.Peer',
Method('Ping')
)
@defer.inlineCallbacks
def main():
try:
cli = yield client.connect(reactor)
robj = yield cli.getRemoteObject( 'org.example', '/MyObjPath', peer_iface )
yield robj.callRemote('Ping')
print 'Ping Succeeded. org.example is available'
except error.DBusException, e:
print 'Ping Failed. org.example is not available'
reactor.stop()
reactor.callWhenRunning(main)
reactor.run()
Of course, the org.freedesktop.DBus.Peer interface is rather simplistic. To
better demonstrate DBus interface definition, consider the following code
from txdbus.interface import DBusInterface, Method, Signal
# Method( method_name, arguments='', returns='')
# Signal( signal_name, arguments='' )
#
# The arguments and returns parameters must be empty strings for
# no arguments/return values or a valid DBus signature string
#
iface = DBusInterface( 'org.example',
Method('simple'),
Method('full', 's', 'i'),
Method('retOnly', returns='s'),
Method('argOnly', 's'),
Signal('noDataSignal'),
Signal('DataSignal', 'as') )
Exporting Objects Over DBus
In order to export an object over DBus, it must support the
txdbus.objects.IDBusObject interface. While this interface may be directly
supported by applications, it will typically be easier to derive from the
default implementation provided by the txdbus.objects.DBusObject class. The
easiest way to explain its use is by way of example. The following code
demonstrates a simple object exported over DBus.
from twisted.internet import reactor, defer
from txdbus import client, objects, error
from txdbus.interface import DBusInterface, Method
class MyObj (objects.DBusObject):
iface = DBusInterface('org.example.MyIFace',
Method('exampleMethod', arguments='s', returns='s' ))
dbusInterfaces = [iface]
def __init__(self, objectPath):
super(MyObj, self).__init__(objectPath)
def dbus_exampleMethod(self, arg):
print 'Received remote call. Argument: ', arg
return 'You sent (%s)' % arg
@defer.inlineCallbacks
def main():
try:
conn = yield client.connect(reactor)
conn.exportObject( MyObj('/MyObjPath') )
yield conn.requestBusName('org.example')
print 'Object exported on bus name "org.example" with path /MyObjPath'
except error.DBusException, e:
print 'Failed to export object: ', e
reactor.stop()
reactor.callWhenRunning( main )
reactor.run()
This example demonstrates several key issues for subclasses of DBusObject.
The DBus interfaces supported by an object are declared by way of a class-level
variable named dbusInterfaces. This variable contains a list of
DBusInterface instances which define an interface’s API. When class
inheritance is used, the dbusInterfaces variables of all superclasses are
conjoined to determine the full set of APIs supported by the object.
Supporting the methods declared in the DBus interfaces is as simple as creating
methods named dbus_<DBusMethodName>. These methods may return Deferreds to
the final results if those results are not immediately available.
The following code demonstrates the use of the exported object.
from twisted.internet import reactor, defer
from txdbus import client, error
@defer.inlineCallbacks
def main():
try:
cli = yield client.connect(reactor)
robj = yield cli.getRemoteObject( 'org.example', '/MyObjPath' )
reply = yield robj.callRemote('exampleMethod', 'Hello World!')
print 'Reply from server: ', reply
except error.DBusException, e:
print 'DBus Error:', e
reactor.stop()
reactor.callWhenRunning(main)
reactor.run()
DBus Properties
Tx DBus supports DBus Properties through the
txdbus.objects.DBusProperty class. This class leverages Python’s
descriptor capabilities to provide near-transparent support for
DBus Properties.
If the Property in the DBusInterface class set emitsOnChanged to
True, an org.freedesktop.DBus.Properties.PropertiesChanged signal
will be generated each time the value is assigned to (defaults to True).
from twisted.internet import reactor, defer
from txdbus import client, objects, error
from txdbus.interface import DBusInterface, Property
from txdbus.objects import DBusProperty
class MyObj (objects.DBusObject):
iface = DBusInterface('org.example.MyIFace',
Property('foo', 's', writeable=True))
dbusInterfaces = [iface]
foo = DBusProperty('foo')
def __init__(self, objectPath):
super(MyObj, self).__init__(objectPath)
self.foo = 'bar'
@defer.inlineCallbacks
def main():
try:
conn = yield client.connect(reactor)
conn.exportObject( MyObj('/MyObjPath') )
yield conn.requestBusName('org.example')
print 'Object exported on bus name "org.example" with path /MyObjPath'
except error.DBusException, e:
print 'Failed to export object: ', e
reactor.stop()
reactor.callWhenRunning( main )
reactor.run()
Client-side property use:
from twisted.internet import reactor, defer
from txdbus import client, error
@defer.inlineCallbacks
def main():
try:
cli = yield client.connect(reactor)
robj = yield cli.getRemoteObject( 'org.example', '/MyObjPath' )
# Use the standard org.freedesktop.DBus.Properties.Get function to
# obtain the value of 'foo'. Only one interface on the remote object
# declares 'foo' so the interface name (the second function argument)
# may be omitted.
foo = yield robj.callRemote('Get', '', 'foo')
# prints "bar"
print foo
yield robj.callRemote('Set', '', 'foo', 'baz')
foo = yield robj.callRemote('Get', '', 'foo')
# prints "baz"
print foo
except error.DBusException, e:
print 'DBus Error:', e
reactor.stop()
reactor.callWhenRunning(main)
reactor.run()
Caller Identity
The identity of the calling DBus connection can be reliably determined
in DBus. Methods wishing to know the identity of the connection invoking
them may add a dbusCaller=None key-word argument. Methods supporting
this argument will be supplied with the unique bus name of the calling
connection.
def dbus_identityExample(dbusCaller=None):
print 'Calling connection: ', dbusCaller
Although the unique bus name of the caller is often not very useful
in and of itself it can be reliably converted into a Unix user id
with the getConnectionUnixUser() method of
txdbus.client.DBusClientConnection:
def dbus_identityExample(dbusCaller=None):
d = self.getConnection().getConnectionUnixUser( dbusCaller )
d.addCallback( lambda uid : 'Your Unix User Id is: %d' % uid )
return d
Resolving Conflicting Interface Declarations
Mapping DBus method calls to methods named dbus_<DBusMethodName> is generally
a convenient mechanism. However, it can result in confusion when multiple
supported interfaces define methods with the same name. To resolve this
situation, the dbusMethod() decorator may be used to explicitly bind a method
to the desired interface.
from twisted.internet import reactor, defer
from txdbus import client, objects, error
from txdbus.interface import DBusInterface, Method
from txdbus.objects import dbusMethod
class MyObj (objects.DBusObject):
iface1 = DBusInterface('org.example.MyIFace1',
Method('common'))
iface2 = DBusInterface('org.example.MyIFace2',
Method('common'))
dbusInterfaces = [iface1, iface2]
def __init__(self, objectPath):
super(MyObj, self).__init__(objectPath)
@dbusMethod('org.example.MyIFace1', 'common')
def dbus_common1(self):
print 'iface1 common called!'
@dbusMethod('org.example.MyIFace2', 'common')
def dbus_common2(self):
print 'iface2 common called!'
@defer.inlineCallbacks
def main():
try:
conn = yield client.connect(reactor)
conn.exportObject( MyObj('/MultiInterfaceObject') )
yield conn.requestBusName('org.example')
print 'Object exported on bus name "org.example" with path /MultiInterfaceObject'
except error.DBusException, e:
print 'Failed to export object: ', e
reactor.stop()
reactor.callWhenRunning( main )
reactor.run()
Similarly, action must be taken on the client side to ensure that the
appropriate function is executed when multiple interfaces support methods of
the same name. The interface key-word argument to the callRemote() function
may be used to identify the desired interface. If the interfaces argument is
not used in this situation, it is "implementation defined" as to which
interface’s method will be invoked.
from twisted.internet import reactor, defer
from txdbus import client, error
@defer.inlineCallbacks
def main():
try:
cli = yield client.connect(reactor)
robj = yield cli.getRemoteObject( 'org.example', '/MultiInterfaceObject' )
yield robj.callRemote('common', interface='org.example.MyIFace1')
yield robj.callRemote('common', interface='org.example.MyIFace2')
except error.DBusException, e:
print 'DBus Error:', e
reactor.stop()
reactor.callWhenRunning(main)
reactor.run()
Signals
Signals are emitted by subclasses of DBusObject using the emitSignal() method
from twisted.internet import reactor, defer
from txdbus import client, objects, error
from txdbus.interface import DBusInterface, Signal
class SignalSender (objects.DBusObject):
iface = DBusInterface( 'org.example.SignalSender',
Signal('tick', 'u')
)
dbusInterfaces = [iface]
def __init__(self, objectPath):
super(SignalSender, self).__init__(objectPath)
self.count = 0
def sendTick(self):
self.emitSignal('tick', self.count)
self.count += 1
reactor.callLater(1, self.sendTick)
@defer.inlineCallbacks
def main():
try:
conn = yield client.connect(reactor)
s = SignalSender('/Signaller')
conn.exportObject( s )
yield conn.requestBusName('org.example')
print 'Object exported on bus name "org.example" with path /Signaller'
print 'Emitting "tick" signals every second'
s.sendTick() # begin looping
except error.DBusException, e:
print 'Failed to export object: ', e
reactor.stop()
reactor.callWhenRunning( main )
reactor.run()
The corresponding client code to receive the emitted signals is:
from twisted.internet import reactor, defer
from txdbus import client, error
def onSignal( tickCount ):
print 'Got tick signal: ', tickCount
@defer.inlineCallbacks
def main():
try:
cli = yield client.connect(reactor)
robj = yield cli.getRemoteObject( 'org.example', '/Signaller' )
robj.notifyOnSignal( 'tick', onSignal )
except error.DBusException, e:
print 'DBus Error:', e
reactor.callWhenRunning(main)
reactor.run()
Note that this client code uses introspection to obtain the API of the
remote object emitting the signals. Consequently, the server application must
be up and running when the client application starts or an error will be thrown
from getRemoteObject() when the introspection fails. Were the interface
specified explicitly, the signal registration would succeed even if the
emitting application were entirely disconnected from the bus. The following
code can be run at any time and, if launched before the signal-emitting
application, it will never miss any messages.
from twisted.internet import reactor, defer
from txdbus import client, error
from txdbus.interface import DBusInterface, Signal
signal_iface = DBusInterface( 'org.example.SignalSender',
Signal('tick', 'u')
)
def onSignal( tickCount ):
print 'Got tick signal: ', tickCount
@defer.inlineCallbacks
def main():
try:
cli = yield client.connect(reactor)
robj = yield cli.getRemoteObject( 'org.example', '/Signaller', signal_iface )
robj.notifyOnSignal( 'tick', onSignal )
except error.DBusException, e:
print 'DBus Error:', e
reactor.callWhenRunning(main)
reactor.run()
DBus Structure Handling and Object Serialization
When calling methods that accept structures as arguments, such as
(si) (a structure containing a string and 32-bit signed integer)
the argument passed to the callRemote() method should be 2-element
list containing the desired string and integer
# -- Server Snippet --
...
Method('structArg', '(si)', 's')
...
def dbus_structArg(self, arg):
return 'You sent (%s, %d)' % (arg[0], arg[1])
# -- Client Snippet --
remoteObj.callRemote('structArg', ['Foobar', 1])
It is also possible to pass Python objects instead of lists to arguments
requiring a structure type. If the object contains a dbusOrder member
variable, it will be used as an ordered list of attribute names by the
serialization process. For example, the client portion of the previous code
snippet could be equivalently written as
class DBSerializeable(object):
dbusOrder = ['text', 'number']
def __init__(self, txt, num):
self.text = txt
self.number = num
serialObj = DBSerializeable( 'Foobar', 1 )
remoteObj.callRemote('structArg', serialObj)
Error Handling
DBus reports errors with dedicated error messages. Some of these messages are generated by the bus itself, such as when a remote method call is sent to bus name that does not exist, others are generated within client applications, such as when invalid argument values are detected.
Any exception raised during the invocation of a dbus_* method will be
converted into a proper DBus error message. The name of the DBus error message
will default to org.txdbus.PythonException.<CLASS_NAME>. If the
exception object has a dbusErrorName member variable, that value will be used
instead. All error messages sent by this implementation include a single string
parameter that is obtained by converting the exception instance to a string.
from twisted.internet import reactor, defer
from txdbus import client, objects, error
from txdbus.interface import DBusInterface, Method
class ExampleException (Exception):
dbusErrorName = 'org.example.ExampleException'
class ErrObj (objects.DBusObject):
iface = DBusInterface('org.example.ErrorExample',
Method('throwError'))
dbusInterfaces = [iface]
def __init__(self, objectPath):
super(ErrObj, self).__init__(objectPath)
def dbus_throwError(self):
raise ExampleException('Uh oh')
@defer.inlineCallbacks
def main():
try:
conn = yield client.connect(reactor)
conn.exportObject( ErrObj('/ErrorObject') )
yield conn.requestBusName('org.example')
print 'Object exported on bus name "org.example" with path /ErrorObject'
except error.DBusException, e:
print 'Failed to export object: ', e
reactor.stop()
reactor.callWhenRunning( main )
reactor.run()
Failures occuring during remote method invocation are reported to the calling
code as instances of txdbus.error.RemoteError. Instances of this object have
two fields errName which is the textual name of the DBus error and an
optional message. DBus does not formally define the content of error
messages. However, if the DBus error message contains a single string parameter
(which is often the case in practice), it will be assigned to the message
field of the RemoteError instance.
from twisted.internet import reactor, defer
from txdbus import client, error
@defer.inlineCallbacks
def main():
try:
cli = yield client.connect(reactor)
robj = yield cli.getRemoteObject( 'org.example', '/ErrorObject' )
try:
yield robj.callRemote('throwError')
print 'Not Reached'
except error.RemoteError, e:
print 'Client threw an error named: ', e.errName
print 'Error message: ', e.message
except error.DBusException, e:
print 'DBus Error:', e
reactor.stop()
reactor.callWhenRunning(main)
reactor.run()