Add more user API methods and improve documentation

Author: joowani

Diff for: README.rst

@@ -31,7 +31,7 @@
 |
 
 Welcome to the GitHub page for **python-arango**, a Python driver for
-`ArangoDB's REST API <https://www.arangodb.com/>`__.
+`ArangoDB <https://www.arangodb.com/>`__.
 
 Features
 ========
@@ -100,12 +100,12 @@ Here is a simple usage example:
 
     # Insert new documents into the collection
     students.insert({'name': 'jane', 'age': 19})
-    students.insert({'name': 'josh', 'age': 13})
+    students.insert({'name': 'josh', 'age': 18})
     students.insert({'name': 'jake', 'age': 21})
 
-    # Execute an AQL query and iterate through the result cursor
-    cursor = db.aql.execute('FOR s IN students RETURN s')
-    print(student['name'] for student in cursor)
+    # Execute an AQL query
+    result = db.aql.execute('FOR s IN students RETURN s')
+    print([student['name'] for student in result])
 
 Please read the full `API documentation`_ for more details!
 

Diff for: arango/client.py

@@ -154,14 +154,15 @@ def head(self, endpoint, params=None, headers=None, **_):
         :returns: the ArangoDB http response
         :rtype: arango.response.Response
         """
+        url = self._url_prefix + endpoint
         res = self._http.head(
-            url=self._url_prefix + endpoint,
+            url=url,
             params=params,
             headers=headers,
             auth=(self._username, self._password)
         )
         if self._logging:
-            logger.debug('HEAD {} {}'.format(endpoint, res.status_code))
+            logger.debug('HEAD {} {}'.format(url, res.status_code))
         return res
 
     def get(self, endpoint, params=None, headers=None, **_):
@@ -176,14 +177,15 @@ def get(self, endpoint, params=None, headers=None, **_):
         :returns: the ArangoDB http response
         :rtype: arango.response.Response
         """
+        url = self._url_prefix + endpoint
         res = self._http.get(
-            url=self._url_prefix + endpoint,
+            url=url,
             params=params,
             headers=headers,
             auth=(self._username, self._password)
         )
         if self._logging:
-            logger.debug('GET {} {}'.format(endpoint, res.status_code))
+            logger.debug('GET {} {}'.format(url, res.status_code))
         return res
 
     def put(self, endpoint, data=None, params=None, headers=None, **_):
@@ -200,15 +202,16 @@ def put(self, endpoint, data=None, params=None, headers=None, **_):
         :returns: the ArangoDB http response
         :rtype: arango.response.Response
         """
+        url = self._url_prefix + endpoint
         res = self._http.put(
-            url=self._url_prefix + endpoint,
+            url=url,
             data=sanitize(data),
             params=params,
             headers=headers,
             auth=(self._username, self._password)
         )
         if self._logging:
-            logger.debug('PUT {} {}'.format(endpoint, res.status_code))
+            logger.debug('PUT {} {}'.format(url, res.status_code))
         return res
 
     def post(self, endpoint, data=None, params=None, headers=None, **_):
@@ -225,15 +228,16 @@ def post(self, endpoint, data=None, params=None, headers=None, **_):
         :returns: the ArangoDB http response
         :rtype: arango.response.Response
         """
+        url = self._url_prefix + endpoint
         res = self._http.post(
-            url=self._url_prefix + endpoint,
+            url=url,
             data=sanitize(data),
             params=params,
             headers=headers,
             auth=(self._username, self._password)
         )
         if self._logging:
-            logger.debug('POST {} {}'.format(endpoint, res.status_code))
+            logger.debug('POST {} {}'.format(url, res.status_code))
         return res
 
     def patch(self, endpoint, data=None, params=None, headers=None, **_):
@@ -250,15 +254,16 @@ def patch(self, endpoint, data=None, params=None, headers=None, **_):
         :returns: the ArangoDB http response
         :rtype: arango.response.Response
         """
+        url = self._url_prefix + endpoint
         res = self._http.patch(
-            url=self._url_prefix + endpoint,
+            url=url,
             data=sanitize(data),
             params=params,
             headers=headers,
             auth=(self._username, self._password)
         )
         if self._logging:
-            logger.debug('PATCH {} {}'.format(endpoint, res.status_code))
+            logger.debug('PATCH {} {}'.format(url, res.status_code))
         return res
 
     def delete(self, endpoint, data=None, params=None, headers=None, **_):
@@ -275,13 +280,14 @@ def delete(self, endpoint, data=None, params=None, headers=None, **_):
         :returns: the ArangoDB http response
         :rtype: arango.response.Response
         """
+        url = self._url_prefix + endpoint
         res = self._http.delete(
-            url=self._url_prefix + endpoint,
+            url=url,
             data=sanitize(data),
             params=params,
             headers=headers,
             auth=(self._username, self._password)
         )
         if self._logging:
-            logger.debug('DELETE {} {}'.format(endpoint, res.status_code))
+            logger.debug('DELETE {} {}'.format(url, res.status_code))
         return res

Diff for: arango/connection.py

@@ -213,6 +213,10 @@ class UserDeleteError(ArangoError):
     """Failed to delete the user."""
 
 
+class UserAccessError(ArangoError):
+    """Failed to retrieve the names of databases user can access."""
+
+
 class UserGrantAccessError(ArangoError):
     """Failed to grant user access to a database."""
 

Diff for: arango/exceptions.py

@@ -1 +1 @@
-VERSION = '3.1.0'
+VERSION = '3.2.0'

Diff for: arango/version.py

@@ -3,20 +3,11 @@
 Server Administration
 ---------------------
 
-Python-arango provides operations for server administration and monitoring.
-For more information on the HTTP REST API visit this
-`page <https://docs.arangodb.com/HTTP/AdministrationAndMonitoring>`__.
+Python-arango provides operations for administration and monitoring. Some of
+these operations require root privileges (i.e. access to the ``_system``
+database).
 
-.. note::
-     Some operations in the example below require root privileges (i.e. the
-     user must have access to the ``_system`` database).
-
-.. warning::
-    `Replication <https://docs.arangodb.com/HTTP/Replications>`__ and
-    `sharding <https://docs.arangodb.com/HTTP/ShardingInterface>`__ are
-    currently not supported by python-arango.
-
-**Example:**
+Example:
 
 .. code-block:: python
 
@@ -60,5 +51,4 @@ For more information on the HTTP REST API visit this
     # Reload the routing collection (requires root access)
     client.reload_routing()
 
-
 Refer to :ref:`ArangoClient` class for more details.

Diff for: docs/admin.rst

@@ -14,12 +14,10 @@ AQL Queries
 ===========
 
 **AQL queries** can be invoked using the :ref:`AQL` class, which returns
-instances of :ref:`Cursor`. For more information on the syntax of AQL visit
-this `page <https://docs.arangodb.com/AQL/Fundamentals/Syntax.html>`__ and
-for more information on the HTTP REST API visit this
-`page <https://docs.arangodb.com/HTTP/AqlQuery>`__.
+instances of :ref:`Cursor`. For more information on AQL syntax visit this
+`page <https://docs.arangodb.com/AQL/Fundamentals/Syntax.html>`__.
 
-**Example:**
+Here is an example showing how AQL queries can be executed:
 
 .. code-block:: python
 
@@ -56,13 +54,10 @@ AQL User Functions
 **AQL user functions** are custom functions defined by the users to extend the
 functionality of AQL. Although python-arango provides ways to add, delete and
 retrieve user functions in Python, the functions themselves must be defined in
-Javascript.
+Javascript. For more general information on AQL user functions visit this
+`page <https://docs.arangodb.com/AQL/Extending>`__.
 
-For more information on the HTTP REST API for AQL user functions visit this
-`page <https://docs.arangodb.com/HTTP/AqlQueryCache>`__ and for more general
-information this `page <https://docs.arangodb.com/AQL/Extending>`__.
-
-**Example:**
+Here is an example showing how AQL functions can be created or deleted:
 
 .. code-block:: python
 
@@ -90,13 +85,10 @@ AQL Query Cache
 
 **AQL query cache** minimizes redundant calculation of the same query results.
 If it useful when read queries are called frequently and write queries are not.
-
-For more information on the HTTP REST API for AQL query caches visit this
-`page <https://docs.arangodb.com/HTTP/AqlQueryCache>`__ and for more general
-information visit this
+For more general information on AQL query caches visit this
 `page <https://docs.arangodb.com/AQL/ExecutionAndPerformance/QueryCache.html>`__.
 
-**Example:**
+Here is an example showing how the AQL query cache can be used:
 
 .. code-block:: python
 

Diff for: docs/aql.rst

@@ -3,55 +3,55 @@
 Async Execution
 ---------------
 
-Python-arango provides support for **asynchronous execution**, where incoming
+Python-arango provides support for **asynchronous executions**, where incoming
 requests are placed in a server-side, in-memory task queue and executed in a
 fire-and-forget style. The results of the requests can be retrieved later via
 :ref:`AsyncJob` objects.
 
-For more information on the HTTP REST API for retrieving asynchronous results
-visit this `page <https://docs.arangodb.com/HTTP/AsyncResultsManagement>`_.
+.. note::
+    The user should be mindful of the server-side memory while using async
+    executions with a large number of requests.
 
