index.rst 3.08 KB
Newer Older
1
2
3
4
5
.. aiogremlin documentation master file, created by
   sphinx-quickstart on Sat Jun 27 13:50:06 2015.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

davebshow's avatar
davebshow committed
6
7
8
9
10
11
12
13
14
==========
aiogremlin
==========

:py:mod:`aiogremlin` is an asynchronous client for the `Tinkerpop 3 Gremlin Server`_
based on the `asyncio`_ and `aiohttp`_ libraries.

Releases
========
davebshow's avatar
davebshow committed
15
The latest release of :py:mod:`aiogremlin` is **0.1.1**.
davebshow's avatar
davebshow committed
16
17
18
19
20
21


Requirements
============

- Python 3.4
davebshow's avatar
davebshow committed
22
- Tinkerpop 3 Gremlin Server 3.0.0
davebshow's avatar
davebshow committed
23

davebshow's avatar
davebshow committed
24
Using Python 2? Checkout `gremlinrestclient`_.
davebshow's avatar
davebshow committed
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

Dependencies
============
- aiohttp 0.16.5
- aiowebsocketclient 0.0.3

To speed up serialization, you can also install `ujson`_. If not available,
aiogremlin will use the Python standard library :any:`json<json>` module.

- ujson 1.33


Installation
============
Install using pip::

    $ pip install aiogremlin


Getting Started
===============

:py:mod:`aiogremlin` has a simple API that is quite easy to use. However, as it relies
heavily on `asyncio`_ and `aiohttp`_, it is helpful to be familar with the
basics of these modules. If you're not, maybe check out the :py:mod:`asyncio`
documentation relating to the :ref:`event loop<asyncio-event-loop>` and the
concept of the :ref:`coroutine<coroutine>`. Also, I would recommend the
documentation relating to :py:mod:`aiohttp`'s
:ref:`websocket client<aiohttp-client-websockets>` and
:ref:`HTTP client<aiohttp-client-reference>` implementations.

Minimal Example
---------------
Submit a script to the Gremlin Server::

    >>> import asyncio
    >>> import aiogremlin
    >>> @asyncio.coroutine
    ... def go():
    ...     resp = yield from aiogremlin.submit("1 + 1")
    ...     return (yield from resp.get())
    >>> loop = asyncio.get_event_loop()
    >>> results = loop.run_until_complete(go())
    >>> results
    [Message(status_code=200, data=[2], message={}, metadata='')]


davebshow's avatar
davebshow committed
72
The above example demonstrates how :py:mod:`aiogremlin` uses the
davebshow's avatar
davebshow committed
73
74
75
76
:ref:`event loop<asyncio-event-loop>` to drive communication with the Gremlin
Server, but the **rest of examples are written as if they were run in a Python
interpreter**. In reality, **this isn't possible**, so remember, code *must*
be wrapped in functions and run with the :ref:`event loop<asyncio-event-loop>`.
77

davebshow's avatar
davebshow committed
78
79
80
81
82
83
84
85
86
87
88
Contribute
----------

Contributions are welcome. If you find a bug, or have a suggestion, please open
an issue on `Github`_. If you would like to make a pull request, please make
sure to add appropriate tests and run them::

    $ python setup.py test

In the future there will be CI and more info on contributing.

89
90
91
92
93
Contents:

.. toctree::
   :maxdepth: 3

davebshow's avatar
davebshow committed
94
   usage
95
96
97
98
99
100
101
102
103
   modules


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
davebshow's avatar
davebshow committed
104
105
106
107
108

.. _Tinkerpop 3 Gremlin Server: http://tinkerpop.incubator.apache.org/
.. _`asyncio`: https://docs.python.org/3/library/asyncio.html
.. _`aiohttp`: http://aiohttp.readthedocs.org/en/latest/
.. _`ujson`: https://pypi.python.org/pypi/ujson
davebshow's avatar
davebshow committed
109
.. _Github: https://github.com/davebshow/aiogremlin/issues
davebshow's avatar
davebshow committed
110
.. _`gremlinrestclient`: http://gremlinrestclient.readthedocs.org/en/latest/