Add a LOT of docstrings.

1 files changed, 105 insertions, 10 deletions

diff --git a/src/leap/soledad/backends/leap_backend.py b/src/leap/soledad/backends/leap_backend.py
index a37f9d25..3110c662 100644
--- a/src/leap/soledad/backends/leap_backend.py
+++ b/src/leap/soledad/backends/leap_backend.py
@@ -1,21 +1,39 @@
+# -*- coding: utf-8 -*-
+# leap_backend.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 encrypts data before sending to server and decrypts after
-receiving.
+A U1DB backend for encrypting data before sending to server and decrypting
+after receiving.
 """
 
+import uuid
 try:
     import simplejson as json
 except ImportError:
     import json  # noqa
 
+
 from u1db import Document
 from u1db.remote import utils
 from u1db.remote.http_target import HTTPSyncTarget
 from u1db.remote.http_database import HTTPDatabase
 from u1db.errors import BrokenSyncStream
 
-import uuid
-
 
 class NoDefaultKey(Exception):
     """
@@ -33,7 +51,7 @@ class NoSoledadInstance(Exception):
 
 class DocumentNotEncrypted(Exception):
     """
-    Exception to signal failures in document encryption.
+    Raised for failures in document encryption.
     """
     pass
 
@@ -45,10 +63,33 @@ class LeapDocument(Document):
     LEAP Documents are standard u1db documents with cabability of returning an
     encrypted version of the document json string as well as setting document
     content based on an encrypted version of json string.
+
+    Also, LEAP Documents can be flagged as syncable or not, so the replicas
+    might not sync every document.
     """
 
     def __init__(self, doc_id=None, rev=None, json='{}', has_conflicts=False,
                  encrypted_json=None, soledad=None, syncable=True):
+        """
+        Container for handling an encryptable document.
+
+        @param doc_id: The unique document identifier.
+        @type doc_id: str
+        @param rev: The revision identifier of the document.
+        @type rev: str
+        @param json: The JSON string for this document.
+        @type json: str
+        @param has_conflicts: Boolean indicating if this document has conflicts
+        @type has_conflicts: bool
+        @param encrypted_json: The encrypted JSON string for this document. If
+            given, the decrypted value supersedes any raw json string given.
+        @type encrypted_json: str
+        @param soledad: An instance of Soledad so we can encrypt/decrypt
+            document contents when syncing.
+        @type soledad: soledad.Soledad
+        @param syncable: Should this document be synced with remote replicas?
+        @type syncable: bool
+        """
         super(LeapDocument, self).__init__(doc_id, rev, json, has_conflicts)
         self._soledad = soledad
         self._syncable = syncable
@@ -58,6 +99,9 @@ class LeapDocument(Document):
     def get_encrypted_content(self):
         """
         Return an encrypted JSON serialization of document's contents.
+
+        @return: The encrpted JSON serialization of document's contents.
+        @rtype: str
         """
         if not self._soledad:
             raise NoSoledadInstance()
@@ -66,16 +110,19 @@ class LeapDocument(Document):
 
     def set_encrypted_content(self, cyphertext):
         """
-        Set document's content based on an encrypted JSON serialization of
+        Decrypt C{cyphertext} and set document's content.
         contents.
         """
         plaintext = self._soledad.decrypt_symmetric(self.doc_id, cyphertext)
-        return self.set_json(plaintext)
+        self.set_json(plaintext)
 
     def get_encrypted_json(self):
         """
         Return a valid JSON string containing document's content encrypted to
         the user's public key.
+
+        @return: The encrypted JSON string.
+        @rtype: str
         """
         return json.dumps({'_encrypted_json': self.get_encrypted_content()})
 
@@ -90,9 +137,21 @@ class LeapDocument(Document):
         self.set_encrypted_content(cyphertext)
 
     def _get_syncable(self):
+        """
+        Return whether this document is syncable.
+
+        @return: Is this document syncable?
+        @rtype: bool
+        """
         return self._syncable
 
     def _set_syncable(self, syncable=True):
+        """
+        Determine if this document should be synced with remote replicas.
+
+        @param syncable: Should this document be synced with remote replicas?
+        @type syncable: bool
+        """
         self._syncable = syncable
 
     syncable = property(
@@ -101,15 +160,28 @@ class LeapDocument(Document):
         doc="Determine if document should be synced with server."
     )
 
-    # Returning the revision as string solves the following exception in
-    # Twisted web:
-    #     exceptions.TypeError: Can only pass-through bytes on Python 2
     def _get_rev(self):
+        """
+        Get the document revision.
+
+        Returning the revision as string solves the following exception in
+        Twisted web:
+            exceptions.TypeError: Can only pass-through bytes on Python 2
+
+        @return: The document revision.
+        @rtype: str
+        """
         if self._rev is None:
             return None
         return str(self._rev)
 
     def _set_rev(self, rev):
+        """
+        Set document revision.
+
+        @param rev: The new document revision.
+        @type rev: bytes
+        """
         self._rev = rev
 
     rev = property(
@@ -125,6 +197,18 @@ class LeapSyncTarget(HTTPSyncTarget):
     """
 
     def __init__(self, url, creds=None, soledad=None):
+        """
+        Initialize the LeapSyncTarget.
+
+        @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 soledad: An instance of Soledad so we can encrypt/decrypt
+            document contents when syncing.
+        @type soledad: soledad.Soledad
+        """
         super(LeapSyncTarget, self).__init__(url, creds)
         self._soledad = soledad
 
@@ -132,6 +216,17 @@ class LeapSyncTarget(HTTPSyncTarget):
         """
         Does the same as parent's method but ensures incoming content will be
         decrypted.
+
+        @param data: The body of the HTTP response.
+        @type data: str
+        @param return_doc_cb: A callback to insert docs from target.
+        @type return_doc_cb: function
+        @param ensure_callback: A callback to ensure we have the correct
+            target_replica_uid, if it was just created.
+        @type ensure_callback: function
+
+        @return: The parsed sync stream.
+        @rtype: list of str
         """
         parts = data.splitlines()  # one at a time
         if not parts or parts[0] != '[':