-**Example:**
+Here is an example showing how asynchronous executions can be used:
 
 .. code-block:: python
 
-    from arango import ArangoClient
+    from arango import ArangoClient, ArangoError
 
     client = ArangoClient()
     db = client.db('my_database')
 
-    # Initialize an AsyncExecution object to make asynchronous calls
+    # Initialize an AsyncExecution object to make asynchronous requests
     async = db.async(return_result=True)
 
     # AsyncExecution has a similar interface as that of Database, but
-    # AsyncJob objects are returned instead of results on API calls
+    # AsyncJob objects are returned instead of results on method calls
     job1 = async.collection('students').insert({'_key': 'Abby'})
     job2 = async.collection('students').insert({'_key': 'John'})
     job3 = async.collection('students').insert({'_key': 'John'})
     job4 = async.aql.execute('FOR d IN students RETURN d')
 
-    # Once the jobs finish, their results can be accessed before expiry
+    # Check the statuses of the asynchronous jobs
     for job in [job1, job2, job3, job4]:
-        print(job, job.status())
+        print(job.status())
 
     # Retrieve the result of a job
     result = job1.result()
-    assert isinstance(result, dict)
 
-    # If a job fails the error is returned as opposed to being raised
+    # If a job fails, the exception object is returned (not raised)
     result = job3.result()
-    assert isinstance(result, Exception)
+    assert isinstance(result, ArangoError)
 
     # Cancel a pending job
     job3.cancel()
 
-    # Clear a result of a job from the server
+    # Delete a result of a job from the server to free up resources
     job4.clear()
 
-    # List the first 100 jobs done
+    # List the first 100 jobs completed
     client.async_jobs(status='done', count=100)
 
-    # List the first 100 jobs pending in the queue
+    # List the first 100 jobs still pending in the queue
     client.async_jobs(status='pending', count=100)
 
     # Clear all jobs from the server

Diff for: docs/async.rst

@@ -3,51 +3,49 @@
 Batch Execution
 ---------------
 
-Python-arango provides support for **batch execution**, where incoming requests
-are queued in client-side memory and executed in a single HTTP call. After the
-batch is committed/executed, the results of the requests can be retrieved via
-:ref:`BatchJob` objects.
+Python-arango provides support for **batch executions**, where incoming
+requests are queued in client-side memory and executed in a single HTTP call.
+After the batch is committed, the results of the queued requests can be
+retrieved via :ref:`BatchJob` objects.
 
-For more information on the HTTP REST API for batch requests visit this
-`page <https://docs.arangodb.com/HTTP/BatchRequest>`_.
+.. note::
+    The user should be mindful of the client-side memory while using batch
+    executions with a large number of requests.
 
-
-**Example:**
+Here is an example showing how batch executions can be used:
 
 .. code-block:: python
 
-    from arango import ArangoClient
+    from arango import ArangoClient, ArangoError
 
     client = ArangoClient()
     db = client.db('my_database')
 
-    # Initialize a BatchExecution object via a context manager
+    # Initialize the BatchExecution object via a context manager
     with db.batch(return_result=True) as batch:
 
         # BatchExecution has a similar interface as that of Database, but
-        # BatchJob objects are returned instead of results on API calls
+        # BatchJob objects are returned instead of results on method calls
         job1 = batch.aql.execute('FOR d IN students RETURN d')
         job2 = batch.collection('students').insert({'_key': 'Abby'})
         job3 = batch.collection('students').insert({'_key': 'John'})
         job4 = batch.collection('students').insert({'_key': 'John'})
 
     # Upon exiting context, the queued requests are committed
     for job in [job1, job2, job3, job4]:
-        print(job, job.status())
+        print(job.status())
 
     # Retrieve the result of a job
-    print(job1.result())
+    job1.result()
 
-    # If a job fails the error is returned as opposed to being raised
-    assert isinstance(job4.result(), Exception)
+    # If a job fails, the exception object is returned (not raised)
+    assert isinstance(job4.result(), ArangoError)
 
     # BatchExecution can also be initialized without a context manager
     batch = db.batch(return_result=True)
     students = batch.collection('students')
     job5 = batch.collection('students').insert({'_key': 'Jake'})
     job6 = batch.collection('students').insert({'_key': 'Jill'})
-    batch.commit()  # The commit must be called manually
-
+    batch.commit()  # In which case the commit must be called explicitly
 
-Refer to :ref:`BatchExecution` and :ref:`BatchJob` classes for more
-details.
+Refer to :ref:`BatchExecution` and :ref:`BatchJob` classes for more details.