Add Makefile target maintainer-update-website to update d.fd.o/doc/dbus-python
[dbus-python-phuang.git] / dbus / __init__.py
blob81246dc4029c79ef7c2208bb18753ecd72cd1ded
1 """\
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
12 def main_function():
13 "your code here"
15 if __name__ == '__main__':
16 idle_add(main_function)
17 dbus_mainloop_wrapper = DBusGMainLoop(set_as_default=True)
18 mainloop = MainLoop()
19 mainloop.run()
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)
39 >>> #
40 >>> # the bus daemon itself provides a service, so use it
41 >>> #
42 >>> bus_object = bus.get_object('org.freedesktop.DBus', '/org/freedesktop/DBus')
43 >>> bus_object
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'):
46 ... print repr(x)
47 ...
48 dbus.String(u'org.freedesktop.DBus')
49 dbus.String(u'org.freedesktop.Notifications')
50 dbus.String(u':1.0')
51 dbus.String(u'org.gnome.ScreenSaver')
52 dbus.String(u':1.1')
53 dbus.String(u':1.2')
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():
57 ... print repr(x)
58 ...
59 dbus.String(u'org.freedesktop.DBus')
60 dbus.String(u'org.freedesktop.Notifications')
61 dbus.String(u':1.0')
62 dbus.String(u'org.gnome.ScreenSaver')
63 dbus.String(u':1.1')
64 dbus.String(u':1.2')
65 >>> #
66 >>> # use one of the other services on the session bus
67 >>> #
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)
71 >>> #
72 >>> # objects can support multiple interfaces
73 >>> #
74 >>> peer_iface = Interface(notify_object, 'org.freedesktop.DBus.Peer')
75 >>> # org.freedesktop.DBus.Peer.Ping is a "do-nothing" method
76 >>> peer_iface.Ping()
77 >>>
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.
91 Receiving signals
92 =================
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`.
111 Exporting objects
112 =================
114 See `dbus.service.Object`.
117 for epydoc's benefit
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 # This program is free software; you can redistribute it and/or modify
133 # it under the terms of the GNU General Public License as published by
134 # the Free Software Foundation; either version 2 of the License, or
135 # (at your option) any later version.
137 # This program is distributed in the hope that it will be useful,
138 # but WITHOUT ANY WARRANTY; without even the implied warranty of
139 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
140 # GNU General Public License for more details.
142 # You should have received a copy of the GNU General Public License
143 # along with this program; if not, write to the Free Software
144 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
146 import os
148 __all__ = (
149 # from _dbus
150 'Bus', 'SystemBus', 'SessionBus', 'StarterBus',
151 'Interface',
153 # from _dbus_bindings
154 'get_default_main_loop', 'set_default_main_loop',
156 'validate_interface_name', 'validate_member_name',
157 'validate_bus_name', 'validate_object_path',
158 'validate_error_name',
160 'DBusException',
162 'ObjectPath', 'ByteArray', 'Signature', 'Byte', 'Boolean',
163 'Int16', 'UInt16', 'Int32', 'UInt32', 'Int64', 'UInt64',
164 'Double', 'String', 'Array', 'Struct', 'Dictionary', 'UTF8String',
166 # from exceptions
167 'MissingErrorHandlerException', 'MissingReplyHandlerException',
168 'ValidationException', 'IntrospectionParserException',
169 'UnknownMethodException', 'NameExistsException',
171 # submodules
172 'service', 'mainloop', 'lowlevel'
174 __docformat__ = 'restructuredtext'
176 try:
177 from dbus._version import version, __version__
178 except ImportError:
179 pass
181 # OLPC Sugar compatibility
182 import dbus.exceptions as exceptions
183 import dbus.types as types
185 from _dbus_bindings import get_default_main_loop, set_default_main_loop,\
186 validate_interface_name, validate_member_name,\
187 validate_bus_name, validate_object_path,\
188 validate_error_name
189 from _dbus_bindings import DBusException
190 from dbus.exceptions import MissingErrorHandlerException, \
191 MissingReplyHandlerException, \
192 ValidationException, \
193 IntrospectionParserException, \
194 UnknownMethodException, \
195 NameExistsException
196 from _dbus_bindings import ObjectPath, ByteArray, Signature, Byte, Boolean,\
197 Int16, UInt16, Int32, UInt32, Int64, UInt64,\
198 Double, String, Array, Struct, Dictionary, \
199 UTF8String
200 from dbus._dbus import Bus, SystemBus, SessionBus, StarterBus, Interface
203 if 'DBUS_PYTHON_NO_DEPRECATED' not in os.environ:
204 from dbus._dbus import dbus_bindings # for backwards compat