=======================================
dbus-python_: Python bindings for D-Bus
=======================================

.. _dbus-python: http://www.freedesktop.org/wiki/Software/DBusBindings#python

About this Fork
===============

This fork includes changes to the library to add a setup.py so it can be
installed via pip (allowing the version to be controlled, etc.).  This
can be done by doing the following (under Ubuntu/Debian)::

    $ sudo apt-get build-dep python-dbus
    $ pip install -U git+https://github.com/posborne/dbus-python.git

There is not currently a package on PyPI as we would like to make one last
push at including these changes in upstream.

Usage
=====

Online documentation can be found at
<http://dbus.freedesktop.org/doc/dbus-python/>.

There is an incomplete tutorial in `doc/tutorial.txt`__
(if you compile dbus-python with `docutils`_' ``rst2html`` tool installed or
you're reading this document on the D-Bus website, there's also an
`HTML version`__).

__ doc/tutorial.txt
__ doc/tutorial.html

`API documentation`_ is generated if you compile dbus-python with `epydoc`_
version 3 and `docutils`_ installed. An `online copy of the API documentation`_
is also available.

.. _API documentation: api/index.html
.. _epydoc: http://epydoc.sourceforge.net/
.. _docutils: http://docutils.sourceforge.net/
.. _online copy of the API documentation:
   http://dbus.freedesktop.org/doc/dbus-python/api/

To develop on dbus-python, see `doc/HACKING.txt`__ or the `HTML version`__.

__ doc/HACKING.txt
__ doc/HACKING.html

Problems and alternatives
=========================

dbus-python might not be the best D-Bus binding for you to use. dbus-python
does not follow the principle of "In the face of ambiguity, refuse the
temptation to guess", and can't be changed to not do so without seriously
breaking compatibility.

In addition, it uses libdbus (which has known problems with multi-threaded
use) and attempts to be main-loop-agnostic (which means you have to select
a suitable main loop for your application).

Alternative ways to get your Python code onto D-Bus include:

* GDBus, part of the GIO module of `GLib`_, via GObject-Introspection and
  `PyGI`_ (uses the GLib main loop and object model)

* QtDBus, part of `Qt`_, via `PyQt`_ (uses the Qt main loop and object model)

.. _GLib: http://developer.gnome.org/glib/
.. _PyGI: https://live.gnome.org/PyGObject
.. _Qt: https://qt.nokia.com/
.. _PyQT: http://www.riverbankcomputing.co.uk/software/pyqt/intro