API_CHANGES.txt

   1 ===============================
   2 API changes in dbus-python 0.80
   3 ===============================
   4
   5 :Author: Simon McVittie
   6 :Contact: simon.mcvittie@collabora.co.uk
   7 :Organization: `Collabora Ltd`_
   8 :Date: 2006-11-23
   9
  10 .. _Collabora Ltd: http://www.collabora.co.uk/
  11
  12 Type changes
  13 ============
  14
  15 * The Byte constructor accepts either single-byte strings, or integers in
  16   the range 0 to 255.
  17
  18 * There is no Variant type any more. Instead, the ``variant_level``
  19   attribute on D-Bus types gives the number of variant wrappers in
  20   which it is contained; this is to remove ambiguity. For instance, calling
  21   this method::
  22
  23     @dbus.service.method('com.example', in_signature='v', out_signature='')
  24     def Print(self, variant):
  25         print repr(variant)
  26
  27   yields the following results::
  28
  29     # on the wire: Variant containing Int32
  30     Int32(0, variant_level=1)
  31     # on the wire: Variant containing Variant containing Int32
  32     Int32(0, variant_level=2)
  33
  34   Once an object of a D-Bus type has been constructed, its
  35   ``variant_level`` cannot be altered.
  36
  37 * The D-Bus integer types (dbus.Int32, etc.) are properly range-checked.
  38
  39 * The Array constructor takes arguments (iterable[, signature])
  40   rather than (iterable[, type][, signature]); ditto for Dict.
  41
  42 Calling conventions
  43 ===================
  44
  45 * In method parameters, method returns from proxy methods, etc.,
  46   integers arrive as instances of dbus.Int32 etc., bytes arrive as
  47   Byte, and so on, rather than everything being converted to an
  48   appropriate built-in Python type. This means you can tell exactly
  49   what arguments went over the bus, and their types.
  50
  51 * Proxy methods with multiple return values return a tuple rather than
  52   a list.
  53
  54 * Calling a proxy method with reply ignored, or with async
  55   handlers, returns None
  56
  57 ``dbus_bindings``
  58 =================
  59
  60 * ConnectionError no longer exists (it was never raised)
  61
  62 * ``dbus_bindings`` is now called ``_dbus_bindings``, and is considerably
  63   different internally:
  64
  65   * connections are private at the libdbus level: shared connections
  66     are only shared among Python code
  67
  68   * The MessageIter stuff is now done in C: there's a much simpler
  69     Python API, ``Message.append(...)`` where positional arguments are
  70     the things to be appended, and the keyword argument ``signature``
  71     controls how objects are interpreted
  72
  73   * The signature-guessing algorithm used if there is no proper
  74     signature is exposed as a static method,
  75     ``Message.guess_signature(*args)``
  76
  77   * Bus is a subclass of Connection rather than being a wrapper object
  78     which has-a Connection
  79
  80   * The timeouts in _send_with_reply and in _send_with_reply_and_block
  81     are in (possibly fractional) seconds, as is conventional in Python
  82
  83   * The specialized Message subclasses have names ending with Message
  84
  85 * There is a small amount of compatibility glue in a new
  86   ``dbus_bindings`` module (also ``dbus.dbus_bindings``)
  87   which should enable most current code to work - this is deprecated,
  88   and will disappear in a future version of dbus-python
  89
  90 Main loops
  91 ==========
  92
  93 Main loop handling is different - instead of the
  94 ``use_default_mainloop`` keyword argument to Bus and subclasses, there's now
  95 ``mainloop`` which takes an instance of dbus.mainloop.NativeMainLoop.
  96
  97 Alternatively, you can set a default main loop by calling
  98 ``dbus.set_default_main_loop()`` and passing it a NativeMainLoop, or
  99 by passing ``set_as_default=True`` to the factory function
 100 from which you obtained the native main loop.
 101
 102 The plan is that in a future version of dbus-python there will be an
 103 abstract base class dbus.mainloop.MainLoop (or something); when it's added,
 104 instances of its subclasses will be accepted wherever a NativeMainLoop
 105 instance is now. This will let you wrap main loops using a Python API.
 106 This will be used to implement SimpleMainLoop (a pure-Python main loop
 107 which can only do D-Bus) and a Twisted main-loop wrapper.
 108
 109 The only working mainloop implementation is (still) GLib; you can get
 110 a NativeMainLoop instance by::
 111
 112   from dbus.mainloop.glib import DBusGMainLoop
 113   my_native_main_loop = DBusGMainLoop(set_as_default=True)
 114
 115 The above is how the highly magical ``dbus.glib`` module is now implemented.
 116 At some point ``dbus.glib`` will be deprecated, since it's non-obvious,
 117 and pychecker will usually complain if you use it correctly!
 118
 119 At the moment the GLib main loop always uses the default main context;
 120 python-gobject will probably need to add some extra API before we can
 121 allow other main-contexts to be used.
 122
 123 ..
 124   vim:set sw=2 sts=2 et ft=rst tw=72: