summaryrefslogtreecommitdiff
path: root/src/leap/soledad/backends/couch.py
diff options
context:
space:
mode:
authordrebs <drebs@leap.se>2013-04-08 12:15:30 -0300
committerdrebs <drebs@leap.se>2013-04-08 12:15:30 -0300
commite6ca75a9e2a7a634f92ae54238df7d86100fbdab (patch)
treedd780d232253867ff26074dde1a7acc2dfb63fee /src/leap/soledad/backends/couch.py
parentd2d35a449beb05799bd68a7679f58382f8599152 (diff)
Add a LOT of docstrings.
Diffstat (limited to 'src/leap/soledad/backends/couch.py')
-rw-r--r--src/leap/soledad/backends/couch.py232
1 files changed, 201 insertions, 31 deletions
diff --git a/src/leap/soledad/backends/couch.py b/src/leap/soledad/backends/couch.py
index b7a77054..5407f992 100644
--- a/src/leap/soledad/backends/couch.py
+++ b/src/leap/soledad/backends/couch.py
@@ -1,42 +1,71 @@
+# -*- coding: utf-8 -*-
+# couch.py
+# Copyright (C) 2013 LEAP
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY 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/>.
+
+
"""A U1DB backend that uses CouchDB as its persistence layer."""
# general imports
import uuid
-from base64 import b64encode, b64decode
import re
-# u1db
+try:
+ import simplejson as json
+except ImportError:
+ import json # noqa
+
+
+from base64 import b64encode, b64decode
from u1db import errors
from u1db.sync import LocalSyncTarget
from u1db.backends.inmemory import InMemoryIndex
from u1db.remote.server_state import ServerState
from u1db.errors import DatabaseDoesNotExist
-# couchdb
from couchdb.client import Server, Document as CouchDocument
from couchdb.http import ResourceNotFound
-# leap
from leap.soledad.backends.objectstore import (
ObjectStoreDatabase,
ObjectStoreSyncTarget,
)
from leap.soledad.backends.leap_backend import LeapDocument
-try:
- import simplejson as json
-except ImportError:
- import json # noqa
-
class InvalidURLError(Exception):
- """Exception raised when Soledad encounters a malformed URL."""
- pass
+ """
+ Exception raised when Soledad encounters a malformed URL.
+ """
class CouchDatabase(ObjectStoreDatabase):
- """A U1DB backend that uses Couch as its persistence layer."""
+ """
+ A U1DB backend that uses Couch as its persistence layer.
+ """
@classmethod
def open_database(cls, url, create):
- """Open a U1DB database using CouchDB as backend."""
+ """
+ Open a U1DB database using CouchDB as backend.
+
+ @param url: the url of the database replica
+ @type url: str
+ @param create: should the replica be created if it does not exist?
+ @type create: bool
+
+ @return: the database instance
+ @rtype: CouchDatabase
+ """
# get database from url
m = re.match('(^https?://[^/]+)/(.+)$', url)
if not m:
@@ -51,24 +80,39 @@ class CouchDatabase(ObjectStoreDatabase):
raise DatabaseDoesNotExist()
return cls(url, dbname)
- def __init__(self, url, database, replica_uid=None, full_commit=True,
+ def __init__(self, url, dbname, replica_uid=None, full_commit=True,
session=None):
- """Create a new Couch data container."""
+ """
+ Create a new Couch data container.
+
+ @param url: the url of the couch database
+ @type url: str
+ @param dbname: the database name
+ @type dbname: str
+ @param replica_uid: an optional unique replica identifier
+ @type replica_uid: str
+ @param full_commit: turn on the X-Couch-Full-Commit header
+ @type full_commit: bool
+ @param session: an http.Session instance or None for a default session
+ @type session: http.Session
+ """
self._url = url
self._full_commit = full_commit
self._session = session
self._server = Server(url=self._url,
full_commit=self._full_commit,
session=self._session)
- self._dbname = database
+ self._dbname = dbname
# this will ensure that transaction and sync logs exist and are
# up-to-date.
try:
- self._database = self._server[database]
+ self._database = self._server[self._dbname]
except ResourceNotFound:
- self._server.create(database)
- self._database = self._server[database]
+ self._server.create(self._dbname)
+ self._database = self._server[self._dbname]
super(CouchDatabase, self).__init__(replica_uid=replica_uid,
+ # TODO: move the factory choice
+ # away
document_factory=LeapDocument)
#-------------------------------------------------------------------------
@@ -76,7 +120,19 @@ class CouchDatabase(ObjectStoreDatabase):
#-------------------------------------------------------------------------
def _get_doc(self, doc_id, check_for_conflicts=False):
- """Get just the document content, without fancy handling."""
+ """
+ Get just the document content, without fancy handling.
+
+ @param doc_id: The unique document identifier
+ @type doc_id: str
+ @param include_deleted: If set to True, deleted documents will be
+ returned with empty content. Otherwise asking for a deleted
+ document will return None.
+ @type include_deleted: bool
+
+ @return: a Document object.
+ @type: u1db.Document
+ """
cdoc = self._database.get(doc_id)
if cdoc is None:
return None
@@ -95,7 +151,19 @@ class CouchDatabase(ObjectStoreDatabase):
return doc
def get_all_docs(self, include_deleted=False):
- """Get the JSON content for all documents in the database."""
+ """
+ Get the JSON content for all documents in the database.
+
+ @param include_deleted: If set to True, deleted documents will be
+ returned with empty content. Otherwise deleted documents will not
+ be included in the results.
+ @type include_deleted: bool
+
+ @return: (generation, [Document])
+ The current generation of the database, followed by a list of all
+ the documents in the database.
+ @rtype: tuple
+ """
generation = self._get_generation()
results = []
for doc_id in self._database:
@@ -108,7 +176,19 @@ class CouchDatabase(ObjectStoreDatabase):
return (generation, results)
def _put_doc(self, doc):
- """Store document in database."""
+ """
+ Update a document.
+
+ This is called everytime we just want to do a raw put on the db (i.e.
+ without index updates, document constraint checks, and conflict
+ checks).
+
+ @param doc: The document to update.
+ @type doc: u1db.Document
+
+ @return: The new revision identifier for the document.
+ @rtype: str
+ """
# prepare couch's Document
cdoc = CouchDocument()
cdoc['_id'] = doc.doc_id
@@ -130,12 +210,19 @@ class CouchDatabase(ObjectStoreDatabase):
def get_sync_target(self):
"""
Return a SyncTarget object, for another u1db to synchronize with.
+
+ @return: The sync target.
+ @rtype: CouchSyncTarget
"""
return CouchSyncTarget(self)
def create_index(self, index_name, *index_expressions):
"""
Create a named index, which can then be queried for future lookups.
+
+ @param index_name: A unique name which can be used as a key prefix.
+ @param index_expressions: Index expressions defining the index
+ information.
"""
if index_name in self._indexes:
if self._indexes[index_name]._definition == list(
@@ -144,7 +231,7 @@ class CouchDatabase(ObjectStoreDatabase):
raise errors.IndexNameTakenError
index = InMemoryIndex(index_name, list(index_expressions))
for doc_id in self._database:
- if doc_id == self.U1DB_DATA_DOC_ID:
+ if doc_id == self.U1DB_DATA_DOC_ID: # skip special file
continue
doc = self._get_doc(doc_id)
if doc.content is not None:
@@ -154,7 +241,12 @@ class CouchDatabase(ObjectStoreDatabase):
self._store_u1db_data()
def close(self):
- """Release any resources associated with this database."""
+ """
+ Release any resources associated with this database.
+
+ @return: True if db was succesfully closed.
+ @rtype: bool
+ """
# TODO: fix this method so the connection is properly closed and
# test_close (+tearDown, which deletes the db) works without problems.
self._url = None
@@ -165,7 +257,20 @@ class CouchDatabase(ObjectStoreDatabase):
return True
def sync(self, url, creds=None, autocreate=True):
- """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.
+ @type url: str
+ @param creds: optional dictionary giving credentials.
+ to authorize the operation with the server.
+ @type creds: dict
+ @param autocreate: Ask the target to create the db if non-existent.
+ @type autocreate: bool
+
+ @return: The local generation before the synchronisation was performed.
+ @rtype: int
+ """
from u1db.sync import Synchronizer
return Synchronizer(self, CouchSyncTarget(url, creds=creds)).sync(
autocreate=autocreate)
@@ -175,8 +280,23 @@ class CouchDatabase(ObjectStoreDatabase):
#-------------------------------------------------------------------------
def _init_u1db_data(self):
+ """
+ Initialize U1DB info data structure in the couch db.
+
+ A U1DB database needs to keep track of all database transactions,
+ document conflicts, the generation of other replicas it has seen,
+ indexes created by users and so on.
+
+ In this implementation, all this information is stored in a special
+ document stored in the couch db with id equals to
+ CouchDatabse.U1DB_DATA_DOC_ID.
+
+ This method initializes the document that will hold such information.
+ """
if self._replica_uid is None:
self._replica_uid = uuid.uuid4().hex
+ # TODO: prevent user from overwriting a document with the same doc_id
+ # as this one.
doc = self._factory(doc_id=self.U1DB_DATA_DOC_ID)
doc.content = {'transaction_log': [],
'conflicts': b64encode(json.dumps({})),
@@ -186,6 +306,11 @@ class CouchDatabase(ObjectStoreDatabase):
self._put_doc(doc)
def _fetch_u1db_data(self):
+ """
+ Fetch U1DB info from the couch db.
+
+ See C{_init_u1db_data} documentation.
+ """
# retrieve u1db data from couch db
cdoc = self._database.get(self.U1DB_DATA_DOC_ID)
jsonstr = self._database.get_attachment(cdoc, 'u1db_json').getvalue()
@@ -202,6 +327,11 @@ class CouchDatabase(ObjectStoreDatabase):
self._couch_rev = cdoc['_rev']
def _store_u1db_data(self):
+ """
+ Store U1DB info in the couch db.
+
+ See C{_init_u1db_data} documentation.
+ """
doc = self._factory(doc_id=self.U1DB_DATA_DOC_ID)
doc.content = {
'transaction_log': self._transaction_log,
@@ -220,10 +350,15 @@ class CouchDatabase(ObjectStoreDatabase):
#-------------------------------------------------------------------------
def delete_database(self):
- """Delete a U1DB CouchDB database."""
+ """
+ Delete a U1DB CouchDB database.
+ """
del(self._server[self._dbname])
def _dump_indexes_as_json(self):
+ """
+ Dump index definitions as JSON string.
+ """
indexes = {}
for name, idx in self._indexes.iteritems():
indexes[name] = {}
@@ -232,6 +367,16 @@ class CouchDatabase(ObjectStoreDatabase):
return json.dumps(indexes)
def _load_indexes_from_json(self, indexes):
+ """
+ Load index definitions from JSON string.
+
+ @param indexes: A JSON serialization of a list of [('index-name',
+ ['field', 'field2'])].
+ @type indexes: str
+
+ @return: A dictionary with the index definitions.
+ @rtype: dict
+ """
dict = {}
for name, idx_dict in json.loads(indexes).iteritems():
idx = InMemoryIndex(name, idx_dict['definition'])
@@ -241,30 +386,55 @@ class CouchDatabase(ObjectStoreDatabase):
class CouchSyncTarget(ObjectStoreSyncTarget):
- pass
+ """
+ Functionality for using a CouchDatabase as a synchronization target.
+ """
class CouchServerState(ServerState):
- """Inteface of the WSGI server with the CouchDB backend."""
+ """
+ Inteface of the WSGI server with the CouchDB backend.
+ """
def __init__(self, couch_url):
self.couch_url = couch_url
def open_database(self, dbname):
- """Open a database at the given location."""
+ """
+ Open a couch database.
+
+ @param dbname: The name of the database to open.
+ @type dbname: str
+
+ @return: The CouchDatabase object.
+ @rtype: CouchDatabase
+ """
# TODO: open couch
from leap.soledad.backends.couch import CouchDatabase
return CouchDatabase.open_database(self.couch_url + '/' + dbname,
create=False)
def ensure_database(self, dbname):
- """Ensure database at the given location."""
+ """
+ Ensure couch database exists.
+
+ @param dbname: The name of the database to ensure.
+ @type dbname: str
+
+ @return: The CouchDatabase object and the replica uid.
+ @rtype: (CouchDatabase, str)
+ """
from leap.soledad.backends.couch import CouchDatabase
db = CouchDatabase.open_database(self.couch_url + '/' + dbname,
create=True)
return db, db._replica_uid
def delete_database(self, dbname):
- """Delete database at the given location."""
+ """
+ Delete couch database.
+
+ @param dbname: The name of the database to delete.
+ @type dbname: str
+ """
from leap.soledad.backends.couch import CouchDatabase
CouchDatabase.delete_database(self.couch_url + '/' + dbname)