8/14/2019 API changes in python

1/2

===============================API changes in dbus-python 0.80===============================Type changes============

* The Byte constructor accepts either single-byte strings, or integers inthe range 0 to 255.

* There is no Variant type any more. Instead, the ``variant_level``attribute on D-Bus types gives the number of variant wrappers inwhich it is contained; this is to remove ambiguity. For instance, callingthis method::

@dbus.service.method('com.example', in_signature='v', out_signature='')def Print(self, variant):

print repr(variant)

yields the following results::

# on the wire: Variant containing Int32

Int32(0, variant_level=1)# on the wire: Variant containing Variant containing Int32Int32(0, variant_level=2)

Once an object of a D-Bus type has been constructed, its``variant_level`` cannot be altered.

* The D-Bus integer types (dbus.Int32, etc.) are properly range-checked.

* The Array constructor takes arguments (iterable[, signature])rather than (iterable[, type][, signature]); ditto for Dict.

Calling conventions

===================

* In method parameters, method returns from proxy methods, etc.,integers arrive as instances of dbus.Int32 etc., bytes arrive asByte, and so on, rather than everything being converted to anappropriate built-in Python type. This means you can tell exactlywhat arguments went over the bus, and their types.

* Proxy methods with multiple return values return a tuple rather thana list.

* Calling a proxy method with reply ignored, or with asynchandlers, returns None

``dbus_bindings``=================

* ConnectionError no longer exists (it was never raised)

* ``dbus_bindings`` is now called ``_dbus_bindings``, and is considerablydifferent internally:

* connections are private at the libdbus level: shared connectionsare only shared among Python code

8/14/2019 API changes in python

2/2

* The MessageIter stuff is now done in C: there's a much simplerPython API, ``Message.append(...)`` where positional arguments arethe things to be appended, and the keyword argument ``signature``controls how objects are interpreted

* The signature-guessing algorithm used if there is no propersignature is exposed as a static method,

``Message.guess_signature(*args)``

* Bus is a subclass of Connection rather than being a wrapper objectwhich has-a Connection

* The timeouts in _send_with_reply and in _send_with_reply_and_blockare in (possibly fractional) seconds, as is conventional in Python

* The specialized Message subclasses have names ending with Message

* There is a small amount of compatibility glue in a new``dbus_bindings`` module (also ``dbus.dbus_bindings``)which should enable most current code to work - this is deprecated,

and will disappear in a future version of dbus-python

Main loops==========

Main loop handling is different - instead of the``use_default_mainloop`` keyword argument to Bus and subclasses, there's now``mainloop`` which takes an instance of dbus.mainloop.NativeMainLoop.

Alternatively, you can set a default main loop by calling``dbus.set_default_main_loop()`` and passing it a NativeMainLoop, orby passing ``set_as_default=True`` to the factory functionfrom which you obtained the native main loop.

The plan is that in a future version of dbus-python there will be anabstract base class dbus.mainloop.MainLoop (or something); when it's added,instances of its subclasses will be accepted wherever a NativeMainLoopinstance is now. This will let you wrap main loops using a Python API.This will be used to implement SimpleMainLoop (a pure-Python main loopwhich can only do D-Bus) and a Twisted main-loop wrapper.

The only working mainloop implementation is (still) GLib; you can geta NativeMainLoop instance by::

from dbus.mainloop.glib import DBusGMainLoopmy_native_main_loop = DBusGMainLoop(set_as_default=True)

The above is how the highly magical ``dbus.glib`` module is now implemented.At some point ``dbus.glib`` will be deprecated, since it's non-obvious,and pychecker will usually complain if you use it correctly!

At the moment the GLib main loop always uses the default main context;python-gobject will probably need to add some extra API before we canallow other main-contexts to be used.

..vim:set sw=2 sts=2 et ft=rst tw=72: