[refactor] kaliy's review and pep8 fixes

README with information about latest change, missing docs and licenses,
variable naming and pep8.

4 files changed, 25 insertions, 19 deletions

diff --git a/common/src/leap/soledad/common/command.py b/common/src/leap/soledad/common/command.py
index 978cec91..811bf135 100644
--- a/common/src/leap/soledad/common/command.py
+++ b/common/src/leap/soledad/common/command.py
@@ -24,26 +24,27 @@ Utility to sanitize and run shell commands.
 import subprocess
 
 
-def exec_validated_cmd(cmd, args, validator=None):
+def exec_validated_cmd(cmd, argument, validator=None):
     """
-    Executes cmd, validating args with validator.
+    Executes cmd, validating argument with a validator function.
 
     :param cmd: command.
     :type dbname: str
-    :param args: arguments.
-    :type args: str
-    :param validator: optional function to validate args
+    :param argument: argument.
+    :type argument: str
+    :param validator: optional function to validate argument
     :type validator: function
 
     :return: exit code and stdout or stderr (if code != 0)
     :rtype: (int, str)
     """
-    if validator and not validator(args):
+    if validator and not validator(argument):
         return 1, "invalid argument"
     command = cmd.split(' ')
-    command.append(args)
+    command.append(argument)
     try:
-        process = subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        process = subprocess.Popen(command, stdout=subprocess.PIPE,
+                                   stderr=subprocess.PIPE)
     except OSError, e:
         return 1, e
     (out, err) = process.communicate()
diff --git a/common/src/leap/soledad/common/couch.py b/common/src/leap/soledad/common/couch.py
index d9ed5026..4c5f6400 100644
--- a/common/src/leap/soledad/common/couch.py
+++ b/common/src/leap/soledad/common/couch.py
@@ -435,7 +435,7 @@ class CouchDatabase(CommonBackend):
             self._set_replica_uid(replica_uid)
         if ensure_ddocs:
             self.ensure_ddocs_on_db()
-            self.ensure_security()
+            self.ensure_security_ddoc()
         self._cache = None
 
     @property
@@ -468,10 +468,15 @@ class CouchDatabase(CommonBackend):
                         getattr(ddocs, ddoc_name)))
                 self._database.save(ddoc)
 
-    def ensure_security(self):
+    def ensure_security_ddoc(self):
         """
         Make sure that only soledad user is able to access this database as
-        a member.
+        an unprivileged member, meaning that administration access will
+        be forbidden even inside an user database.
+        The goal is to make sure that only the lowest access level is given
+        to the unprivileged CouchDB user set on the server process.
+        This is achieved by creating a _security design document, see:
+        http://docs.couchdb.org/en/latest/api/database/security.html
         """
         security = self._database.security
         security['members'] = {'names': ['soledad'], 'roles': []}
@@ -1386,12 +1391,9 @@ class CouchSyncTarget(CommonSyncTarget):
             source_replica_transaction_id)
 
 
-DB_NAME_MASK = "^user-[a-f0-9]+$"
-
-
 def is_db_name_valid(name):
     """
-    Validate a user database using DB_NAME_MASK.
+    Validate a user database using a regular expression.
 
     :param name: database name.
     :type name: str
@@ -1399,7 +1401,8 @@ def is_db_name_valid(name):
     :return: boolean for name vailidity
     :rtype: bool
     """
-    return re.match(DB_NAME_MASK, name) is not None
+    db_name_regex = "^user-[a-f0-9]+$"
+    return re.match(db_name_regex, name) is not None
 
 
 class CouchServerState(ServerState):
diff --git a/common/src/leap/soledad/common/tests/test_command.py b/common/src/leap/soledad/common/tests/test_command.py
index af4903eb..420f91ae 100644
--- a/common/src/leap/soledad/common/tests/test_command.py
+++ b/common/src/leap/soledad/common/tests/test_command.py
@@ -50,4 +50,6 @@ class ExecuteValidatedCommandTest(unittest.TestCase):
     def test_return_status_code_number_on_failure(self):
         status, out = exec_validated_cmd("ls", "user-bebacafe")
         self.assertEquals(status, 2)
-        self.assertIn('ls: cannot access user-bebacafe: No such file or directory\n', out)
+        self.assertIn(
+            'ls: cannot access user-bebacafe: No such file or directory\n',
+            out)
diff --git a/common/src/leap/soledad/common/tests/test_couch.py b/common/src/leap/soledad/common/tests/test_couch.py
index 3622bb56..d1a07a3a 100644
--- a/common/src/leap/soledad/common/tests/test_couch.py
+++ b/common/src/leap/soledad/common/tests/test_couch.py
@@ -1504,11 +1504,11 @@ class CouchDatabaseExceptionsTests(CouchDBTestCase):
     def test_ensure_security_doc(self):
         """
         Ensure_security creates a _security ddoc to ensure that only soledad
-        will have member access to a db.
+        will have the lowest privileged access to an user db.
         """
         self.create_db(ensure=False)
         self.assertFalse(self.db._database.security)
-        self.db.ensure_security()
+        self.db.ensure_security_ddoc()
         security_ddoc = self.db._database.security
         self.assertIn('admins', security_ddoc)
         self.assertFalse(security_ddoc['admins']['names'])