From e6ca75a9e2a7a634f92ae54238df7d86100fbdab Mon Sep 17 00:00:00 2001 From: drebs Date: Mon, 8 Apr 2013 12:15:30 -0300 Subject: Add a LOT of docstrings. --- src/leap/soledad/shared_db.py | 103 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 98 insertions(+), 5 deletions(-) (limited to 'src/leap/soledad/shared_db.py') 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 . + -@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) -- cgit v1.2.3