Add logger parameter and update documentation on customer HTTP clients

Author: joowani

arango/async.py

@@ -41,7 +41,7 @@ def __init__(self, connection, return_result=True):
             password=connection.password,
             http_client=connection.http_client,
             database=connection.database,
-            enable_logging=connection.has_logging
+            enable_logging=connection.logging_enabled
         )
         self._return_result = return_result
         self._aql = AQL(self)

arango/batch.py

@@ -43,7 +43,7 @@ def __init__(self, connection, return_result=True, commit_on_error=False):
             password=connection.password,
             http_client=connection.http_client,
             database=connection.database,
-            enable_logging=connection.has_logging
+            enable_logging=connection.logging_enabled
         )
         self._id = uuid4()
         self._return_result = return_result

arango/client.py

@@ -15,26 +15,32 @@
 class ArangoClient(object):
     """ArangoDB client.
 
-    :param protocol: the internet transfer protocol (default: ``"http"``)
+    :param protocol: The internet transfer protocol (default: ``"http"``).
     :type protocol: str | unicode
-    :param host: ArangoDB host (default: ``"localhost"``)
+    :param host: ArangoDB server host (default: ``"localhost"``).
     :type host: str | unicode
-    :param port: ArangoDB port (default: ``8529``)
+    :param port: ArangoDB server port (default: ``8529``).
     :type port: int or str
-    :param username: ArangoDB username (default: ``"root"``)
+    :param username: ArangoDB default username (default: ``"root"``).
     :type username: str | unicode
-    :param password: ArangoDB password (default: ``""``)
-    :param verify: check the connection during initialization. Root privileges
-        are required to use this check.
+    :param password: ArangoDB default password (default: ``""``).
+    :param verify: Check the connection during initialization. Root privileges
+        are required to use this flag.
     :type verify: bool
-    :param http_client: the HTTP client object
+    :param http_client: Custom HTTP client to override the default one with.
+        Please refer to the API documentation for more details.
     :type http_client: arango.http_clients.base.BaseHTTPClient
-    :param enable_logging: log all API requests
+    :param enable_logging: Log all API requests as debug messages.
     :type enable_logging: bool
-    :param check_cert: verify SSL certificate when making HTTP requests
+    :param check_cert: Verify SSL certificate when making HTTP requests. This
+        flag is ignored if a custom **http_client** is specified.
     :type check_cert: bool
-    :param use_session: use session when making HTTP requests
+    :param use_session: Use session when making HTTP requests. This flag is
+        ignored if a custom **http_client** is specified.
     :type use_session: bool
+    :param logger: Custom logger to record the API requests with. The logger's
+        ``debug`` method is called.
+    :type logger: logging.Logger
     """
 
     def __init__(self,
@@ -47,7 +53,8 @@ def __init__(self,
                  http_client=None,
                  enable_logging=True,
                  check_cert=True,
-                 use_session=True):
+                 use_session=True,
+                 logger=None):
 
         self._protocol = protocol
         self._host = host
@@ -58,7 +65,7 @@ def __init__(self,
             use_session=use_session,
             check_cert=check_cert
         ) if http_client is None else http_client
-        self._logging = enable_logging
+        self._logging_enabled = enable_logging
         self._conn = Connection(
             protocol=self._protocol,
             host=self._host,
@@ -67,7 +74,8 @@ def __init__(self,
             username=self._username,
             password=self._password,
             http_client=self._http_client,
-            enable_logging=self._logging
+            enable_logging=self._logging_enabled,
+            logger=logger
         )
         self._wal = WriteAheadLog(self._conn)
 
@@ -156,7 +164,7 @@ def logging_enabled(self):
         :returns: whether logging is enabled
         :rtype: bool
         """
-        return self._logging
+        return self._logging_enabled
 
     @property
     def wal(self):
@@ -612,7 +620,7 @@ def database(self, name, username=None, password=None):
             username=username or self._username,
             password=password or self._password,
             http_client=self._http_client,
-            enable_logging=self._logging
+            enable_logging=self._logging_enabled
         ))
 
     def create_database(self, name, users=None, username=None, password=None):

arango/cluster.py

@@ -40,7 +40,7 @@ def __init__(self,
             password=connection.password,
             http_client=connection.http_client,
             database=connection.database,
-            enable_logging=connection.has_logging
+            enable_logging=connection.logging_enabled
         )
         self._shard_id = shard_id
         self._trans_id = transaction_id

arango/connection.py

@@ -5,8 +5,6 @@
 from arango.http_clients import DefaultHTTPClient
 from arango.utils import sanitize
 
-logger = logging.getLogger('arango')
-
 
 class Connection(object):
     """ArangoDB database connection.
@@ -37,7 +35,8 @@ def __init__(self,
                  username='root',
                  password='',
                  http_client=None,
-                 enable_logging=True):
+                 enable_logging=True,
+                 logger=None):
 
         self._protocol = protocol.strip('/')
         self._host = host.strip('/')
