Try to avoid importing things from _dbus_bindings when they could be imported from...
[dbus-python-phuang.git] / doc / API_CHANGES.txt
blobace4f5b7d6cec6021a204b0d5908509827f8b5c4
1 ===============================
2 API changes in dbus-python 0.80
3 ===============================
5 :Author: Simon McVittie
6 :Contact: simon.mcvittie@collabora.co.uk
7 :Organization: `Collabora Ltd`_
8 :Date: 2006-11-23
10 .. _Collabora Ltd: http://www.collabora.co.uk/
12 Type changes
13 ============
15 * The Byte constructor accepts either single-byte strings, or integers in
16   the range 0 to 255.
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::
23     @dbus.service.method('com.example', in_signature='v', out_signature='') 
24     def Print(self, variant):
25         print repr(variant)
27   yields the following results::
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)
34   Once an object of a D-Bus type has been constructed, its
35   ``variant_level`` cannot be altered.
37 * The D-Bus integer types (dbus.Int32, etc.) are properly range-checked.
39 * The Array constructor takes arguments (iterable[, signature])
40   rather than (iterable[, type][, signature]); ditto for Dict.
42 Calling conventions
43 ===================
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.
51 * Proxy methods with multiple return values return a tuple rather than
52   a list.
54 * Calling a proxy method with reply ignored, or with async
55   handlers, returns None
57 ``dbus_bindings``
58 =================
60 * ConnectionError no longer exists (it was never raised)
62 * ``dbus_bindings`` is now called ``_dbus_bindings``, and is considerably
63   different internally:
65   * connections are private at the libdbus level: shared connections
66     are only shared among Python code
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
73   * The signature-guessing algorithm used if there is no proper
74     signature is exposed as a static method,
75     ``Message.guess_signature(*args)``
77   * Bus is a subclass of Connection rather than being a wrapper object
78     which has-a Connection
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
83   * The specialized Message subclasses have names ending with Message
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
90 Main loops
91 ==========
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.
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.
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.
109 The only working mainloop implementation is (still) GLib; you can get
110 a NativeMainLoop instance by::
112   from dbus.mainloop.glib import DBusGMainLoop
113   my_native_main_loop = DBusGMainLoop(set_as_default=True)
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!
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.
124   vim:set sw=2 sts=2 et ft=rst tw=72: