Revamp the library for 4.0.0.

Author: joowani

.gitignore

@@ -8,3 +8,5 @@
 *.coverage
 .cache/
 tests/__pycache__/
+*.DS_Store
+venv

.travis.yml

@@ -1,20 +1,21 @@
-language: python
 sudo: false
+language: python
 python:
     - 2.7
     - 3.4
     - 3.5
     - 3.6
+services:
+    - docker
 before_install:
-    - sh scripts/setup_arangodb.sh
+    - docker run --name arango -d -p 8529:8529 -e ARANGO_ROOT_PASSWORD=passwd arangodb/arangodb:3.3.8
+    - docker cp tests/static/service.zip arango:/tmp/service.zip
 install:
-    - pip install coverage
-    - pip install pytest
-    - pip install pytest-cov
-    - pip install python-coveralls
-    - python setup.py install
+    - pip install flake8 mock pytest pytest-cov python-coveralls sphinx
+    - pip install .
 script:
-    - py.test --cov-report= --cov=arango tests/
+    - python -m flake8
+    - python -m sphinx -b doctest docs build
+    - py.test --complete -s -v --cov=arango
 after_success:
     - coveralls
-    - pkill -9 -f arango

MANIFEST.in

@@ -0,0 +1 @@
+include README.rst LICENSE

README.rst

@@ -32,22 +32,28 @@
 
 |
 
-Welcome to the GitHub page for **python-arango**, a Python driver for
-`ArangoDB <https://www.arangodb.com/>`__.
+Welcome to the GitHub page for **python-arango**, a Python driver for ArangoDB_.
+
+Announcements
+=============
+
+- Python-arango version `4.0.0`_ is now out!
+- Please see the releases_ page for details on latest updates.
 
 Features
 ========
 
-- Clean, Pythonic interface
+- Clean Pythonic interface
 - Lightweight
 - High ArangoDB REST API coverage
 
 Compatibility
 =============
 
-- Python versions 2.7.x, 3.4.x, 3.5.x and 3.6.x are supported
-- Latest version of python-arango (3.x) supports ArangoDB 3.x only
-- Older versions of python-arango support ArangoDB 1.x ~ 2.x only
+- Python versions 2.7, 3.4, 3.5 and 3.6 are supported
+- Python-arango 4.x supports ArangoDB 3.3+ (recommended)
+- Python-arango 3.x supports ArangoDB 3.0 ~ 3.2 only
+- Python-arango 2.x supports ArangoDB 1.x ~ 2.x only
 
 Installation
 ============
@@ -65,10 +71,7 @@ To install the latest version directly from GitHub_:
 
     ~$ pip install -e git+git@github.com:joowani/python-arango.git@master#egg=python-arango
 
-You may need to use ``sudo`` depending on your environment setup.
-
-.. _PyPi: https://pypi.python.org/pypi/python-arango
-.. _GitHub: https://github.com/joowani/python-arango
+You may need to use ``sudo`` depending on your environment.
 
 Getting Started
 ===============
@@ -79,79 +82,98 @@ Here is a simple usage example:
 
     from arango import ArangoClient
 
-    # Initialize the client for ArangoDB
-    client = ArangoClient(
-        protocol='http',
-        host='localhost',
-        port=8529,
-        username='root',
-        password='',
-        enable_logging=True
-    )
+    # Initialize the client for ArangoDB.
+    client = ArangoClient(protocol='http', host='localhost', port=8529)
+
+    # Connect to "_system" database as root user.
+    sys_db = client.db('_system', username='root', password='passwd')
 
-    # Create a new database named "my_database"
-    db = client.create_database('my_database')
+    # Create a new database named "test".
+    sys_db.create_database('test')
 
-    # Create a new collection named "students"
+    # Connect to "test" database as root user.
+    db = client.db('test', username='root', password='passwd')
+
+    # Create a new collection named "students".
     students = db.create_collection('students')
 
-    # Add a hash index to the collection
+    # Add a hash index to the collection.
     students.add_hash_index(fields=['name'], unique=True)
 
-    # Insert new documents into the collection
-    students.insert({'name': 'jane', 'age': 19})
+    # Insert new documents into the collection.
+    students.insert({'name': 'jane', 'age': 39})
     students.insert({'name': 'josh', 'age': 18})
-    students.insert({'name': 'jake', 'age': 21})
+    students.insert({'name': 'judy', 'age': 21})
 
-    # Execute an AQL query
-    result = db.aql.execute('FOR s IN students RETURN s')
-    print([student['name'] for student in result])
+    # Execute an AQL query and iterate through the result cursor.
+    cursor = db.aql.execute('FOR doc IN students RETURN doc')
+    student_names = [document['name'] for document in cursor]
 
 
-Here is another example involving graphs:
+Here is another example with graphs:
 
 .. code-block:: python
 
     from arango import ArangoClient
 
-    client = ArangoClient()
+    # Initialize the client for ArangoDB.
+    client = ArangoClient(protocol='http', host='localhost', port=8529)
+
+    # Connect to "test" database as root user.
+    db = client.db('test', username='root', password='passwd')
 
-    # Create a new graph
-    graph = client.db('my_database').create_graph('my_graph')
+    # Create a new graph named "school".
+    graph = db.create_graph('school')
+
+    # Create vertex collections for the graph.
     students = graph.create_vertex_collection('students')
-    courses = graph.create_vertex_collection('courses')
-    takes = graph.create_edge_definition(
-        name='takes',
-        from_collections=['students'],
-        to_collections=['courses']
+    lectures = graph.create_vertex_collection('lectures')
+
+    # Create an edge definition (relation) for the graph.
+    register = graph.create_edge_definition(
+        edge_collection='register',
+        from_vertex_collections=['students'],
+        to_vertex_collections=['lectures']
     )
 
-    # Insert vertices
+    # Insert vertex documents into "students" (from) vertex collection.
     students.insert({'_key': '01', 'full_name': 'Anna Smith'})
     students.insert({'_key': '02', 'full_name': 'Jake Clark'})
     students.insert({'_key': '03', 'full_name': 'Lisa Jones'})
 
-    courses.insert({'_key': 'MAT101', 'title': 'Calculus'})
-    courses.insert({'_key': 'STA101', 'title': 'Statistics'})
-    courses.insert({'_key': 'CSC101', 'title': 'Algorithms'})
-
-    # Insert edges
-    takes.insert({'_from': 'students/01', '_to': 'courses/MAT101'})
-    takes.insert({'_from': 'students/01', '_to': 'courses/STA101'})
-    takes.insert({'_from': 'students/01', '_to': 'courses/CSC101'})
-    takes.insert({'_from': 'students/02', '_to': 'courses/MAT101'})
-    takes.insert({'_from': 'students/02', '_to': 'courses/STA101'})
-    takes.insert({'_from': 'students/03', '_to': 'courses/CSC101'})
-
-    # Traverse the graph in outbound direction, breadth-first
-    traversal_results = graph.traverse(
+    # Insert vertex documents into "lectures" (to) vertex collection.
+    lectures.insert({'_key': 'MAT101', 'title': 'Calculus'})
+    lectures.insert({'_key': 'STA101', 'title': 'Statistics'})
+    lectures.insert({'_key': 'CSC101', 'title': 'Algorithms'})
+
+    # Insert edge documents into "register" edge collection.
+    register.insert({'_from': 'students/01', '_to': 'lectures/MAT101'})
+    register.insert({'_from': 'students/01', '_to': 'lectures/STA101'})
+    register.insert({'_from': 'students/01', '_to': 'lectures/CSC101'})
+    register.insert({'_from': 'students/02', '_to': 'lectures/MAT101'})
+    register.insert({'_from': 'students/02', '_to': 'lectures/STA101'})
+    register.insert({'_from': 'students/03', '_to': 'lectures/CSC101'})
+
+    # Traverse the graph in outbound direction, breadth-first.
+    result = graph.traverse(
         start_vertex='students/01',
-        strategy='bfs',
-        direction='outbound'
+        direction='outbound',
+        strategy='breadthfirst'
     )
-    print(traversal_results['vertices'])
 
-Please read the full `API documentation`_ for more details!
+Check out the documentation_ for more details.
 
-.. _API documentation:
+Contributing
+============
+
+Please take a look at this page_ before submitting a pull request. Thanks!
+
+.. _ArangoDB: https://www.arangodb.com
+.. _4.0.0: https://github.com/joowani/python-arango/releases/tag/4.0.0
+.. _releases: https://github.com/joowani/python-arango/releases
+.. _PyPi: https://pypi.python.org/pypi/python-arango
+.. _GitHub: https://github.com/joowani/python-arango
+.. _documentation:
     http://python-driver-for-arangodb.readthedocs.io/en/master/index.html
+.. _page:
+    http://python-driver-for-arangodb.readthedocs.io/en/master/contributing.html

arango/__init__.py

@@ -1,2 +1,3 @@
-from arango.client import ArangoClient
-from arango.client import ArangoError
+from arango.client import ArangoClient  # noqa: F401
+from arango.exceptions import *         # noqa: F401 F403
+from arango.http import *               # noqa: F401 F403

arango/api.py

@@ -1,40 +1,58 @@
 from __future__ import absolute_import, unicode_literals
 
-from functools import wraps
+__all__ = ['APIWrapper']
 
 
 class APIWrapper(object):
-    """ArangoDB API wrapper base class.
+    """Base class for API wrappers.
 
-    This class is meant to be used internally only.
+    :param connection: HTTP connection.
+    :type connection: arango.connection.Connection
+    :param executor: API executor.
+    :type executor: arango.executor.Executor
     """
 
-    def __getattribute__(self, attr):
-        method = object.__getattribute__(self, attr)
-        conn = object.__getattribute__(self, '_conn')
-
-        if not getattr(method, 'api_method', False):
-            return method
-
-        @wraps(method)
-        def wrapped_method(*args, **kwargs):
-            request, handler = method(*args, **kwargs)
-            return conn.handle_request(request, handler)
-        return wrapped_method
-
-
-def api_method(method):
-    """Decorator used to mark ArangoDB API methods.
-
-    Methods decorated by this should return two things:
-
-    - An instance of :class:`arango.request.Request`
-    - A handler that takes an instance of :class:`arango.response.Response`
-
-    :param method: the method to wrap
-    :type method: callable
-    :returns: the wrapped method
-    :rtype: callable
-    """
-    setattr(method, 'api_method', True)
-    return method
+    def __init__(self, connection, executor):
+        self._conn = connection
+        self._executor = executor
+        self._is_transaction = self.context == 'transaction'
+
+    @property
+    def db_name(self):
+        """Return the name of the current database.
+
+        :return: Database name.
+        :rtype: str | unicode
+        """
+        return self._conn.db_name
+
+    @property
+    def username(self):
+        """Return the username.
+
+        :returns: Username.
+        :rtype: str | unicode
+        """
+        return self._conn.username
+
+    @property
+    def context(self):
+        """Return the API execution context.
+
+        :return: API execution context. Possible values are "default", "async",
+            "batch" and "transaction".
+        :rtype: str | unicode
+        """
+        return self._executor.context
+
+    def _execute(self, request, response_handler):
+        """Execute an API per execution context.
+
+        :param request: HTTP request.
+        :type request: arango.request.Request
+        :param response_handler: HTTP response handler.
+        :type response_handler: callable
+        :return: API execution result.
+        :rtype: str | unicode | bool | int | list | dict
+        """
+        return self._executor.execute(request, response_handler)