|
Packit |
130fc8 |
===============================
|
|
Packit |
130fc8 |
API changes in dbus-python 0.80
|
|
Packit |
130fc8 |
===============================
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
:Author: Simon McVittie
|
|
Packit |
130fc8 |
:Contact: simon.mcvittie@collabora.co.uk
|
|
Packit |
130fc8 |
:Organization: `Collabora Ltd`_
|
|
Packit |
130fc8 |
:Date: 2006-11-23
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
.. _Collabora Ltd: http://www.collabora.co.uk/
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
Type changes
|
|
Packit |
130fc8 |
============
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* The Byte constructor accepts either single-byte strings, or integers in
|
|
Packit |
130fc8 |
the range 0 to 255.
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* There is no Variant type any more. Instead, the ``variant_level``
|
|
Packit |
130fc8 |
attribute on D-Bus types gives the number of variant wrappers in
|
|
Packit |
130fc8 |
which it is contained; this is to remove ambiguity. For instance, calling
|
|
Packit |
130fc8 |
this method::
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
@dbus.service.method('com.example', in_signature='v', out_signature='')
|
|
Packit |
130fc8 |
def Print(self, variant):
|
|
Packit |
130fc8 |
print repr(variant)
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
yields the following results::
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
# on the wire: Variant containing Int32
|
|
Packit |
130fc8 |
Int32(0, variant_level=1)
|
|
Packit |
130fc8 |
# on the wire: Variant containing Variant containing Int32
|
|
Packit |
130fc8 |
Int32(0, variant_level=2)
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
Once an object of a D-Bus type has been constructed, its
|
|
Packit |
130fc8 |
``variant_level`` cannot be altered.
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* The D-Bus integer types (dbus.Int32, etc.) are properly range-checked.
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* The Array constructor takes arguments (iterable[, signature])
|
|
Packit |
130fc8 |
rather than (iterable[, type][, signature]); ditto for Dict.
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
Calling conventions
|
|
Packit |
130fc8 |
===================
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* In method parameters, method returns from proxy methods, etc.,
|
|
Packit |
130fc8 |
integers arrive as instances of dbus.Int32 etc., bytes arrive as
|
|
Packit |
130fc8 |
Byte, and so on, rather than everything being converted to an
|
|
Packit |
130fc8 |
appropriate built-in Python type. This means you can tell exactly
|
|
Packit |
130fc8 |
what arguments went over the bus, and their types.
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* Proxy methods with multiple return values return a tuple rather than
|
|
Packit |
130fc8 |
a list.
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* Calling a proxy method with reply ignored, or with async
|
|
Packit |
130fc8 |
handlers, returns None
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
``dbus_bindings``
|
|
Packit |
130fc8 |
=================
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* ConnectionError no longer exists (it was never raised)
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* ``dbus_bindings`` is now called ``_dbus_bindings``, and is considerably
|
|
Packit |
130fc8 |
different internally:
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* connections are private at the libdbus level: shared connections
|
|
Packit |
130fc8 |
are only shared among Python code
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* The MessageIter stuff is now done in C: there's a much simpler
|
|
Packit |
130fc8 |
Python API, ``Message.append(...)`` where positional arguments are
|
|
Packit |
130fc8 |
the things to be appended, and the keyword argument ``signature``
|
|
Packit |
130fc8 |
controls how objects are interpreted
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* The signature-guessing algorithm used if there is no proper
|
|
Packit |
130fc8 |
signature is exposed as a static method,
|
|
Packit |
130fc8 |
``Message.guess_signature(*args)``
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* Bus is a subclass of Connection rather than being a wrapper object
|
|
Packit |
130fc8 |
which has-a Connection
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* The timeouts in _send_with_reply and in _send_with_reply_and_block
|
|
Packit |
130fc8 |
are in (possibly fractional) seconds, as is conventional in Python
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* The specialized Message subclasses have names ending with Message
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
* There is a small amount of compatibility glue in a new
|
|
Packit |
130fc8 |
``dbus_bindings`` module (also ``dbus.dbus_bindings``)
|
|
Packit |
130fc8 |
which should enable most current code to work - this is deprecated,
|
|
Packit |
130fc8 |
and will disappear in a future version of dbus-python
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
Main loops
|
|
Packit |
130fc8 |
==========
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
Main loop handling is different - instead of the
|
|
Packit |
130fc8 |
``use_default_mainloop`` keyword argument to Bus and subclasses, there's now
|
|
Packit |
130fc8 |
``mainloop`` which takes an instance of dbus.mainloop.NativeMainLoop.
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
Alternatively, you can set a default main loop by calling
|
|
Packit |
130fc8 |
``dbus.set_default_main_loop()`` and passing it a NativeMainLoop, or
|
|
Packit |
130fc8 |
by passing ``set_as_default=True`` to the factory function
|
|
Packit |
130fc8 |
from which you obtained the native main loop.
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
The plan is that in a future version of dbus-python there will be an
|
|
Packit |
130fc8 |
abstract base class dbus.mainloop.MainLoop (or something); when it's added,
|
|
Packit |
130fc8 |
instances of its subclasses will be accepted wherever a NativeMainLoop
|
|
Packit |
130fc8 |
instance is now. This will let you wrap main loops using a Python API.
|
|
Packit |
130fc8 |
This will be used to implement SimpleMainLoop (a pure-Python main loop
|
|
Packit |
130fc8 |
which can only do D-Bus) and a Twisted main-loop wrapper.
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
The only working mainloop implementation is (still) GLib; you can get
|
|
Packit |
130fc8 |
a NativeMainLoop instance by::
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
from dbus.mainloop.glib import DBusGMainLoop
|
|
Packit |
130fc8 |
my_native_main_loop = DBusGMainLoop(set_as_default=True)
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
The above is how the highly magical ``dbus.glib`` module is now implemented.
|
|
Packit |
130fc8 |
At some point ``dbus.glib`` will be deprecated, since it's non-obvious,
|
|
Packit |
130fc8 |
and pychecker will usually complain if you use it correctly!
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
At the moment the GLib main loop always uses the default main context;
|
|
Packit |
130fc8 |
python-gobject will probably need to add some extra API before we can
|
|
Packit |
130fc8 |
allow other main-contexts to be used.
|
|
Packit |
130fc8 |
|
|
Packit |
130fc8 |
..
|
|
Packit |
130fc8 |
vim:set sw=2 sts=2 et ft=rst tw=72:
|