Merge lp:~verterok/ubuntuone-client/dbus-iface-docs into lp:ubuntuone-client

[Guillermo Gonzalez]

export method and signal docstrings via DBus Introspect, add script to generate a simple text file with SyncDaemon DBus API

[Guillermo Gonzalez (verterok)]

This branch adds a script to generate simple text file with the syncdaemon DBus API description.
In order to include the method docstrings I overrided a dbus-python magic method in the parent class of the DBus exposed objects to add an extra <docstring> tag to the Introspect xml, so we can get all the information directly from DBus
Also adds a new make target: 'docs'.

[lp:~verterok/ubuntuone-client/dbus-iface-docs]

292. By Guillermo Gonzalez on 2009-12-16

remove commented code

[Eric Casteleijn (thisfred)]

Looks good, tests pass.

review: Approve

[Rick McBride (rmcbride)]

Very nice! neat diagram too.

review: Approve

=== modified file '.bzrignore'
--- .bzrignore	2009-07-15 21:47:57 +0000
+++ .bzrignore	2009-12-16 20:33:18 +0000
@@ -42,3 +42,4 @@
 icons
 storageprotocol
 clientdefs.py
+docs/syncdaemon_dbus_api.txt

=== modified file 'Makefile.am'
--- Makefile.am	2009-09-25 18:48:03 +0000
+++ Makefile.am	2009-12-16 20:33:18 +0000
@@ -62,6 +62,10 @@
 	fi
 	rm -rf _trial_temp
 
+docs: protocol Makefile
+	PYTHONPATH="$(PYTHONPATH)" $(PYTHON) $(srcdir)/contrib/dbus-docs
+
+
 protocol: ubuntuone Makefile
 	PROTOCOL="ubuntuone/storageprotocol"; \
 	if [ ! -d $(USP_PATH) ]; then \

=== added file 'contrib/dbus-docs'
--- contrib/dbus-docs	1970-01-01 00:00:00 +0000
+++ contrib/dbus-docs	2009-12-16 20:33:18 +0000
@@ -0,0 +1,193 @@
+#!/usr/bin/env python
+#
+# Author: Guillermo Gonzalez <[e-mail]>
+#
+# Copyright 2009 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License version 3, as published
+# by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranties of
+# MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
+# PURPOSE.  See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from twisted.internet import glib2reactor
+glib2reactor.install()
+
+import sys
+import os
+import signal
+import dbus
+import subprocess
+import shutil
+
+from xml.etree import ElementTree
+
+sys.path.insert(0, os.path.abspath("."))
+
+from contrib.dbus_util import DBusRunner
+from contrib.testing.testcase import (
+    FakeMain, 
+    DBusGMainLoop, 
+    DBusInterface, 
+    FakeNetworkManager,
+)
+
+from ubuntuone.syncdaemon.dbus_interface import (
+    DBUS_IFACE_SYNC_NAME,
+    DBUS_IFACE_STATUS_NAME,
+    DBUS_IFACE_EVENTS_NAME,
+    DBUS_IFACE_FS_NAME,
+    DBUS_IFACE_SHARES_NAME,
+    DBUS_IFACE_CONFIG_NAME,
+)
+from ubuntuone.syncdaemon.tools import DBusClient
+from twisted.internet import reactor, defer
+
+
+iface_path = ((DBUS_IFACE_SYNC_NAME, '/'), (DBUS_IFACE_CONFIG_NAME, '/config'),
+              (DBUS_IFACE_EVENTS_NAME, '/events'), 
+              (DBUS_IFACE_FS_NAME, '/filesystem'), 
+              (DBUS_IFACE_SHARES_NAME, '/shares'), 
+              (DBUS_IFACE_STATUS_NAME, '/status'))
+
+
+def parse_introspect_data(xml):
+    """Parse the xml returned by Introspect and returns a dict"""
+    info = dict()
+    e = ElementTree.fromstring(xml)
+    for c in e.findall('interface'):
+        # ignore other interfaces 
+        if not c.attrib['name'].startswith('com.ubuntuone'):
+            continue
+        iface_name = c.attrib['name']
+        info[iface_name] = dict()
+        # methods
+        methods = dict()
+        for method in c.findall('method'):
+            meth_name = method.attrib['name']
+            args = []
+            for arg in method.findall('arg'):
+                dir = arg.attrib['direction']
+                type = arg.attrib['type']
+                if 'name' in arg.attrib:
+                    name = arg.attrib['name']
+                    args.append((type, dir, name))
+                else:
+                    args.append((type, dir))
+            docstrings = method.findall('docstring')
+            docstring = docstrings[0].text if docstrings else 'No docstring'
+            methods[meth_name] = dict(args=args, docstring=docstring)
+        info[iface_name]['methods'] = methods
+        # signals
+        signals = dict()
+        for signal in c.findall('signal'):
+            sig_name = signal.attrib['name']
+            args = []
+            for arg in signal.findall('arg'):
+                type = arg.attrib['type']
+                name = arg.attrib['name']
+                args.append((type, name))
+            docstrings = signal.findall('docstring')
+            docstring = docstrings[0].text if docstrings else 'No docstring'
+            signals[sig_name] = dict(args=args, docstring=docstring)
+        info[iface_name]['signals'] = signals
+    return info
+
+
+def get_info(path):
+    """Get all the introspectable info from 'path'"""
+    d = defer.Deferred()
+    client = DBusClient(bus, path, 'org.freedesktop.DBus.Introspectable')
+    client.call_method('Introspect', reply_handler=d.callback, 
+                       error_handler=d.errback)
+    return d
+
+
+def dump_to_stream(info_by_path, stream):
+    print >>stream, "SyncDaemon DBus API\n"
+    for path, interfaces in info_by_path.items():
+        print >>stream, "Object path: %s" % path
+        for iface_name, kinds in interfaces.items():
+            print >>stream, "  Interface: %s" % iface_name
+            print >>stream, "    Methods:"
+            for meth_name, val in kinds['methods'].items():
+                in_args = ','.join([arg[2] + '=' + arg[0] for arg in 
+                                    val['args'] if arg[1] == 'in'])
+                out_args = ','.join([arg[0] for arg in val['args'] 
+                                     if arg[1] == 'out'])
+                if out_args and in_args:
+                    print >>stream, "      %s(%s) -> %s" % (meth_name, in_args,
+                                                            out_args)
+                elif in_args:
+                    print >>stream, "      %s(%s)" % (meth_name, in_args)
+                else:
+                    print >>stream, "      %s()" % meth_name
+                print >>stream, "        %s\n" % val['docstring']
+            print >>stream, "    Signals:"
+            for signal_name, val in kinds['signals'].items():
+                in_args = ','.join([arg[1] + '=' + arg[0] \
+                                    for arg in val['args']])
+                if in_args:
+                    print >>stream, "      %s(%s)" % (signal_name, in_args)
+                else:
+                    print >>stream, "      %s(%s)" % signal_name
+                print >>stream, "        %s\n" % val['docstring']
+
+
[e-mail]
+def main(bus):
+    """Entry point"""
+    info_by_path = dict()
+    for iface, path in iface_path:
+        xml = yield get_info(path)
+        obj_info = parse_introspect_data(xml)
+        info_by_path[path] = obj_info
+    dest_file = os.path.join(os.getcwd(), 'docs', 'syncdaemon_dbus_api.txt')
+    with open(dest_file, 'w') as f:
+        dump_to_stream(info_by_path, f)
+    reactor.stop() 
+
+
+def start_syncdaemon(tmp_dir):
+    """Starts a syncdaemon instance just like the one used in the test suite"""
+    xdg_cache = os.path.join(tmp_dir, 'xdg_cache')
+    data_dir = os.path.join(xdg_cache, 'data')
+    partials_dir = os.path.join(xdg_cache, 'partials')
+    root_dir = os.path.join(tmp_dir, 'root')
+    shares_dir = os.path.join(tmp_dir, 'shares')
+    main = FakeMain(root_dir, shares_dir, data_dir, partials_dir)
+    loop = DBusGMainLoop(set_as_default=True)
+    bus = dbus.bus.BusConnection(mainloop=loop)
+    nm = FakeNetworkManager(bus)
+    dbus_iface = DBusInterface(bus, main, system_bus=bus)
+    main.dbus_iface = dbus_iface
+    return main, bus
+
+
+if __name__ == '__main__':
+    dbus_runner = DBusRunner()
+    dbus_runner.startDBus()
+    tmp_dir = os.path.join(os.getcwd(), 'tmp')
+    try:
+
+        m, bus = start_syncdaemon(tmp_dir)
+        try:
+            reactor.callWhenRunning(main, bus)
+            reactor.run()
+        finally:
+            m.quit()
+    finally:
+        dbus_runner.stopDBus()
+        # remove the tmp dir
+        os.chmod(tmp_dir, 0777)
+        for dirpath, dirs, _ in os.walk(tmp_dir):
+            for dir in dirs:
+                os.chmod(os.path.join(dirpath, dir), 0777)
+        shutil.rmtree(tmp_dir)
+

=== added file 'contrib/dbus_util.py'
--- contrib/dbus_util.py	1970-01-01 00:00:00 +0000
+++ contrib/dbus_util.py	2009-12-16 20:33:18 +0000
@@ -0,0 +1,72 @@
+#
+# Author: Guillermo Gonzalez <[e-mail]>
+#
+# Copyright 2009 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License version 3, as published
+# by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranties of
+# MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
+# PURPOSE.  See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import os
+import signal
+import subprocess
+
+from distutils.spawn import find_executable
+
+
+class DBusLaunchError(Exception):
+    """Error while launching dbus-daemon"""
+    pass
+
+class NotFoundError(Exception):
+    """Not found error"""
+    pass
+
+
+class DBusRunner(object):
+
+    def __init__(self):
+        self.dbus_address = None
+        self.dbus_pid = None
+        self.running = False
+
+    def startDBus(self):
+        """Start our own session bus daemon for testing."""
+        dbus = find_executable("dbus-daemon")
+        if not dbus:
+            raise NotFoundError("dbus-daemon was not found.")
+
+        config_file = os.path.join(os.getcwd(), "contrib", "testing",
+                                   "dbus-session.conf")
+        dbus_args = ["--fork",
+                     "--config-file=" + config_file,
+                     "--print-address=1",
+                     "--print-pid=2"]
+        p = subprocess.Popen([dbus] + dbus_args,
+                             bufsize=4096, stdout=subprocess.PIPE,
+                             stderr=subprocess.PIPE)
+
+        self.dbus_address = "".join(p.stdout.readlines()).strip()
+        self.dbus_pid = int("".join(p.stderr.readlines()).strip())
+
+        if self.dbus_address != "":
+            os.environ["DBUS_SESSION_BUS_ADDRESS"] = self.dbus_address
+        else:
+            os.kill(self.dbus_pid, signal.SIGKILL)
+            raise DBusLaunchError("There was a problem launching dbus-daemon.")
+        self.running = True
+
+    def stopDBus(self):
+        """Stop our DBus session bus daemon."""
+        del os.environ["DBUS_SESSION_BUS_ADDRESS"]
+        os.kill(self.dbus_pid, signal.SIGKILL)
+        self.running = False
+

=== modified file 'contrib/test'
--- contrib/test	2009-11-06 19:31:17 +0000
+++ contrib/test	2009-12-16 20:33:18 +0000
@@ -66,36 +66,6 @@
                         suite.addTests(module_suite)
         return suite
 
-    def startDBus(self):
-        """Start our own session bus daemon for testing."""
-        dbus = find_executable("dbus-daemon")
-        if not dbus:
-            raise NotFoundError("dbus-daemon was not found.")
-
-        config_file = os.path.join(os.getcwd(), "contrib", "testing",
-                                   "dbus-session.conf")
-        dbus_args = ["--fork",
-                     "--config-file=" + config_file,
-                     "--print-address=1",
-                     "--print-pid=2"]
-        p = subprocess.Popen([dbus] + dbus_args,
-                             bufsize=4096, stdout=subprocess.PIPE, 
-                             stderr=subprocess.PIPE)
-
-        self.dbus_address = "".join(p.stdout.readlines()).strip()
-        self.dbus_pid = int("".join(p.stderr.readlines()).strip())
-
-        if self.dbus_address != "":
-            os.environ["DBUS_SESSION_BUS_ADDRESS"] = self.dbus_address
-        else:
-            os.kill(self.dbus_pid, signal.SIGKILL)
-            raise DBusLaunchError("There was a problem launching dbus-daemon.")
-
-    def stopDBus(self):
-        """Stop our DBus session bus daemon."""
-        del os.environ["DBUS_SESSION_BUS_ADDRESS"]
-        os.kill(self.dbus_pid, signal.SIGKILL)
-
     def run(self, testpath, test_pattern=None):
         """run the tests. """
         # install the glib2reactor before any import of the reactor to avoid
@@ -106,7 +76,9 @@
         from twisted.trial.reporter import TreeReporter
         from twisted.trial.runner import TrialRunner
 
-        self.startDBus()
+        from contrib.dbus_util import DBusRunner
+        dbus_runner = DBusRunner()
+        dbus_runner.startDBus()
 
         workingDirectory = os.path.join(os.getcwd(), "_trial_temp", "tmp")
         runner = TrialRunner(reporterFactory=TreeReporter, realTimeErrors=True,
@@ -125,7 +97,7 @@
             result = runner.run(suite)
             success = result.wasSuccessful()
         finally:
-            self.stopDBus()
+            dbus_runner.stopDBus()
         if not success:
             sys.exit(1)
         else:

=== modified file 'ubuntuone/syncdaemon/dbus_interface.py'
--- ubuntuone/syncdaemon/dbus_interface.py	2009-12-07 20:49:54 +0000
+++ ubuntuone/syncdaemon/dbus_interface.py	2009-12-16 20:33:18 +0000
@@ -22,6 +22,7 @@
 
 from dbus import DBusException
 from itertools import groupby, chain
+from xml.etree import ElementTree
 
 from twisted.internet import defer
 from twisted.python.failure import Failure
@@ -90,6 +91,36 @@
         """ emit's a Error signal. """
         self.SignalError(signal, extra_args)
 
+    @classmethod
+    def _add_docstring(cls, func, reflection_data):
+        """add <docstring> tag to reflection_data if func.__doc__ isn't None."""
+        # add docstring element
+        if getattr(func, '__doc__', None) is not None:
+
+            element = ElementTree.fromstring(reflection_data)
+            doc = element.makeelement('docstring', dict())
+            data = '<![CDATA[' + func.__doc__ + ']]>'
+            doc.text = '%s'
+            element.insert(0, doc)
+            return ElementTree.tostring(element) % data
+        else:
+            return reflection_data
+
+    @classmethod
+    def _reflect_on_method(cls, func):
+        """override _reflect_on_method to provide an extra <docstring> element
+        in the xml.
+        """
+        reflection_data = dbus.service.Object._reflect_on_method(func)
+        reflection_data = cls._add_docstring(func, reflection_data)
+        return reflection_data
+
+    @classmethod
+    def _reflect_on_signal(cls, func):
+        reflection_data = dbus.service.Object._reflect_on_signal(func)
+        reflection_data = cls._add_docstring(func, reflection_data)
+        return reflection_data
+
 
 class Status(DBusExposedObject):
     """ Represent the status of the syncdaemon """