summaryrefslogtreecommitdiff
path: root/src/leap/soledad/shared_db.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/shared_db.py
parentd2d35a449beb05799bd68a7679f58382f8599152 (diff)
Add a LOT of docstrings.
Diffstat (limited to 'src/leap/soledad/shared_db.py')
-rw-r--r--src/leap/soledad/shared_db.py103
1 files changed, 98 insertions, 5 deletions
diff --git a/src/leap/soledad/shared_db.py b/src/leap/soledad/shared_db.py
index 275ed269..5fce8ac2 100644
--- a/src/leap/soledad/shared_db.py
+++ b/src/leap/soledad/shared_db.py
@@ -1,8 +1,23 @@
# -*- coding: utf-8 -*-
-"""
-Created on Tue Mar 5 18:46:38 2013
+# shared_db.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/>.
+
-@author: drebs
+"""
+A shared database for storing/retrieving encrypted key material.
"""
try:
@@ -10,6 +25,7 @@ try:
except ImportError:
import json # noqa
+
from u1db import errors
from u1db.remote import http_database
@@ -44,8 +60,21 @@ class SoledadSharedDatabase(http_database.HTTPDatabase):
@staticmethod
def open_database(url, create, token=None):
+ # TODO: users should not be able to create the shared database, so we
+ # have to remove this from here in the future.
"""
Open a Soledad shared database.
+
+ @param url: URL of the remote database.
+ @type url: str
+ @param create: Should the database be created if it does not already
+ exist?
+ @type create: bool
+ @param token: An authentication token for accessing the shared db.
+ @type token: str
+
+ @return: The shared database in the given url.
+ @rtype: SoledadSharedDatabase
"""
db = SoledadSharedDatabase(url, token=token)
db.open(create)
@@ -55,12 +84,27 @@ class SoledadSharedDatabase(http_database.HTTPDatabase):
def delete_database(url):
"""
Dummy method that prevents from deleting shared database.
+
+ @raise: This will always raise an Unauthorized exception.
+
+ @param url: The database URL.
+ @type url: str
"""
raise Unauthorized("Can't delete shared database.")
def __init__(self, url, document_factory=None, creds=None, token=None):
"""
Initialize database with auth token and encryption powers.
+
+ @param url: URL of the remote database.
+ @type url: str
+ @param document_factory: A factory for U1BD documents.
+ @type document_factory: u1db.Document
+ @param creds: A tuple containing the authentication method and
+ credentials.
+ @type creds: tuple
+ @param token: An authentication token for accessing the shared db.
+ @type token: str
"""
self._token = token
super(SoledadSharedDatabase, self).__init__(url, document_factory,
@@ -70,8 +114,28 @@ class SoledadSharedDatabase(http_database.HTTPDatabase):
content_type=None, auth=True):
"""
Perform token-based http request.
+
+ @param method: The HTTP method for the request.
+ @type method: str
+ @param url_parts: A list with extra parts for the URL.
+ @type url_parts: list
+ @param params: Parameters to be added as query string.
+ @type params: dict
+ @param body: The body of the request (must be JSON serializable).
+ @type body: object
+ @param content_type: The content-type of the request.
+ @type content_type: str
+ @param auth: Should the request be authenticated?
+ @type auth: bool
+
+ @raise u1db.errors.Unavailable: If response status is 503.
+ @raise u1db.errors.HTTPError: If response status is neither 200, 201
+ or 503
+
+ @return: The headers and body of the HTTP response.
+ @rtype: tuple
"""
- # add the auth-token as a request parameter
+ # add `auth-token` as a request parameter
if auth:
if not self._token:
raise NoTokenForAuth()
@@ -87,7 +151,27 @@ class SoledadSharedDatabase(http_database.HTTPDatabase):
def _request_json(self, method, url_parts, params=None, body=None,
content_type=None, auth=True):
"""
- Perform token-based http request.
+ Perform token-based http request and deserialize the JSON results.
+
+ @param method: The HTTP method for the request.
+ @type method: str
+ @param url_parts: A list with extra parts for the URL.
+ @type url_parts: list
+ @param params: Parameters to be added as query string.
+ @type params: dict
+ @param body: The body of the request (must be JSON serializable).
+ @type body: object
+ @param content_type: The content-type of the request.
+ @type content_type: str
+ @param auth: Should the request be authenticated?
+ @type auth: bool
+
+ @raise u1db.errors.Unavailable: If response status is 503.
+ @raise u1db.errors.HTTPError: If response status is neither 200, 201
+ or 503
+
+ @return: The headers and body of the HTTP response.
+ @rtype: tuple
"""
# allow for token-authenticated requests.
res, headers = self._request(method, url_parts,
@@ -98,6 +182,15 @@ class SoledadSharedDatabase(http_database.HTTPDatabase):
def get_doc_unauth(self, doc_id):
"""
Modified method to allow for unauth request.
+
+ This is the only (public) way to make an unauthenticaded request on
+ the shared database.
+
+ @param doc_id: The document id.
+ @type doc_id: str
+
+ @return: The requested document.
+ @rtype: Document
"""
db = http_database.HTTPDatabase(self._url.geturl(),
document_factory=self._factory)