@@ -52,8 +51,9 @@ def __init__(self,
         self._username = username
         self._password = password
         self._http = http_client or DefaultHTTPClient()
-        self._logging = enable_logging
+        self._enable_logging = enable_logging
         self._type = 'standard'
+        self._logger = logger or logging.getLogger('arango')
 
     def __repr__(self):
         return '<ArangoDB connection to database "{}">'.format(self._database)
@@ -122,13 +122,26 @@ def http_client(self):
         return self._http
 
     @property
-    def has_logging(self):
+    def logging_enabled(self):
         """Return ``True`` if logging is enabled, ``False`` otherwise.
 
         :returns: whether logging is enabled or not
         :rtype: bool
         """
-        return self._logging
+        return self._enable_logging
+
+    @property
+    def has_logging(self):  # pragma: no cover
+        """Return ``True`` if logging is enabled, ``False`` otherwise.
+
+        :returns: whether logging is enabled or not
+        :rtype: bool
+
+        .. warning::
+            This property will be deprecated in the future.
+            Use **logging_enabled** instead.
+        """
+        return self._enable_logging
 
     @property
     def type(self):
@@ -182,8 +195,8 @@ def head(self, endpoint, params=None, headers=None, **_):
             headers=headers,
             auth=(self._username, self._password)
         )
-        if self._logging:
-            logger.debug('HEAD {} {}'.format(url, res.status_code))
+        if self._enable_logging:
+            self._logger.debug('HEAD {} {}'.format(url, res.status_code))
         return res
 
     def get(self, endpoint, params=None, headers=None, **_):
@@ -205,8 +218,8 @@ def get(self, endpoint, params=None, headers=None, **_):
             headers=headers,
             auth=(self._username, self._password)
         )
-        if self._logging:
-            logger.debug('GET {} {}'.format(url, res.status_code))
+        if self._enable_logging:
+            self._logger.debug('GET {} {}'.format(url, res.status_code))
         return res
 
     def put(self, endpoint, data=None, params=None, headers=None, **_):
@@ -231,8 +244,8 @@ def put(self, endpoint, data=None, params=None, headers=None, **_):
             headers=headers,
             auth=(self._username, self._password)
         )
-        if self._logging:
-            logger.debug('PUT {} {}'.format(url, res.status_code))
+        if self._enable_logging:
+            self._logger.debug('PUT {} {}'.format(url, res.status_code))
         return res
 
     def post(self, endpoint, data=None, params=None, headers=None, **_):
@@ -257,8 +270,8 @@ def post(self, endpoint, data=None, params=None, headers=None, **_):
             headers=headers,
             auth=(self._username, self._password)
         )
-        if self._logging:
-            logger.debug('POST {} {}'.format(url, res.status_code))
+        if self._enable_logging:
+            self._logger.debug('POST {} {}'.format(url, res.status_code))
         return res
 
     def patch(self, endpoint, data=None, params=None, headers=None, **_):
@@ -283,8 +296,8 @@ def patch(self, endpoint, data=None, params=None, headers=None, **_):
             headers=headers,
             auth=(self._username, self._password)
         )
-        if self._logging:
-            logger.debug('PATCH {} {}'.format(url, res.status_code))
+        if self._enable_logging:
+            self._logger.debug('PATCH {} {}'.format(url, res.status_code))
         return res
 
     def delete(self, endpoint, data=None, params=None, headers=None, **_):
@@ -309,6 +322,6 @@ def delete(self, endpoint, data=None, params=None, headers=None, **_):
             headers=headers,
             auth=(self._username, self._password)
         )
-        if self._logging:
-            logger.debug('DELETE {} {}'.format(url, res.status_code))
+        if self._enable_logging:
+            self._logger.debug('DELETE {} {}'.format(url, res.status_code))
         return res

arango/response.py

@@ -4,22 +4,24 @@
 class Response(object):
     """ArangoDB HTTP response.
 
-    Methods of :class:`arango.http_clients.base.BaseHTTPClient` must return
-    an instance of this.
+    Overridden methods of :class:`arango.http_clients.base.BaseHTTPClient` must
+    return instances of this.
 
-    :param method: the HTTP method
+    :param method: The HTTP method name (e.g. ``"post"``).
     :type method: str | unicode
-    :param url: the request URL
+    :param url: The request URL
+        (e.g. ``"http://localhost:8529/_db/_system/_api/database"``)
     :type url: str | unicode
-    :param http_code: the HTTP status code
+    :param headers: A dict-like mapping object containing the HTTP headers.
+        Must allow case-insensitive key access.
+    :type headers: collections.MutableMapping
+    :param http_code: The HTTP status code.
     :type http_code: int
-    :param http_text: the HTTP status text
+    :param http_text: The HTTP status text. This is used only for printing
+        error messages, and has no specification to follow.
     :type http_text: str | unicode
-    :param body: the HTTP response body
+    :param body: The HTTP response body.
     :type body: str | unicode | dict
-
-    .. note::
-        This class is meant to be used internally only.
     """
 
     __slots__ = (

arango/transaction.py

@@ -49,7 +49,7 @@ def __init__(self,
             password=connection.password,
             http_client=connection.http_client,
             database=connection.database,
-            enable_logging=connection.has_logging
+            enable_logging=connection.logging_enabled
         )
         self._id = uuid4()
         self._actions = ['db = require("internal").db']

arango/version.py

@@ -1 +1 @@
-VERSION = '3.11.0'
+VERSION = '3.12.0'

docs/classes.rst

@@ -45,6 +45,15 @@ AQLQueryCache
 .. autoclass:: arango.aql.AQLQueryCache
     :members:
 
+.. _BaseHTTPClient:
+
+BaseHTTPClient
+==============
+
+.. autoclass:: arango.http_clients.base.BaseHTTPClient
+    :members:
+
+
 .. _BatchExecution:
 
 BatchExecution