2 Implements the public API for a D-Bus client. See the dbus.service module
3 to export objects or claim well-known names.
5 The first thing you need to do is connect dbus-python to a main loop
6 implementation. Currently, the only working implementation is (still)
7 to use pygobject and libdbus-glib::
9 from gobject import MainLoop, idle_add
10 from dbus.mainloop.glib import DBusGMainLoop
15 if __name__ == '__main__':
16 idle_add(main_function)
17 dbus_mainloop_wrapper = DBusGMainLoop(set_as_default=True)
21 In particular, receiving signals and making asynchronous method calls
22 can only work while the main loop is running.
24 Calling methods on remote objects
25 =================================
27 To access remote objects over the D-Bus you need to get a Bus object,
28 providing a connection to the bus daemon. You then obtain a remote
29 object proxy (ProxyObject) from the Bus, by providing the bus name
30 (either a well-known name or a unique name) and the object path.
32 Using the ProxyObject you can call methods in a fairly obvious
33 way, using the dbus_interface keyword argument to choose which interface's
34 method to call. You can also make an Interface object which wraps the
35 remote object, and call methods on that.
37 >>> from dbus import Bus, Interface
38 >>> bus = Bus(Bus.TYPE_SESSION)
40 >>> # the bus daemon itself provides a service, so use it
42 >>> bus_object = bus.get_object('org.freedesktop.DBus', '/org/freedesktop/DBus')
44 <ProxyObject wrapping <dbus.Bus on SESSION at 0x300843c0> org.freedesktop.DBus /org/freedesktop/DBus at 0x30302080>
45 >>> for x in bus_object.ListNames(dbus_interface='org.freedesktop.DBus'):
48 dbus.String(u'org.freedesktop.DBus')
49 dbus.String(u'org.freedesktop.Notifications')
51 dbus.String(u'org.gnome.ScreenSaver')
54 >>> # a different way to do the same thing
55 >>> bus_iface = Interface(bus_object, 'org.freedesktop.DBus')
56 >>> for x in bus_iface.ListNames():
59 dbus.String(u'org.freedesktop.DBus')
60 dbus.String(u'org.freedesktop.Notifications')
62 dbus.String(u'org.gnome.ScreenSaver')
66 >>> # use one of the other services on the session bus
68 >>> notify_object = bus.get_object('org.freedesktop.Notifications', '/org/freedesktop/Notifications')
69 >>> notify_iface = Interface(notify_object, 'org.freedesktop.Notifications')
70 >>> notify_iface.notify('a dbus-python script', 1, '', 'Hello, world', 'Hello from dbus-python', [], {}, 0)
72 >>> # objects can support multiple interfaces
74 >>> peer_iface = Interface(notify_object, 'org.freedesktop.DBus.Peer')
75 >>> # org.freedesktop.DBus.Peer.Ping is a "do-nothing" method
79 Asynchronous method calls
80 =========================
82 You can call methods asynchronously by passing the ``reply_handler``
83 and ``error_handler`` keyword arguments. The initial call immediately
84 returns `None`. The actual result will arrive when it becomes available,
85 as long as the main loop is running.
87 If the method succeeds, the ``reply_handler`` will be called with the
88 return values as arguments. If it fails or times out, the ``error_handler``
89 will be called with a `dbus.DBusException` instance as its argument.
94 To receive signals, get a `dbus.proxies.ProxyObject` or `dbus.Interface`
95 in the same way as above, and call its ``connect_to_signal`` method.
97 You can also connect to signals in a generic way using the
98 `Bus.add_signal_receiver` method.
100 Either way, a ``SignalMatch`` object is returned - this object has a
101 ``remove`` method which you can call to stop receiving that signal.
103 Receiving signals happens asynchronously, so it only works while the
104 main loop is running.
106 Obtaining a well-known name
107 ===========================
109 See `dbus.service.BusName`.
114 See `dbus.service.Object`.
119 :NewField SupportedUsage: Supported usage
120 :NewField Constructor: Constructor
123 # Copyright (C) 2003, 2004, 2005, 2006 Red Hat Inc. <http://www.redhat.com/>
124 # Copyright (C) 2003 David Zeuthen
125 # Copyright (C) 2004 Rob Taylor
126 # Copyright (C) 2005, 2006 Collabora Ltd. <http://www.collabora.co.uk/>
128 # Licensed under the Academic Free License version 2.1
130 # This program is free software; you can redistribute it and/or modify
131 # it under the terms of the GNU General Public License as published by
132 # the Free Software Foundation; either version 2 of the License, or
133 # (at your option) any later version.
135 # This program is distributed in the hope that it will be useful,
136 # but WITHOUT ANY WARRANTY; without even the implied warranty of
137 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
138 # GNU General Public License for more details.
140 # You should have received a copy of the GNU General Public License
141 # along with this program; if not, write to the Free Software
142 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
148 'Bus', 'SystemBus', 'SessionBus', 'StarterBus',
151 # from _dbus_bindings
152 'get_default_main_loop', 'set_default_main_loop',
154 'validate_interface_name', 'validate_member_name',
155 'validate_bus_name', 'validate_object_path',
156 'validate_error_name',
160 'ObjectPath', 'ByteArray', 'Signature', 'Byte', 'Boolean',
161 'Int16', 'UInt16', 'Int32', 'UInt32', 'Int64', 'UInt64',
162 'Double', 'String', 'Array', 'Struct', 'Dictionary', 'UTF8String',
165 'MissingErrorHandlerException', 'MissingReplyHandlerException',
166 'ValidationException', 'IntrospectionParserException',
167 'UnknownMethodException', 'NameExistsException',
170 'service', 'mainloop', 'lowlevel'
172 __docformat__
= 'restructuredtext'
175 from dbus
._version
import version
, __version__
179 # OLPC Sugar compatibility
180 import dbus
.exceptions
as exceptions
181 import dbus
.types
as types
183 from _dbus_bindings
import get_default_main_loop
, set_default_main_loop
,\
184 validate_interface_name
, validate_member_name
,\
185 validate_bus_name
, validate_object_path
,\
187 from _dbus_bindings
import DBusException
188 from dbus
.exceptions
import MissingErrorHandlerException
, \
189 MissingReplyHandlerException
, \
190 ValidationException
, \
191 IntrospectionParserException
, \
192 UnknownMethodException
, \
194 from _dbus_bindings
import ObjectPath
, ByteArray
, Signature
, Byte
, Boolean
,\
195 Int16
, UInt16
, Int32
, UInt32
, Int64
, UInt64
,\
196 Double
, String
, Array
, Struct
, Dictionary
, \
198 from dbus
._dbus
import Bus
, SystemBus
, SessionBus
, StarterBus
, Interface
201 if 'DBUS_PYTHON_NO_DEPRECATED' not in os
.environ
:
202 from dbus
._dbus
import dbus_bindings
# for backwards compat