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   * Some relatively internal methods have been renamed starting with
  81     an underscore - most Python code shouldn't need to use them, and
  82     they expose the full complexity of Messages etc.
  83
  84   * The timeouts in _send_with_reply and in _send_with_reply_and_block
  85     are in (possibly fractional) seconds, as is conventional in Python
  86
  87   * The specialized Message subclasses have names ending with Message
  88
  89 * There is a small amount of compatibility glue in a new
  90   ``dbus_bindings`` module (also ``dbus.dbus_bindings``)
  91   which should enable most current code to work - this is deprecated,
  92   and will disappear in a future version of dbus-python
  93
  94 Main loops
  95 ==========
  96
  97 Main loop handling is different - instead of the
  98 ``use_default_mainloop`` keyword argument to Bus and subclasses, there's now
  99 ``mainloop`` which takes an instance of dbus.mainloop.NativeMainLoop.
 100
 101 Alternatively, you can set a default main loop by calling
 102 ``dbus.set_default_main_loop()`` and passing it a NativeMainLoop, or
 103 by passing ``set_as_default=True`` to the factory function
 104 from which you obtained the native main loop.
 105
 106 The plan is that in a future version of dbus-python there will be an
 107 abstract base class dbus.mainloop.MainLoop (or something); when it's added,
 108 instances of its subclasses will be accepted wherever a NativeMainLoop
 109 instance is now. This will let you wrap main loops using a Python API.
 110 This will be used to implement SimpleMainLoop (a pure-Python main loop
 111 which can only do D-Bus) and a Twisted main-loop wrapper.
 112
 113 The only working mainloop implementation is (still) GLib; you can get
 114 a NativeMainLoop instance by::
 115
 116   from dbus.mainloop.glib import DBusGMainLoop
 117   my_native_main_loop = DBusGMainLoop(set_as_default=True)
 118
 119 The above is how the highly magical ``dbus.glib`` module is now implemented.
 120 At some point ``dbus.glib`` will be deprecated, since it's non-obvious,
 121 and pychecker will usually complain if you use it correctly!
 122
 123 At the moment the GLib main loop always uses the default main context;
 124 python-gobject will probably need to add some extra API before we can
 125 allow other main-contexts to be used.
 126
 127 ..
 128   vim:set sw=2 sts=2 et ft=rst tw=72: