dbus/__init__.py

   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.
   4
   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::
   8
   9     from gobject import MainLoop, idle_add
  10     from dbus.mainloop.glib import DBusGMainLoop
  11
  12     def main_function():
  13         "your code here"
  14
  15     if __name__ == '__main__':
  16         idle_add(main_function)
  17         dbus_mainloop_wrapper = DBusGMainLoop(set_as_default=True)
  18         mainloop = MainLoop()
  19         mainloop.run()
  20
  21 In particular, receiving signals and making asynchronous method calls
  22 can only work while the main loop is running.
  23
  24 Calling methods on remote objects
  25 =================================
  26
  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.
  31
  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.
  36
  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 >>>
  78
  79 Asynchronous method calls
  80 =========================
  81
  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.
  86
  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.
  90
  91 Receiving signals
  92 =================
  93
  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.
  96
  97 You can also connect to signals in a generic way using the
  98 `Bus.add_signal_receiver` method.
  99
 100 Either way, a ``SignalMatch`` object is returned - this object has a
 101 ``remove`` method which you can call to stop receiving that signal.
 102
 103 Receiving signals happens asynchronously, so it only works while the
 104 main loop is running.
 105
 106 Obtaining a well-known name
 107 ===========================
 108
 109 See `dbus.service.BusName`.
 110
 111 Exporting objects
 112 =================
 113
 114 See `dbus.service.Object`.
 115
 116 ..
 117   for epydoc's benefit
 118
 119 :NewField SupportedUsage: Supported usage
 120 :NewField Constructor: Constructor
 121 """
 122
 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/>
 127 #
 128 # Licensed under the Academic Free License version 2.1
 129 #
 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.
 136 #
 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.
 141 #
 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
 145
 146 import os
 147
 148 __all__ = (
 149            # from _dbus
 150            'Bus', 'SystemBus', 'SessionBus', 'StarterBus',
 151            'Interface',
 152
 153            # from _dbus_bindings
 154            'get_default_main_loop', 'set_default_main_loop',
 155
 156            'validate_interface_name', 'validate_member_name',
 157            'validate_bus_name', 'validate_object_path',
 158            'validate_error_name',
 159
 160            'DBusException',
 161
 162            'ObjectPath', 'ByteArray', 'Signature', 'Byte', 'Boolean',
 163            'Int16', 'UInt16', 'Int32', 'UInt32', 'Int64', 'UInt64',
 164            'Double', 'String', 'Array', 'Struct', 'Dictionary', 'UTF8String',
 165
 166            # from exceptions
 167            'MissingErrorHandlerException', 'MissingReplyHandlerException',
 168            'ValidationException', 'IntrospectionParserException',
 169            'UnknownMethodException', 'NameExistsException',
 170
 171            # submodules
 172            'service', 'mainloop', 'lowlevel'
 173            )
 174 __docformat__ = 'restructuredtext'
 175
 176 try:
 177     from dbus._version import version, __version__
 178 except ImportError:
 179     pass
 180
 181 # OLPC Sugar compatibility
 182 import dbus.exceptions as exceptions
 183 import dbus.types as types
 184
 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
 201
 202
 203 if 'DBUS_PYTHON_NO_DEPRECATED' not in os.environ:
 204     from dbus._dbus import dbus_bindings    # for backwards compat