index.rst 3.29 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
==========
aiogremlin
==========

davebshow's avatar
davebshow committed
10
11
12
13
14
15
16
17
18
19
20
`aiogremlin` is a port of the official `Gremlin-Python` designed for integration with
event loop based asynchronous Python networking libraries, including `asyncio`_,
`aiohttp`_, and `tornado`_. It uses the `async/await` syntax introduced
in `PEP 492`_, and is therefore Python 3.5+ only.

`aiogremlin` tries to follow `Gremlin-Python` as closely as possible both in terms
of API and implementation. It is regularly rebased against the official Apache Git
repository, and will be released according to the `TinkerPop`_ release schedule.

Note that this *NOT* an official Apache project component, it is a
*THIRD PARTY PACKAGE!*
davebshow's avatar
davebshow committed
21
22
23

Releases
========
davebshow's avatar
davebshow committed
24
The latest release of :py:mod:`aiogremlin` is **3.2.5**.
davebshow's avatar
davebshow committed
25
26
27
28
29


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

davebshow's avatar
davebshow committed
30
- Python 3.5+
davebshow's avatar
davebshow committed
31
- TinkerPop 3.2.5
davebshow's avatar
davebshow committed
32
33
34
35


Dependencies
============
davebshow's avatar
davebshow committed
36
37
- aiohttp 1.3.3
- PyYAML 3.12
davebshow's avatar
davebshow committed
38
39
40
41
42
43
44
45
46



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

    $ pip install aiogremlin

davebshow's avatar
davebshow committed
47
48
49
50
For this version, a separate install of gremlinpython is required::

    $ pip install gremlinpython --no-deps

davebshow's avatar
davebshow committed
51
52
53
54
55

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

:py:mod:`aiogremlin` has a simple API that is quite easy to use. However, as it relies
davebshow's avatar
davebshow committed
56
57
58
59
heavily on `asyncio`_ and `aiohttp`_, it is helpful to be familiar with the
basics of these modules.

:py:mod:`aiogremlin` is *very* similar to Gremlin-Python, except it is all async, all the time.
davebshow's avatar
davebshow committed
60
61
62
63
64
65

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

    >>> import asyncio
davebshow's avatar
davebshow committed
66
67
    >>> from aiogremlin import DriverRemoteConnection, Graph

davebshow's avatar
davebshow committed
68
    >>> loop = asyncio.get_event_loop()
davebshow's avatar
davebshow committed
69
70
71
72
73
74
75
76
77

    >>> async def go(loop):
    ...    remote_connection = await DriverRemoteConnection.open(
    ...        'ws://localhost:8182/gremlin', 'g')
    ...    g = Graph().traversal().withRemote(remote_connection)
    ...    vertices = await g.V().toList()
    ...    return vertices

    >>> results = loop.run_until_complete(go(loop))
davebshow's avatar
davebshow committed
78
    >>> results
davebshow's avatar
davebshow committed
79
    # [v[1], v[2], v[3], v[4], v[5], v[6]]
davebshow's avatar
davebshow committed
80
81


davebshow's avatar
davebshow committed
82
The above example demonstrates how :py:mod:`aiogremlin` uses the
davebshow's avatar
davebshow committed
83
84
85
: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*
davebshow's avatar
davebshow committed
86
be wrapped in a coroutine and run with the :ref:`event loop<asyncio-event-loop>`.
87

davebshow's avatar
davebshow committed
88
89
90
91
92
93
94
95
96
97
98
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.

99
100
101
102
103
Contents:

.. toctree::
   :maxdepth: 3

davebshow's avatar
davebshow committed
104
   usage
105
106
107
108
109
110
111
112
113
   modules


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

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
davebshow's avatar
davebshow committed
114

davebshow's avatar
davebshow committed
115
.. _TinkerPop: http://tinkerpop.apache.org/
davebshow's avatar
davebshow committed
116
117
.. _`asyncio`: https://docs.python.org/3/library/asyncio.html
.. _`aiohttp`: http://aiohttp.readthedocs.org/en/latest/
davebshow's avatar
davebshow committed
118
119
.. _`Tornado`: http://www.tornadoweb.org/en/stable/
.. _`PEP 492`: https://www.python.org/dev/peps/pep-0492/
davebshow's avatar
davebshow committed
120
.. _Github: https://github.com/davebshow/aiogremlin/issues