[RFC] dbus-python API (re)definition

[Simon McVittie]

On Thu, 31 Aug 2006 at 16:50:55 +0100, Simon McVittie wrote:
> I'm also working on getting some API documentation
> together, using epydoc and reStructuredText.

Here's a start on that.

epydoc output:
	http://people.freedesktop.org/~smcv/temp/dbus-python.epydoc/

git (branched from upstream):
	http://people.freedesktop.org/~smcv/git/dbus-python/.git/

> I'm trying to add the magic __all__ attribute to each module - as well
> as making "import *" import only those names listed in __all__, this
> gives epydoc a hint that it should display documentation for those names
> (and only those names) in the page for this module, even if they were
> actually imported from elsewhere (for instance, SessionBus should be
> documented in dbus rather than in dbus._dbus).

I've added __all__ attributes and the epydoc output linked above respects this.

> * service-discovery-applet uses dbus.dbus_bindings.DBusException, so
>   I'll probably add a stub dbus.dbus_bindings which issues
>   a DeprecationWarning on import, for backwards compatibility.

This change will break service-discovery-applet. I've reported this upstream.

gnome-osd also seems to use a lot of dbus_bindings stuff - I'll make
sure there's some sort of backwards compatibility, or a new API they can use
instead.

> dbus_bindings thinks its full canonical name is dbus_bindings, but it's
> installed inside the dbus Python package, i.e. as "dbus.dbus_bindings".
> This confuses introspection tools like pychecker and epydoc, which IMO
> is reason enough to fix it!

It's now definitely _dbus_bindings (at the top level of the Python
package hierarchy). The source is still in the dbus directory in my git repo,
but I'll put the C reimplementation in a _dbus_bindings directory. Ditto
dbus_glib_bindings, which is now definitely _dbus_glib_bindings at the
top level.

	Simon