API_CHANGES.txt

   1 ===============================
   2 API changes in dbus-python-in-c
   3 ===============================
   4
   5 :Author: Simon McVittie
   6 :Contact: simon.mcvittie@collabora.co.uk
   7 :Organization: `Collabora Ltd`_
   8 :Date: 2006-09-26
   9
  10 .. _ Collabora Ltd: http://www.collabora.co.uk/
  11
  12 * Byte is a subtype of str rather than of int, which better matches
  13   Python's conventions for dealing with byte streams. Its constructor
  14   accepts either single-byte strings or integers in the range 0 to 255.
  15
  16 * In method parameters, method returns from proxy methods, etc.,
  17   integers arrive as instances of dbus.Int32 etc., bytes arrive as
  18   Byte, and so on, rather than everything being converted to an
  19   appropriate built-in Python type. This means you can tell exactly
  20   what arguments went over the bus, and their types.
  21
  22 * Variants arrive as method parameters, returns from proxy methods, etc.
  23   as Variant objects. This is a bit of a big change, but makes things
  24   completely unambiguous. To unwrap variants like the old Pyrex
  25   implementation did, you can write::
  26
  27       while isinstance(myparam, dbus.Variant):
  28           myparam = myparam.object
  29
  30   This should also work (and do nothing) under the Pyrex implementation.
  31
  32 * The D-Bus integer types (dbus.Int32, etc.) are properly range-checked.
  33
  34 * Variants are now immutable "value objects".
  35
  36 * Variants are somewhat more useful: they can be cast using int(),
  37   str(), long(), float(), you can iterate over them with iter() if they
  38   contain an iterable, you can compare them with ``==`` and ``!=``,
  39   and you can hash them if the underlying object supports it.
  40
  41 * Array constructor takes arguments (iterable[, signature])
  42   rather than (iterable[, type][, signature]); ditto Variant, Dict
  43
  44 * Proxy methods with multiple return values return a tuple rather than
  45   a list.
  46
  47 * Calling a proxy method with reply ignored, or with async
  48   handlers, returns None
  49
  50 * The Boolean, String, Double and Struct types are now aliases for the
  51   built-in bool, unicode, float and tuple types. Their use is vaguely
  52   deprecated.
  53
  54 * ConnectionError no longer exists (it was never raised)
  55
  56 * dbus_bindings is now called _dbus_bindings, and is considerably
  57   different internally:
  58
  59   * connections are private at the libdbus level: shared connections
  60     are only shared among Python code
  61
  62   * The MessageIter stuff is now done in C: there's a much simpler
  63     Python API, ``Message.append(...)`` where positional arguments are
  64     the things to be appended, and the keyword argument ``signature``
  65     controls how objects are interpreted
  66
  67   * The signature-guessing algorithm used if there is no proper
  68     signature is exposed as a static method,
  69     ``Message.guess_signature(*args)``
  70
  71   * Bus is a subclass of Connection rather than being a wrapper object
  72     which has-a Connection
  73
  74   * Some relatively internal methods have been renamed starting with
  75     an underscore - most Python code shouldn't need to use them, and
  76     they expose the full complexity of Messages etc.
  77
  78   * The timeouts in _send_with_reply and in _send_with_reply_and_block
  79     are in (possibly fractional) seconds, as is conventional in Python
  80
  81   * The specialized Message subclasses have names ending with Message
  82
  83 ..
  84   vim:set sw=2 sts=2 et ft=rst tw=72: