Merge lp:~thisfred/u1db/documentation5 into lp:u1db

[Eric Casteleijn]

Finished first version of the Cosas based tutorial.

Finished first version of the Cosas based tutorial.

[Stuart Langridge (sil)]

When syncronising over http(s) servers can (and usually will) require OAuth -> When synchronising over http(s), servers can (and usually will) require OAuth

The section about editing docs (":py:meth:`~u1db.Database.put_doc` takes a :py:class:`~u1db.Document` object, because the object encapsulates revision information for a particular document") should, I think, say something like "the u1db.Document object is what you get from get_doc", so that people know what a Document object is. However, get_doc is described *after* put_doc. The get_doc bit also doesn't explain that it returns a Document at all. This whole section probably needs changing to reflect that (almost) everything is done with Document objects, you get a Document from get_doc, and you save that Document object back after making changes with it, so the procedure for altering an existing db entry is get_doc, edit the returned Document, put_doc it.

The section on the tags index ("The ``tags`` index will index any document that has a top level field ``tags`` and index its value.") could benefit from an example showing that a document with tags ["shopping", "food"] goes into the index twice. (I know this is explained in more detail elsewhere, but it'd be handy to help people understand if it's presented in context.)

review: Needs Fixing

[lp:~thisfred/u1db/documentation5]

389. By Eric Casteleijn on 2012-08-21

fixed typos and clarified

[Eric Casteleijn (thisfred)]

Pushed fixes

[Stuart Langridge (sil)]

review: Approve

=== modified file 'cosas/cosas.py'
--- cosas/cosas.py	2012-08-17 20:52:21 +0000
+++ cosas/cosas.py	2012-08-21 13:44:17 +0000
@@ -16,14 +16,13 @@
 
 """cosas example application."""
 
-import json
 import os
 import re
 import u1db
+import copy
 
 from dirspec.basedir import save_data_path
 
-EMPTY_TASK = json.dumps({"title": "", "done": False, "tags": []})
 
 TAGS_INDEX = 'tags'
 DONE_INDEX = 'done'
@@ -34,10 +33,13 @@
 
 TAGS = re.compile('#(\w+)|\[(.+)\]')
 
+EMPTY_TASK = {"title": "", "done": False, "tags": []}
+
+get_empty_task = lambda: copy.deepcopy(EMPTY_TASK)
+
 
 def get_database():
     """Get the path that the database is stored in."""
-
     # setting document_factory to Task means that any database method that
     # would return documents, now returns Tasks instead.
     return u1db.open(
@@ -108,7 +110,6 @@
                         # If results is empty, we're done: there are no
                         # documents with all tags.
                         return []
-        # Wrap each document in results in a Task object, and return them.
         return results.values()
 
     def get_task(self, doc_id):
@@ -121,7 +122,6 @@
             # The document id exists, but the document's content was previously
             # deleted.
             raise KeyError("Task with id %s was deleted." % (doc_id,))
-        # Wrap the document in a Task object and return it.
         return task
 
     def delete_task(self, task):
@@ -132,24 +132,17 @@
         """Create a new task document."""
         if tags is None:
             tags = []
-        # We copy the JSON string representing a pristine task with no title
-        # and no tags.
-        content = EMPTY_TASK
+        # We make a fresh copy of a pristine task with no title.
+        content = get_empty_task()
         # If we were passed a title or tags, or both, we set them in the object
         # before storing it in the database.
         if title or tags:
-            # Load the json string into a Python object.
-            content_object = json.loads(content)
-            content_object['title'] = title
-            content_object['tags'] = tags
-            # Convert the Python object back into a JSON string.
-            content = json.dumps(content_object)
+            content['title'] = title
+            content['tags'] = tags
         # Store the document in the database. Since we did not set a document
         # id, the database will store it as a new document, and generate
         # a valid id.
-        task = self.db.create_doc_from_json(content)
-        # Wrap the document in a Task object.
-        return task
+        return self.db.create_doc(content)
 
     def save_task(self, task):
         """Save task to the database."""
 
=== modified file 'cosas/test_cosas.py'
--- cosas/test_cosas.py	2012-08-02 13:14:54 +0000
+++ cosas/test_cosas.py	2012-08-21 13:44:17 +0000
@@ -18,7 +18,7 @@
 
 from testtools import TestCase
 from cosas import (
-    Task, TodoStore, INDEXES, TAGS_INDEX, EMPTY_TASK, extract_tags)
+    Task, TodoStore, INDEXES, TAGS_INDEX, get_empty_task, extract_tags)
 from u1db.backends import inmemory
 
 
@@ -185,7 +185,7 @@
         super(TaskTestCase, self).setUp()
         self.db = inmemory.InMemoryDatabase("cosas")
         self.db.set_document_factory(Task)
-        self.document = self.db.create_doc_from_json(EMPTY_TASK)
+        self.document = self.db.create_doc(get_empty_task())
 
     def test_task(self):
         """Initializing a task."""
 
=== modified file 'cosas/ui.py'
--- cosas/ui.py	2012-08-13 16:09:21 +0000
+++ cosas/ui.py	2012-08-21 13:44:17 +0000
@@ -524,11 +524,13 @@
                 db.set_oauth_credentials(**oauth_creds)
                 db.open(create=True)
             syncer.sync()
+        # refresh the UI to show changed or new tasks
         self.refresh_filter()
         self.update_status_bar("last synced: %s" % (datetime.now(),))
 
     def resolve(self, doc, revs):
         self.store.db.resolve_doc(doc, revs)
+        # refresh the UI to show the resolved version
         self.refresh_filter()
 
 
 
=== modified file 'html-docs/high-level-api.rst'
--- html-docs/high-level-api.rst	2012-08-17 19:00:38 +0000
+++ html-docs/high-level-api.rst	2012-08-21 13:44:17 +0000
@@ -19,8 +19,11 @@
 Creating and editing documents
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To create a document, use ``create_doc()``. Code examples below are
-from :ref:`reference-implementation` in Python.
+To create a document, use :py:meth:`~u1db.Database.create_doc` or
+:py:meth:`~u1db.Database.create_doc_from_json`. Code examples below are from
+:ref:`reference-implementation` in Python. :py:meth:`~u1db.Database.create_doc`
+takes a dictionary-like object, and 
+:py:meth:`~u1db.Database.create_doc_from_json` a JSON string.
 
 .. testsetup ::
 
@@ -43,10 +46,54 @@
     testdoc
 
 
-Editing an *existing* document is done with ``put_doc()``. This is separate
-from ``create_doc()`` so as to avoid accidental overwrites. ``put_doc()`` takes
-a ``Document`` object, because the object encapsulates revision information for
-a particular document.
+Retrieving documents
+^^^^^^^^^^^^^^^^^^^^
+
+The simplest way to retrieve documents from a u1db is by calling
+:py:meth:`~u1db.Database.get_doc` with a ``doc_id``. This will return a
+:py:class:`~u1db.Document` object [#]_.
+
+.. testcode ::
+
+    import u1db
+    db = u1db.open("mydb4.u1db", create=True)
+    doc = db.create_doc({"key": "value"}, doc_id="testdoc")
+    doc1 = db.get_doc("testdoc")
+    print doc1.content
+    print doc1.doc_id
+
+.. testoutput ::
+
+    {u'key': u'value'}
+    testdoc
+
+And it's also possible to retrieve many documents by ``doc_id``.
+
+.. testcode ::
+
+    import u1db
+    db = u1db.open("mydb5.u1db", create=True)
+    doc1 = db.create_doc({"key": "value"}, doc_id="testdoc1")
+    doc2 = db.create_doc({"key": "value"}, doc_id="testdoc2")
+    for doc in db.get_docs(["testdoc2","testdoc1"]):
+        print doc.doc_id
+
+.. testoutput ::
+
+    testdoc2
+    testdoc1
+
+Note that :py:meth:`u1db.Database.get_docs` returns the documents in the order
+specified.
+
+Editing existing documents
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Storing an *existing* document is done with :py:meth:`~u1db.Database.put_doc`.
+This is separate from :py:meth:`~u1db.Database.create_doc` so as to avoid
+accidental overwrites. :py:meth:`~u1db.Database.put_doc` takes a
+:py:class:`~u1db.Document` object, because the object encapsulates revision
+information for a particular document.
 
 .. testcode ::
 
@@ -70,7 +117,7 @@
     Now editing the doc with the doc object we got back...
     {u'key1': u'edited'}
 
-Finally, deleting a document is done with ``delete_doc()``.
+Finally, deleting a document is done with :py:meth:`~u1db.Database.delete_doc`.
 
 .. testcode ::
 
@@ -87,43 +134,6 @@
     None
     None
 
-Retrieving documents
-^^^^^^^^^^^^^^^^^^^^
-
-The simplest way to retrieve documents from a u1db is by ``doc_id``.
-
-.. testcode ::
-
-    import u1db
-    db = u1db.open("mydb4.u1db", create=True)
-    doc = db.create_doc({"key": "value"}, doc_id="testdoc")
-    doc1 = db.get_doc("testdoc")
-    print doc1.content
-    print doc1.doc_id
-
-.. testoutput ::
-
-    {u'key': u'value'}
-    testdoc
-
-And it's also possible to retrieve many documents by ``doc_id``.
-
-.. testcode ::
-
-    import u1db
-    db = u1db.open("mydb5.u1db", create=True)
-    doc1 = db.create_doc({"key": "value"}, doc_id="testdoc1")
-    doc2 = db.create_doc({"key": "value"}, doc_id="testdoc2")
-    for doc in db.get_docs(["testdoc2","testdoc1"]):
-        print doc.doc_id
-
-.. testoutput ::
-
-    testdoc2
-    testdoc1
-
-Note that ``get_docs()`` returns the documents in the order specified.
-
 Document functions
 ^^^^^^^^^^^^^^^^^^
 
@@ -382,20 +392,25 @@
 Synchronising a database can result in conflicts; if your user changes the same
 document in two different places and then syncs again, that document will be
 ''in conflict'', meaning that it has incompatible changes. If this is the case,
-``doc.has_conflicts`` will be true, and put_doc to a conflicted doc will give
-a ``ConflictedDoc`` error. To get a list of conflicted versions of the
-document, do ``get_doc_conflicts(doc_id)``. Deciding what the final
-unconflicted document should look like is obviously specific to the user's
-application; once decided, call ``resolve_doc(doc, list_of_conflicted_revisions)``
-to resolve and set the final resolved content.
+:py:attr:`~u1db.Document.has_conflicts` will be true, and put_doc to a
+conflicted doc will give a ``ConflictedDoc`` error. To get a list of conflicted
+versions of the document, do :py:meth:`~u1db.Database.get_doc_conflicts`.
+Deciding what the final unconflicted document should look like is obviously
+specific to the user's application; once decided, call
+:py:meth:`~u1db.Database.resolve_doc` to resolve and set the final resolved
+content.
 
-Synchronising functions
+Synchronising Functions
 ^^^^^^^^^^^^^^^^^^^^^^^
 
  * :py:meth:`~u1db.Database.sync`
  * :py:meth:`~u1db.Database.get_doc_conflicts`
  * :py:meth:`~u1db.Database.resolve_doc`
 
+.. [#] Alternatively if a factory function was passed into
+    :py:func:`u1db.open`, :py:meth:`~u1db.Database.get_doc` will return
+    whatever type of object the factory function returns.
+
 .. testcleanup ::
 
     os.chdir(old_dir)
 
=== modified file 'html-docs/tutorial.rst'
--- html-docs/tutorial.rst	2012-08-17 21:22:56 +0000
+++ html-docs/tutorial.rst	2012-08-21 13:44:17 +0000
@@ -2,13 +2,13 @@
 ########
 
 In this tutorial we will demonstrate what goes into creating an application
-that uses u1db as a backend. We will use code from the simple todo list
+that uses u1db as a backend. We will use code samples from the simple todo list
 application 'Cosas' as our example. The full source code to Cosas can be found
 in the u1db source tree.  It comes with a user interface, but we will only
 focus on the code that interacts with u1db here.
 
-Tasks
------
+Defining the Task Object
+------------------------
 
 First we need to define what we'll actually store in u1db. For a todo list
 application, it makes sense to have each todo item or task be a single
@@ -27,13 +27,9 @@
 
 .. code-block:: python
 
-    '''
-    {
-     "title": "the task at hand",
-     "done": false,
-     "tags": ["urgent", "priority 1", "today"]
-    }
-    '''
+    '{"title": "the task at hand",
+      "done": false,
+      "tags": ["urgent", "priority 1", "today"]}'
 
 We can define ``Task`` as follows:
 
@@ -128,3 +124,302 @@
 
     True
 
+This is all we need the task object to do: as long as we have a way to store
+all its data in the .content dictionary, the super class will take care of
+converting that into JSON so it can be stored in the database.
+
+For convenience, we can create a function that returns a fresh copy of the
+content that would make up an empty task:
+
+.. code-block:: python
+
+    EMPTY_TASK = {"title": "", "done": False, "tags": []}
+
+    get_empty_task = lambda: copy.deepcopy(EMPTY_TASK)
+
+Defining Indexes
+----------------
+
+Now that we have tasks defined, we will probably want to query the database
+using their properties. To that end, we will need to use indexes. Let's define
+two for now, one to query by tags, and one to query by done status. We'll
+define some global constants with the name and the definition of the indexes,
+which will make them easier to refer to in the rest of the code:
+
+.. code-block:: python
+
+    TAGS_INDEX = 'tags'
+    DONE_INDEX = 'done'
+    INDEXES = {
+        TAGS_INDEX: ['tags'],
+        DONE_INDEX: ['bool(done)'],
+    }
+
+``INDEXES`` is just a regular dictionary, with the names of the indexes as
+keys, and the index definitions, which are lists of expressions as values. (We
+chose to use lists since an index can be defined on multiple fields, though
+both of the indexes defined above only index a single field.)
+
+The ``tags`` index will index any document that has a top level field ``tags``
+and index its value. Our tasks will have a list value under ``tags`` which
+means that u1db will index each task for each of the values in the list in this
+index. So a task with the following content:
+
+.. code-block:: python
+
+    {
+        "title": "Buy sausages and vimto",
+        "tags": ["shopping", "food"],
+        "done": false
+    }
+
+Would be indexed under both ``"food"`` and ``"shopping"``.
+
+The ``done`` index will index any document that has a boolean value in a top
+level field with the name ``done``.
+
+We will see how the indexes are actually created and queried below.
+
+Storing and Retrieving Tasks
+----------------------------
+
+To store and retrieve our task objects we'll need a u1db
+:py:class:`~u1db.Database`. We can make a little helper function to get a
+reference to our application's database, and create it if it doesn't already
+exist:
+
+
+.. code-block:: python
+
+    from dirspec.basedir import save_data_path
+
+    def get_database():
+        """Get the path that the database is stored in."""
+        return u1db.open(
+            os.path.join(save_data_path("cosas"), "cosas.u1db"), create=True,
+            document_factory=Task)
+
+There are a few things to note here: First of all, we use
+`lp:dirspec <http://launchpad.net/dirspec/>`_ to handle where to find or put
+the database in a way that works across platforms. This is not something
+specific to u1db, so you could choose to use it for your own application or
+not: :py:func:`u1db.open` will happily take any filesystem path. Secondly, we
+pass our Task class into the ``document_factory`` argument of
+:py:func:`u1db.open`. This means that any time we get documents from the
+database, it will return Task objects, so we don't have to do the conversion in
+our code.
+
+Now we create a TodoStore class that will handle all interactions with the
+database:
+
+.. code-block:: python
+
+    class TodoStore(object):
+        """The todo application backend."""
+
+        def __init__(self, db):
+            self.db = db
+
+        def initialize_db(self):
+            """Initialize the database."""
+            # Ask the database for currently existing indexes.
+            db_indexes = dict(self.db.list_indexes())
+            # Loop through the indexes we expect to find.
+            for name, expression in INDEXES.items():
+                if name not in db_indexes:
+                    # The index does not yet exist.
+                    self.db.create_index(name, *expression)
+                    continue
+                if expression == db_indexes[name]:
+                    # The index exists and is up to date.
+                    continue
+                # The index exists but the definition is not what expected, so we
+                # delete it and add the proper index expression.
+                self.db.delete_index(name)
+                self.db.create_index(name, *expression)
+
+The ``initialize_db()`` method checks whether the database already has the
+indexes we defined above and if it doesn't or if the definition is different
+than the one we have, the index is (re)created. We will call this method every
+time we start the application, to make sure all the indexes are up to date.
+Creating an index is a matter of calling :py:meth:`~u1db.Database.create_index`
+with a name and the expressions that define the index. This will immediately
+index all documents already in the database, and afterwards any that are added
+or updated.
+
+.. code-block:: python
+
+        def get_all_tags(self):
+            """Get all tags in use in the entire database."""
+            return [key[0] for key in self.db.get_index_keys(TAGS_INDEX)]
+
+The py:meth:`~u1db.Database.get_index_keys` method gets a list of all indexed
+*values* from an index. In this case it will give us a list of all tags that
+have been used in the database, which can be useful if we want to present them
+in the user interface of our application.
+
+.. code-block:: python
+
+        def get_tasks_by_tags(self, tags):
+            """Get all tasks that have every tag in tags."""
+            if not tags:
+                # No tags specified, so return all tasks.
+                return self.get_all_tasks()
+            # Get all tasks for the first tag.
+            results = dict(
+                (doc.doc_id, doc) for doc in
+                self.db.get_from_index(TAGS_INDEX, tags[0]))
+            # Now loop over the rest of the tags (if any) and remove from the
+            # results any document that does not have that particular tag.
+            for tag in tags[1:]:
+                # Get the ids of all documents with this tag.
+                ids = [
+                    doc.doc_id for doc in self.db.get_from_index(TAGS_INDEX, tag)]
+                for key in results.keys():
+                    if key not in ids:
+                        # Remove the document from result, because it does not have
+                        # this particular tag.
+                        del results[key]
+                        if not results:
+                            # If results is empty, we're done: there are no
+                            # documents with all tags.
+                            return []
+            return results.values()
+
+This method gives us a way to query the database by a set of tags. We loop
+through the tags one by one and then filter out any documents that don't have
+that particular tag.
+
+.. code-block:: python
+
+        def get_task(self, doc_id):
+            """Get a task from the database."""
+            task = self.db.get_doc(doc_id)
+            if task is None:
+                # No document with that id exists in the database.
+                raise KeyError("No task with id '%s'." % (doc_id,))
+            if task.is_tombstone():
+                # The document id exists, but the document's content was previously
+                # deleted.
+                raise KeyError("Task with id %s was deleted." % (doc_id,))
+            return task
+
+``get_task`` is a thin wrapper around :py:meth:`~u1db.Database.get_doc` that
+takes care of raising appropriate exceptions when a document does not exist or
+has been deleted. (Deleted documents leave a 'tombstone' behind, which is
+necessary to make sure that synchronisation of the database with other replicas
+does the right thing.)
+
+.. code-block:: python
+
+        def new_task(self, title=None, tags=None):
+            """Create a new task document."""
+            if tags is None:
+                tags = []
+            # We make a fresh copy of a pristine task with no title.
+            content = get_empty_task()
+            # If we were passed a title or tags, or both, we set them in the object
+            # before storing it in the database.
+            if title or tags:
+                content['title'] = title
+                content['tags'] = tags
+            # Store the document in the database. Since we did not set a document
+            # id, the database will store it as a new document, and generate
+            # a valid id.
+            return self.db.create_doc(content)
+
+Here we use the convenience function defined above to initialize the content,
+and then set the properties that were passed into ``new_task``. We call
+:py:meth:`~u1db.Database.create_doc` to create a new document from the content.
+This creates the document in the database, assigns it a new unique id (unless
+we pass one in,) and returns a fully initialized Task object. (Since we made
+that the database's factory.)
+
+.. code-block:: python
+
+        def get_all_tasks(self):
+            return self.db.get_from_index(DONE_INDEX, "*")
+
+
+Since the ``DONE_INDEX`` indexes anything that has a value in the field "done",
+and all tasks do (either True or False), it's a good way to get all tasks out
+of the database, especially since it will sort them by done status, so we'll
+get all the active tasks first.
+
+Synchronisation and Conflicts
+-----------------------------
+
+Synchronisation has to be initiated by the application, either periodically,
+while it's running, or by having the user initiate it. Any
+:py:class:`u1db.Database` can be synchronised with any other, either by file
+path or URL. Cosas gives the user the choice between manually synchronising or
+having it happen automatically, every 30 minutes, for as long as it is running.
+
+.. code-block:: python
+
+    from ubuntuone.platform.credentials import CredentialsManagementTool
+
+        def get_ubuntuone_credentials(self):
+            cmt = CredentialsManagementTool()
+            return cmt.find_credentials()
+
+        def _synchronize(self, creds=None):
+            target = self.sync_target
+            if target.startswith('http://') or target.startswith('https://'):
+                st = HTTPSyncTarget.connect(target)
+                oauth_creds = {
+                    'token_key': creds['token'],
+                    'token_secret': creds['token_secret'],
+                    'consumer_key': creds['consumer_key'],
+                    'consumer_secret': creds['consumer_secret']}
+                if creds:
+                    st.set_oauth_credentials(**oauth_creds)
+            else:
+                db = u1db.open(target, create=True)
+                st = db.get_sync_target()
+            syncer = Synchronizer(self.store.db, st)
+            try:
+                syncer.sync()
+            except DatabaseDoesNotExist:
+                # The server does not yet have the database, so create it.
+                if target.startswith('http://') or target.startswith('https://'):
+                    db = HTTPDatabase(target)
+                    db.set_oauth_credentials(**oauth_creds)
+                    db.open(create=True)
+                syncer.sync()
+            # refresh the UI to show changed or new tasks
+            self.refresh_filter()
+
+        def synchronize(self, finalize):
+            if self.sync_target == 'https://u1db.one.ubuntu.com/~/cosas':
+                d = self.get_ubuntuone_credentials()
+                d.addCallback(self._synchronize)
+                d.addCallback(finalize)
+            else:
+                self._synchronize()
+                finalize()
+
+When synchronising over http(s), servers can (and usually will) require OAuth
+authentication. The code above shows how to acquire and pass in the oauth
+credentials for the Ubuntu One server, in case you want your application to
+synchronize with that.
+
+After synchronising with another replica, it is possible that one or more
+conflicts have arisen, if both replicas independently made changes to the same
+document. Your application should probably check for conflicts after every
+synchronisation, and offer the user a way to resolve them.
+
+Look at the Conflicts class in cosas/ui.py to see an example of how this could
+be presented to the user. The idea is that you show the conflicting versions to
+the user, let them pick one, and then call
+:py:meth:`~u1db.Database.resolve_doc` with the preferred version, and all the
+revisions of the conflicting versions it is meant to resolve.
+
+.. code-block:: python
+
+        def resolve(self, doc, revs):
+            self.store.db.resolve_doc(doc, revs)
+            # refresh the UI to show the resolved version
+            self.refresh_filter()
+
+
 
=== modified file 'u1db/__init__.py'
--- u1db/__init__.py	2012-08-20 12:55:06 +0000
+++ u1db/__init__.py	2012-08-21 13:44:17 +0000
@@ -189,12 +189,16 @@
         Creating an index will block until the expressions have been evaluated
         and the index generated.
 
-        :index_name: A unique name which can be used as a key prefix
-        :index_expressions: index expressions defining the index information.
+        :param index_name: A unique name which can be used as a key prefix
+        :param index_expressions: index expressions defining the index
+            information.
+
             Examples:
-                "fieldname" to index alphabetically sorted on field.
-                "number(fieldname, width)", "lower(fieldname)",
-                "fieldname.subfieldname"
+
+            "fieldname", or "fieldname.subfieldname" to index alphabetically
+            sorted on the contents of a field.
+
+            "number(fieldname, width)", "lower(fieldname)"
         """
         raise NotImplementedError(self.create_index)
 
@@ -202,7 +206,6 @@
         """Remove a named index.
 
         :param index_name: The name of the index we are removing
-        :return: None
         """
         raise NotImplementedError(self.delete_index)
 
@@ -223,11 +226,11 @@
         It is also possible to append a '*' to the last supplied value (eg
         'val*', '*', '*' or 'val', 'val*', '*', but not 'val*', 'val', '*')
 
-        :return: List of [Document]
         :param index_name: The index to query
         :param key_values: values to match. eg, if you have
             an index with 3 fields then you would have:
             get_from_index(index_name, val1, val2, val3)
+        :return: List of [Document]
         """
         raise NotImplementedError(self.get_from_index)
 
@@ -244,7 +247,6 @@
         possible to append a '*' to the last supplied value (eg 'val*', '*',
         '*' or 'val', 'val*', '*', but not 'val*', 'val', '*')
 
-        :return: List of [Document]
         :param index_name: The index to query
         :param start_values: tuples of values that define the lower bound of
             the range. eg, if you have an index with 3 fields then you would
@@ -252,14 +254,15 @@
         :param end_values: tuples of values that define the upper bound of the
             range. eg, if you have an index with 3 fields then you would have:
             (val1, val2, val3)
+        :return: List of [Document]
         """
         raise NotImplementedError(self.get_range_from_index)
 
     def get_index_keys(self, index_name):
         """Return all keys under which documents are indexed in this index.
 
+        :param index_name: The index to query
         :return: [] A list of tuples of indexed keys.
-        :param index_name: The index to query
         """
         raise NotImplementedError(self.get_index_keys)
 
@@ -286,8 +289,6 @@
         :param doc: A Document with the new content to be inserted.
         :param conflicted_doc_revs: A list of revisions that the new content
             supersedes.
-        :return: None, doc will be updated with the new revision and
-            has_conflict flags.
         """
         raise NotImplementedError(self.resolve_doc)
 
@@ -303,7 +304,14 @@
         raise NotImplementedError(self.close)
 
     def sync(self, url):
-        """Synchronize documents with remote replica exposed at url."""
+        """Synchronize documents with remote replica exposed at url.
+
+        :param url: the url of the target replica to sync with.
+        :return: local_gen_before_sync The local generation before the
+            synchronisation was performed. This is useful to pass into
+            whatschanged, if an application wants to know which documents were
+            affected by a synchronisation.
+        """
         from u1db.sync import Synchronizer
         from u1db.remote.http_target import HTTPSyncTarget
         return Synchronizer(self, HTTPSyncTarget(url)).sync()
@@ -337,7 +345,6 @@
         :param other_generation: The generation number for the other replica.
         :param other_transaction_id: The transaction id associated with the
             generation.
-        :return: None
         """
         raise NotImplementedError(self._set_replica_gen_and_trans_id)
 
@@ -588,8 +595,8 @@
         :param source_replica_uid: Another replica which we might have
             synchronized with in the past.
         :return: (target_replica_uid, target_replica_generation,
-                  target_trans_id, source_replica_last_known_generation,
-                  source_replica_last_known_transaction_id)
+            target_trans_id, source_replica_last_known_generation,
+            source_replica_last_known_transaction_id)
         """
         raise NotImplementedError(self.get_sync_info)
 
@@ -609,10 +616,9 @@
 
         :param source_replica_uid: The identifier for the source replica.
         :param source_replica_generation:
-             The database generation for the source replica.
+            The database generation for the source replica.
         :param source_replica_transaction_id: The transaction id associated
             with the source replica generation.
-        :return: None
         """
         raise NotImplementedError(self.record_sync_info)
 
@@ -646,10 +652,10 @@
         :param last_known_trans_id: The last transaction id that the source
             replica knows about this target replica
         :param: return_doc_cb(doc, gen): is a callback
-                used to return documents to the source replica, it will
-                be invoked in turn with Documents that have changed since
-                last_known_generation together with the generation of
-                their last change.
+            used to return documents to the source replica, it will
+            be invoked in turn with Documents that have changed since
+            last_known_generation together with the generation of
+            their last change.
         :return: new_generation - After applying docs_by_generation, this is
             the current generation for this replica
         """