Update documentation

README.rst

@@ -14,7 +14,7 @@
     :target: https://badge.fury.io/py/python-arango
     :alt: Package Version
 
-.. image:: https://img.shields.io/badge/python-2.7%2C%203.4%2C%203.5%2C%203.6-blue.svg
+.. image:: https://img.shields.io/badge/python-2.7%2C%203.4%2C%203.5%2C%203.6%2C%203.7-blue.svg
     :target: https://github.com/joowani/python-arango
     :alt: Python Versions
 

arango/collection.py

@@ -1592,8 +1592,13 @@ def insert_many(self,
                     return_old=False):
         """Insert multiple documents.
 
-        If inserting a document fails, the exception object is placed in the
-        result list instead of document metadata.
+        .. note::
+
+            If inserting a document fails, the exception is not raised but
+            returned as an object in the result list. It is up to you to
+            inspect the list to determine which documents were inserted
+            successfully (returns document metadata) and which were not
+            (returns exception object).
 
         :param documents: List of new documents to insert. If they contain the
             "_key" or "_id" fields, the values are used as the keys of the new
@@ -1746,8 +1751,13 @@ def update_many(self,
                     silent=False):
         """Update multiple documents.
 
-        If updating a document fails, the exception object is placed in the
-        result list instead of document metadata.
+        .. note::
+
+            If updating a document fails, the exception is not raised but
+            returned as an object in the result list. It is up to you to
+            inspect the list to determine which documents were updated
+            successfully (returns document metadata) and which were not
+            (returns exception object).
 
         :param documents: Partial or full documents with the updated values.
             They must contain the "_id" or "_key" fields.
@@ -1953,8 +1963,13 @@ def replace_many(self,
                      silent=False):
         """Replace multiple documents.
 
-        If replacing a document fails, the exception object is placed in the
-        result list instead of document metadata.
+        .. note::
+
+            If replacing a document fails, the exception is not raised but
+            returned as an object in the result list. It is up to you to
+            inspect the list to determine which documents were replaced
+            successfully (returns document metadata) and which were not
+            (returns exception object).
 
         :param documents: New documents to replace the old ones with. They must
             contain the "_id" or "_key" fields. Edge documents must also have
@@ -2142,8 +2157,13 @@ def delete_many(self,
                     silent=False):
         """Delete multiple documents.
 
-        If deleting a document fails, the exception object is placed in the
-        result list instead of document metadata.
+        .. note::
+
+            If deleting a document fails, the exception is not raised but
+            returned as an object in the result list. It is up to you to
+            inspect the list to determine which documents were deleted
+            successfully (returns document metadata) and which were not
+            (returns exception object).
 
         :param documents: Document IDs, keys or bodies. Document bodies must
             contain the "_id" or "_key" fields.

docs/cluster.rst

@@ -0,0 +1,51 @@
+Clusters
+--------
+
+Python-arango provides support for ArangoDB clusters. For more information on
+clusters, refer to `ArangoDB manual`_.
+
+.. _ArangoDB manual: https://docs.arangodb.com
+
+Coordinators
+============
+
+To connect to multiple ArangoDB hosts (e.g. coordinators) you must provide
+either a list of host strings or a comma-separated string during client
+initialization.
+
+**Example:**
+
+.. testcode::
+
+    from arango import ArangoClient
+
+    # Single instance
+    client = ArangoClient(hosts='http://localhost:8529')
+
+    # Multiple instances (option 1: list)
+    client = ArangoClient(hosts=['http://host1:8529', 'http://host2:8529'])
+
+    # Multiple instances (option 2: comma-separated string)
+    client = ArangoClient(hosts='http://host1:8529,http://host2:8529')
+
+Load-Balancing
+==============
+
+There are two load-balancing strategies available: "roundrobin" and "random"
+(defaults to "roundrobin" if not specified).
+
+**Example:**
+
+.. testcode::
+
+    from arango import ArangoClient
+
+    hosts = ['http://host1:8529', 'http://host2:8529']
+
+    # Round-robin
+    client = ArangoClient(hosts=hosts, host_resolver='roundrobin')
+
+    # Random
+    client = ArangoClient(hosts=hosts, host_resolver='random')
+
+See :ref:`ArangoClient` for API specification.

docs/http.rst

@@ -4,16 +4,17 @@ HTTP Clients
 Python-arango lets you define your own HTTP client for sending requests to
 ArangoDB server. The default implementation uses the requests_ library.
 
-Your HTTP client must inherit :class:`arango.http.HTTPClient` and implement its
-two abstract methods:
+Your HTTP client must inherit :class:`arango.http.HTTPClient` and implement the
+following abstract methods:
 
 * :func:`arango.http.HTTPClient.create_session`
 * :func:`arango.http.HTTPClient.send_request`
 
-The **create_session** method must return a session object (called per host)
-which will be stored in python-arango client. The **send_request** method must
-use the session to send a HTTP request, and return a fully populated instance
-of :class:`arango.response.Response`.
+The **create_session** method must return a `requests.Session`_ instance per
+connected host (coordinator). The session objects are stored in the client.
+
+The **send_request** method must use the session to send an HTTP request, and
+return a fully populated instance of :class:`arango.response.Response`.
 
 For example, let's say your HTTP client needs:
 
@@ -100,8 +101,7 @@ Then you would inject your client as follows:
         http_client=CustomHTTPClient()
     )
 
-For more information on how to configure a ``requests.Session`` object, refer
-to `requests documentation`_.
+See `requests.Session`_ for more details on how to create and manage sessions.
 
 .. _requests: https://github.com/requests/requests
-.. _requests documentation: http://docs.python-requests.org/en/master/user/advanced/#session-objects
+.. _requests.Session: http://docs.python-requests.org/en/master/user/advanced/#session-objects

docs/index.rst

@@ -74,6 +74,7 @@ Contents
     errors
     logging
     http
+    cluster
     serializer
     contributing
     specs

docs/threading.rst

@@ -1,11 +1,29 @@
-Threading
----------
+Multithreading
+--------------
+
+There are a few things you should consider before using python-arango in a
+multithreaded (or multiprocess) architecture.
+
+Stateful Objects
+================
 
 Instances of the following classes are considered *stateful*, and should not be
-shared across multiple threads without locks in place:
+accessed across multiple threads without locks in place:
 
 * :ref:`BatchDatabase` (see :doc:`batch`)
 * :ref:`BatchJob` (see :doc:`batch`)
 * :ref:`Cursor` (see :doc:`cursor`)
 
-The rest of python-arango is safe to use in multi-threaded environments.
+
+HTTP Sessions
+=============
+
+When :ref:`ArangoClient` is initialized, a `requests.Session`_ instance is
+created per ArangoDB host connected. HTTP requests to a host are sent using
+only its corresponding session. For more information on how to override this
+behaviour, see :doc:`http`.
+
+Note that a `requests.Session`_ object may not always be thread-safe. Always
+research your use case!
+
+.. _requests.Session: http://docs.python-requests.org/en/master/user/advanced/#session-objects