dbus/decorators.py

   1 """Service-side D-Bus decorators."""
   2
   3 # Copyright (C) 2003, 2004, 2005, 2006 Red Hat Inc. <http://www.redhat.com/>
   4 # Copyright (C) 2003 David Zeuthen
   5 # Copyright (C) 2004 Rob Taylor
   6 # Copyright (C) 2005, 2006 Collabora Ltd. <http://www.collabora.co.uk/>
   7 #
   8 # Licensed under the Academic Free License version 2.1
   9 #
  10 # This program is free software; you can redistribute it and/or modify
  11 # it under the terms of the GNU General Public License as published by
  12 # the Free Software Foundation; either version 2 of the License, or
  13 # (at your option) any later version.
  14 #
  15 # This program is distributed in the hope that it will be useful,
  16 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 # GNU General Public License for more details.
  19 #
  20 # You should have received a copy of the GNU General Public License
  21 # along with this program; if not, write to the Free Software
  22 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  23
  24 __all__ = ('method', 'signal')
  25 __docformat__ = 'restructuredtext'
  26
  27 import inspect
  28
  29 import _dbus_bindings
  30
  31 from dbus.exceptions import DBusException
  32
  33
  34 def method(dbus_interface, in_signature=None, out_signature=None,
  35         async_callbacks=None,
  36         sender_keyword=None, path_keyword=None, destination_keyword=None,
  37         message_keyword=None, connection_keyword=None,
  38         utf8_strings=False, byte_arrays=False):
  39     """Factory for decorators used to mark methods of a `dbus.service.Object`
  40     to be exported on the D-Bus.
  41
  42     The decorated method will be exported over D-Bus as the method of the
  43     same name on the given D-Bus interface.
  44
  45     :Parameters:
  46         `dbus_interface` : str
  47             Name of a D-Bus interface
  48         `in_signature` : str or None
  49             If not None, the signature of the method parameters in the usual
  50             D-Bus notation
  51         `out_signature` : str or None
  52             If not None, the signature of the return value in the usual
  53             D-Bus notation
  54         `async_callbacks` : tuple containing (str,str), or None
  55             If None (default) the decorated method is expected to return
  56             values matching the `out_signature` as usual, or raise
  57             an exception on error. If not None, the following applies:
  58
  59             `async_callbacks` contains the names of two keyword arguments to
  60             the decorated function, which will be used to provide a success
  61             callback and an error callback (in that order).
  62
  63             When the decorated method is called via the D-Bus, its normal
  64             return value will be ignored; instead, a pair of callbacks are
  65             passed as keyword arguments, and the decorated method is
  66             expected to arrange for one of them to be called.
  67
  68             On success the success callback must be called, passing the
  69             results of this method as positional parameters in the format
  70             given by the `out_signature`.
  71
  72             On error the decorated method may either raise an exception
  73             before it returns, or arrange for the error callback to be
  74             called with an Exception instance as parameter.
  75
  76         `sender_keyword` : str or None
  77             If not None, contains the name of a keyword argument to the
  78             decorated function, conventionally ``'sender'``. When the
  79             method is called, the sender's unique name will be passed as
  80             this keyword argument.
  81
  82         `path_keyword` : str or None
  83             If not None (the default), the decorated method will receive
  84             the destination object path as a keyword argument with this
  85             name. Normally you already know the object path, but in the
  86             case of "fallback paths" you'll usually want to use the object
  87             path in the method's implementation.
  88
  89         `destination_keyword` : str or None
  90             If not None (the default), the decorated method will receive
  91             the destination bus name as a keyword argument with this name.
  92             Included for completeness - you shouldn't need this.
  93
  94         `message_keyword` : str or None
  95             If not None (the default), the decorated method will receive
  96             the `dbus.lowlevel.MethodCallMessage` as a keyword argument
  97             with this name.
  98
  99         `connection_keyword` : str or None
 100             If not None (the default), the decorated method will receive
 101             the `dbus.connection.Connection` as a keyword argument
 102             with this name. This is generally only useful for objects
 103             that are available on more than one connection.
 104
 105         `utf8_strings` : bool
 106             If False (default), D-Bus strings are passed to the decorated
 107             method as objects of class dbus.String, a unicode subclass.
 108
 109             If True, D-Bus strings are passed to the decorated method
 110             as objects of class dbus.UTF8String, a str subclass guaranteed
 111             to be encoded in UTF-8.
 112
 113             This option does not affect object-paths and signatures, which
 114             are always 8-bit strings (str subclass) encoded in ASCII.
 115
 116         `byte_arrays` : bool
 117             If False (default), a byte array will be passed to the decorated
 118             method as an `Array` (a list subclass) of `Byte` objects.
 119
 120             If True, a byte array will be passed to the decorated method as
 121             a `ByteArray`, a str subclass. This is usually what you want,
 122             but is switched off by default to keep dbus-python's API
 123             consistent.
 124     """
 125     _dbus_bindings.validate_interface_name(dbus_interface)
 126
 127     def decorator(func):
 128         args = inspect.getargspec(func)[0]
 129         args.pop(0)
 130
 131         if async_callbacks:
 132             if type(async_callbacks) != tuple:
 133                 raise TypeError('async_callbacks must be a tuple of (keyword for return callback, keyword for error callback)')
 134             if len(async_callbacks) != 2:
 135                 raise ValueError('async_callbacks must be a tuple of (keyword for return callback, keyword for error callback)')
 136             args.remove(async_callbacks[0])
 137             args.remove(async_callbacks[1])
 138
 139         if sender_keyword:
 140             args.remove(sender_keyword)
 141         if path_keyword:
 142             args.remove(path_keyword)
 143         if destination_keyword:
 144             args.remove(destination_keyword)
 145         if message_keyword:
 146             args.remove(message_keyword)
 147         if connection_keyword:
 148             args.remove(connection_keyword)
 149
 150         if in_signature:
 151             in_sig = tuple(_dbus_bindings.Signature(in_signature))
 152
 153             if len(in_sig) > len(args):
 154                 raise ValueError, 'input signature is longer than the number of arguments taken'
 155             elif len(in_sig) < len(args):
 156                 raise ValueError, 'input signature is shorter than the number of arguments taken'
 157
 158         func._dbus_is_method = True
 159         func._dbus_async_callbacks = async_callbacks
 160         func._dbus_interface = dbus_interface
 161         func._dbus_in_signature = in_signature
 162         func._dbus_out_signature = out_signature
 163         func._dbus_sender_keyword = sender_keyword
 164         func._dbus_path_keyword = path_keyword
 165         func._dbus_destination_keyword = destination_keyword
 166         func._dbus_message_keyword = message_keyword
 167         func._dbus_connection_keyword = connection_keyword
 168         func._dbus_args = args
 169         func._dbus_get_args_options = {'byte_arrays': byte_arrays,
 170                                        'utf8_strings': utf8_strings}
 171         return func
 172
 173     return decorator
 174
 175
 176 def signal(dbus_interface, signature=None, path_keyword=None,
 177            connection_keyword=None):
 178     """Factory for decorators used to mark methods of a `dbus.service.Object`
 179     to emit signals on the D-Bus.
 180
 181     Whenever the decorated method is called in Python, after the method
 182     body is executed, a signal with the same name as the decorated method,
 183     with the given D-Bus interface, will be emitted from this object.
 184
 185     :Parameters:
 186         `dbus_interface` : str
 187             The D-Bus interface whose signal is emitted
 188         `signature` : str
 189             The signature of the signal in the usual D-Bus notation
 190
 191         `path_keyword` : str or None
 192             A keyword argument to the decorated method. If not None,
 193             that argument will not be emitted as an argument of
 194             the signal, and when the signal is emitted, it will appear
 195             to come from the object path given by the keyword argument.
 196
 197             Note that when calling the decorated method, you must always
 198             pass in the object path as a keyword argument, not as a
 199             positional argument.
 200
 201         `connection_keyword` : str or None
 202             Similar to `path_keyword`, but this gives the Connection on
 203             which the signal should be emitted. If given, and the path_keyword
 204             is also given, the signal will be emitted at that path on that
 205             connection; if given, but the path_keyword is not, the signal
 206             will be emitted from every path at which this object is available
 207             on that connection.
 208
 209             If not given, the signal is emitted on every Connection on which
 210             the object is available: if the `path_keyword` is given, it will
 211             be emitted at that path on each Connection, otherwise it will be
 212             emitted once per (Connection, path) pair.
 213     """
 214     _dbus_bindings.validate_interface_name(dbus_interface)
 215     def decorator(func):
 216         member_name = func.__name__
 217         _dbus_bindings.validate_member_name(member_name)
 218
 219         def emit_signal(self, *args, **keywords):
 220             func(self, *args, **keywords)
 221
 222             object_path = None
 223             if path_keyword:
 224                 object_path = keywords.pop(path_keyword, None)
 225             connection = None
 226             if connection_keyword:
 227                 connection = keywords.pop(connection_keyword, None)
 228
 229             if connection is None:
 230                 if object_path is None:
 231                     # any conn, any path
 232                     locations = self.locations
 233                 else:
 234                     # any conn, specified path
 235                     connections = set()
 236                     for location in self.locations:
 237                         connections.add(connection)
 238                     locations = [(connection, object_path)
 239                                  for connection in connections]
 240             elif object_path is None:
 241                 # specified conn, any path
 242                 locations = [L for L in self.locations if L[0] is connection]
 243             else:
 244                 # specified conn, specified path
 245                 locations = ((connection, object_path),)
 246
 247             for location in locations:
 248                 message = _dbus_bindings.SignalMessage(location[1],
 249                                                        dbus_interface,
 250                                                        member_name)
 251                 if signature is not None:
 252                     message.append(signature=signature, *args)
 253                 else:
 254                     message.append(*args)
 255
 256                 location[0].send_message(message)
 257
 258         args = inspect.getargspec(func)[0]
 259         args.pop(0)
 260
 261         if signature:
 262             sig = tuple(_dbus_bindings.Signature(signature))
 263
 264             if len(sig) > len(args):
 265                 raise ValueError, 'signal signature is longer than the number of arguments provided'
 266             elif len(sig) < len(args):
 267                 raise ValueError, 'signal signature is shorter than the number of arguments provided'
 268
 269         emit_signal.__name__ = func.__name__
 270         emit_signal.__doc__ = func.__doc__
 271         emit_signal._dbus_is_signal = True
 272         emit_signal._dbus_interface = dbus_interface
 273         emit_signal._dbus_signature = signature
 274         emit_signal._dbus_args = args
 275         return emit_signal
 276
 277     return decorator