doc/HACKING.txt

   1 =========================================
   2 D-Bus Python bindings - notes for hackers
   3 =========================================
   4
   5 :Author: Simon McVittie, `Collabora`_
   6 :Date: 2007-01-24
   7
   8 .. _Collabora: http://www.collabora.co.uk/
   9
  10 Upstream development
  11 ====================
  12
  13 dbus-python is developed at freedesktop.org using ``git``.
  14 See UsingGit_ for some details.
  15
  16 .. _UsingGit: http://www.freedesktop.org/wiki/UsingGit
  17
  18 Anonymous access
  19     ``git clone git://anongit.freedesktop.org/git/dbus/dbus-python``
  20 Committer access (requires freedesktop.org shell account)
  21     ``git clone git+ssh://git.freedesktop.org/git/dbus/dbus-python``
  22
  23 Modules
  24 =======
  25
  26 ``dbus``, ``dbus.service`` and ``dbus.mainloop`` are core public API.
  27
  28 ``dbus.lowlevel`` provides a lower-level public API for advanced use.
  29
  30 ``dbus.mainloop.glib`` is the public API for the GLib main loop integration.
  31
  32 ``dbus.types`` and ``dbus.exceptions`` are mainly for backwards
  33 compatibility - use ``dbus`` instead in new code. Ditto ``dbus.glib``.
  34
  35 ``dbus._dbus``, ``dbus.introspect_parser``, ``dbus.proxies`` are internal
  36 implementation details.
  37
  38 ``_dbus_bindings`` is the real implementation of the Python/libdbus
  39 integration, while ``_dbus_bindings`` is the real implementation of
  40 Python/libdbus-glib integration. Neither is public API, although some
  41 of the classes and functions are exposed as public API in other modules.
  42
  43 Threading/locking model
  44 =======================
  45
  46 All Python functions must be called with the GIL (obviously).
  47
  48 Before calling into any D-Bus function that can block, release the GIL;
  49 as well as the usual "be nice to other threads", D-Bus does its own
  50 locking and we don't want to deadlock with it. Most Connection methods
  51 can block.
  52
  53 Other notes
  54 ===========
  55
  56 Code needs to be Python 2.5 compatible - use Py_ssize_t where appropriate.
  57 See http://www.python.org/dev/peps/pep-0353/ for details.
  58
  59 Indentation and other holy wars
  60 ===============================
  61
  62 Python code is meant to follow PEP8, and has 4-space indentation, no hard tabs.
  63
  64 C code is meant to follow what PEP7 refers to as "Python 3000" style - 4-space
  65 indentation, no hard tabs, otherwise consistent with historical Python 2.x
  66 code.
  67
  68 Docstrings etc. are reStructuredText.