Another giant refactoring

Author: CoderJayO

README.md

@@ -40,7 +40,7 @@ Databases
 ---------
 
 ```python
-# Listing the databases
+# List all databases
 conn.databases
 conn.databases["user"]
 conn.databases["system"]
@@ -51,7 +51,7 @@ conn.create_database("my_database")
 # Delete a database
 conn.delete_database("my_database")
 
-# Retrieving information on the default ("_system") database
+# Retrieve information on the default ("_system") database
 conn.name           # equivalent to conn.db("_system").name
 conn.collections    # equivalent to conn.db("_system").collections
 conn.id             # equivalent to conn.db("_system").id
@@ -60,7 +60,7 @@ conn.is_system      # equivalent to conn.db("_system").is_system
 conn.is_edge        # equivalent to conn.db("_system").is_system
 conn.is_volatile    # equivalent to conn.db("_system").is_system
 
-# Get information on a specific database
+# Retrieve information on a specific database
 conn.db("db01").name
 conn.db("db01").collections
 conn.db("db02").id
@@ -80,9 +80,44 @@ conn.db("my_database").*
 
 User Management
 ---------------
+```python
+
+# List all users
+conn.users
+
+# Create a new user
+conn.create_user("username", "password1")
+
+# Update a user
+conn.update_user("username", "password2", change_password=True)
+
+# Replace a user
+conn.replace_user("username", "password3")
+
+# Delete a user
+conn.delete_user("username")
+```
 
 Monitoring
 ----------
+```python
+
+# Retrieve global server log
+conn.read_log(level="debug")
+
+# Create a new user
+conn.create_user("username", "password1")
+
+# Update a user
+conn.update_user("username", "password2", change_password=True)
+
+# Replace a user
+conn.replace_user("username", "password3")
+
+# Delete a user
+conn.delete_user("username")
+```
+
 
 AQL Functions
 -------------
@@ -134,16 +169,16 @@ my_database.collections["user"]
 my_database.collecitons["system"]
 my_database.collections["all"]
 
-# Create a new collection
+# Create a collection
 my_database.create_collection("new_collection")
 
-# Create a new edge collection
-my_database.create_collection("new_ecol", is_edge=True)
+# Create an edge collection
+my_database.create_collection("new_ecollection", is_edge=True)
 
 # Rename a collection
 my_database.rename_collection("new_collection", "my_collection")
 
-# Delete a collection from the database
+# Delete a collection
 my_database.delete_collection("my_collection")
 
 # Retrieve collection information

arango/__init__.py

@@ -1,15 +1,21 @@
-"""ArangoDB Top-Level API."""
+"""ArangoDB's Top-Level API."""
 
 from arango.database import Database
 from arango.api import API
 from arango.exceptions import *
 from arango.constants import HTTP_OK, LOG_LEVELS
-from arango.clients import DefaultArangoClient
+from arango.clients import DefaultClient
 from arango.utils import uncamelify
 
 
 class Arango(object):
-    """Wrapper for ArangoDB's top-level API."""
+    """Wrapper for ArangoDB's top-level APIs:
+
+    1. Database Management
+    2. User Management
+    3. Administration & Monitoring
+    4. Miscellaneous Functions
+    """
 
     def __init__(self, protocol="http", host="localhost", port=8529,
                  username="root", password="", client=None):
@@ -26,8 +32,8 @@ def __init__(self, protocol="http", host="localhost", port=8529,
         :param password: ArangoDB password (default: '')
         :type password: str
         :param client: HTTP client for this wrapper to use
-        :type client: arango.clients.base.BaseArangoClient or None
-        :raises: ArangoConnectionError
+        :type client: arango.clients.base.BaseClient or None
+        :raises: ConnectionError
         """
         self.protocol = protocol
         self.host = host
@@ -40,7 +46,7 @@ def __init__(self, protocol="http", host="localhost", port=8529,
             self.client = client
         else:
             client_init_data = {"auth": (self.username, self.password)}
-            self.client = DefaultArangoClient(client_init_data)
+            self.client = DefaultClient(client_init_data)
 
         # Initialize the ArangoDB API wrapper object
         self.api = API(
@@ -55,7 +61,7 @@ def __init__(self, protocol="http", host="localhost", port=8529,
         # Check the connection by requesting a header
         res = self.api.head("/_api/version")
         if res.status_code not in HTTP_OK:
-            raise ArangoConnectionError(res)
+            raise ConnectionError(res)
 
         # Cache for Database objects
         self._database_cache = {}
@@ -91,6 +97,10 @@ def _invalidate_database_cache(self):
                 )
             )
 
+    ###########################
+    # Miscellaneous Functions #
+    ###########################
+
     @property
     def version(self):
         """Return the version of ArangoDB.
@@ -104,9 +114,9 @@ def version(self):
             raise VersionGetError(res)
         return res.obj["version"]
 
-    #############
-    # Databases #
-    #############
+    #######################
+    # Database Management #
+    #######################
 
     @property
     def databases(self):
@@ -182,13 +192,13 @@ def delete_database(self, name, safe_delete=False):
                 raise DatabaseDeleteError(res)
         self._invalidate_database_cache()
 
-    #########
-    # Users #
-    #########
+    ###################
+    # User Management #
+    ###################
 
     @property
     def users(self):
-        """Return the details on all users.
+        """Return details on all users.
 
         :returns: a dictionary mapping user names to their information
         :rtype: dict
@@ -209,6 +219,26 @@ def users(self):
 
     def create_user(self, username, password, active=None, extra=None,
                     change_password=None):
+        """Create a new user.
+
+        if ``change_password`` is set to true, the only operation allowed by
+        the user will be ``self.replace_user`` or ``self.update_user``. All
+        other operations executed by the user will result in an HTTP 403.
+
+        :param username: the name of the user
+        :type username: str
+        :param password: the user password
+        :type password: str
+        :param active: whether the user is active
+        :type active: bool or None
+        :param extra: any extra data about the user
+        :type extra: dict or None
+        :param change_password: whether the user must change the password
+        :type change_password: bool or None
+        :returns: the information about the new user
+        :rtype: dict
+        :raises: UserCreateError
+        """
         data = {"user": username, "passwd": password}
         if active is not None:
             data["active"] = active
@@ -228,6 +258,26 @@ def create_user(self, username, password, active=None, extra=None,
 
     def update_user(self, username, password=None, active=None, extra=None,
                     change_password=None):
+        """Update an existing user.
+
+        if ``change_password`` is set to true, the only operation allowed by
+        the user will be ``self.replace_user`` or ``self.update_user``. All
+        other operations executed by the user will result in an HTTP 403.
+
+        :param username: the name of the existing user
+        :type username: str
+        :param password: the user password
+        :type password: str
+        :param active: whether the user is active
+        :type active: bool or None
+        :param extra: any extra data about the user
+        :type extra: dict or None
+        :param change_password: whether the user must change the password
+        :type change_password: bool or None
+        :returns: the information about the updated user
+        :rtype: dict
+        :raises: UserUpdateError
+        """
         data = {}
         if password is not None:
             data["password"] = password
@@ -251,6 +301,26 @@ def update_user(self, username, password=None, active=None, extra=None,
 
     def replace_user(self, username, password, active=None, extra=None,
                      change_password=None):
+        """Replace an existing user.
+
+        if ``change_password`` is set to true, the only operation allowed by
+        the user will be ``self.replace_user`` or ``self.update_user``. All
+        other operations executed by the user will result in an HTTP 403.
+
+        :param username: the name of the existing user
+        :type username: str
+        :param password: the user password
+        :type password: str
+        :param active: whether the user is active
+        :type active: bool or None
+        :param extra: any extra data about the user
+        :type extra: dict or None
+        :param change_password: whether the user must change the password
+        :type change_password: bool or None
+        :returns: the information about the replaced user
+        :rtype: dict
+        :raises: UserReplaceError
+        """
         data = {"user": username, "password": password}
         if active is not None:
             data["active"] = active
@@ -271,15 +341,25 @@ def replace_user(self, username, password, active=None, extra=None,
         }
 
     def delete_user(self, username, safe_delete=False):
+        """Delete an existing user.
+
+        :param username: the name of the user
+        :type username: str
+        :param safe_delete: ignores HTTP 404 if set to True
+        :type safe_delete: bool
+        :returns: True if the operation succeeds
+        :rtype: bool
+        :raises: UserDeleteError
+        """
         res = self.api.delete("/_api/user/{user}".format(user=username))
         if res.status_code not in HTTP_OK:
             if not (res.status_code == 404 and safe_delete):
                 raise UserDeleteError(res)
         return True
 
-    ##############
-    # Monitoring #
-    ##############
+    ###############################
+    # Administration & Monitoring #
+    ###############################
 
     def read_log(self, upto=None, level=None, start=None, size=None,
                  offset=None, search=None, sort=None):

arango/api.py

@@ -1,14 +1,14 @@
-"""ArangoDB Request Client."""
+"""Wrapper for making REST API calls to ArangoDB."""
 
 import json
 
 from arango.constants import DEFAULT_DATABASE
-from arango.clients import DefaultArangoClient
+from arango.clients import DefaultClient
 from arango.utils import is_string
 
 
 class API(object):
-    """A simple wrapper for making REST API calls to ArangoDB.
+    """Wrapper object which makes REST API calls to ArangoDB.
 
     :param protocol: the internet transfer protocol (default: 'http')
     :type protocol: str
@@ -23,7 +23,7 @@ class API(object):
     :param database: the ArangoDB database to point the API calls to
     :type database: str
     :param client: HTTP client for this wrapper to use
-    :type client: arango.clients.base.BaseArangoClient or None
+    :type client: arango.clients.base.BaseClient or None
     """
 
     def __init__(self, protocol="http", host="localhost", port=8529,
@@ -44,7 +44,7 @@ def __init__(self, protocol="http", host="localhost", port=8529,
             self.client = client
         else:
             client_init_data = {"auth": (self.username, self.password)}
-            self.client = DefaultArangoClient(client_init_data)
+            self.client = DefaultClient(client_init_data)
 
     def head(self, path, params=None, headers=None):
         """Call a HEAD method in ArangoDB's REST API.
@@ -168,3 +168,25 @@ def delete(self, path, params=None, headers=None):
             headers=headers,
             auth=(self.username, self.password)
         )
+
+    def options(self, path, data=None, params=None, headers=None):
+        """Call an OPTIONS method in ArangoDB's REST API.
+
+        :param path: the API path (e.g. '/_api/version')
+        :type path: str
+        :param data: the request payload
+        :type data: str or dict or None
+        :param params: the request parameters
+        :type params: dict or None
+        :param headers: the request headers
+        :type headers: dict or None
+        :returns: the ArangoDB http response
+        :rtype: arango.response.Response
+        """
+        return self.client.options(
+            url=self.url_prefix + path,
+            data=data if is_string(data) else json.dumps(data),
+            params=params,
+            headers=headers,
+            auth=(self.username, self.password)
+        )

arango/clients/__init__.py

@@ -1 +1 @@
-from arango.clients.default import DefaultArangoClient
+from arango.clients.default import DefaultClient

arango/clients/base.py

@@ -3,7 +3,7 @@
 from abc import ABCMeta, abstractmethod
 
 
-class BaseArangoClient(object):
+class BaseClient(object):
     """Base class for ArangoDB clients.
 
     The methods MUST return an ``arango.response.Response`` object.
@@ -118,3 +118,22 @@ def delete(self, url, params=None, headers=None, auth=None):
         :rtype: arango.response.Response
         """
         raise NotImplementedError
+
+    @abstractmethod
+    def options(self, url, data=None, params=None, headers=None, auth=None):
+        """HTTP OPTIONS method.
+
+        :param url: request URL
+        :type url: str
+        :param data: request payload
+        :type data: str or dict or None
+        :param params: request parameters
+        :type params: dict or None
+        :param headers: request headers
+        :type headers: dict or None
+        :param auth: username and password tuple
+        :type auth: tuple or None
+        :returns: ArangoDB http response object
+        :rtype: arango.response.Response
+        """
+        raise NotImplementedError