Commit d451d85d authored by davebshow's avatar davebshow
Browse files

working on docs

parent 17b44331
......@@ -86,7 +86,10 @@ class GremlinClient:
@asyncio.coroutine
def close(self):
"""Close client. If client has not been detached from underlying
"""
:ref:`coroutine<coroutine>` method.
Close client. If client has not been detached from underlying
ws_connector, this coroutinemethod closes the latter as well."""
if self._closed:
return
......@@ -105,6 +108,23 @@ class GremlinClient:
op=None, processor=None, binary=True, session=None,
timeout=None):
"""
:ref:`coroutine<coroutine>` method.
Submit a script to the Gremlin Server.
:param str gremlin: Gremlin script to submit to server.
:param dict bindings: A mapping of bindings for Gremlin script.
:param str lang: Language of scripts submitted to the server.
"gremlin-groovy" by default
:param str op: Gremlin Server op argument. "eval" by default.
:param str processor: Gremlin Server processor argument. "" by default.
:param float timeout: timeout for establishing connection (optional).
Values ``0`` or ``None`` mean no timeout
:param str session: Session id (optional). Typically a uuid
:param loop: :ref:`event loop<asyncio-event-loop>` If param is ``None``
`asyncio.get_event_loop` is used for getting default event loop
(optional)
:returns: :py:class:`aiogremlin.client.GremlinResponse` object
"""
lang = lang or self.lang
op = op or self.op
......@@ -129,6 +149,24 @@ class GremlinClient:
def execute(self, gremlin, *, bindings=None, lang=None, session=None,
op=None, processor=None, binary=True, timeout=None):
"""
:ref:`coroutine<coroutine>` method.
Submit a script to the Gremlin Server and get the result.
:param str gremlin: Gremlin script to submit to server.
:param dict bindings: A mapping of bindings for Gremlin script.
:param str lang: Language of scripts submitted to the server.
"gremlin-groovy" by default
:param str op: Gremlin Server op argument. "eval" by default.
:param str processor: Gremlin Server processor argument. "" by default.
:param float timeout: timeout for establishing connection (optional).
Values ``0`` or ``None`` mean no timeout
:param str session: Session id (optional). Typically a uuid
:param loop: :ref:`event loop<asyncio-event-loop>` If param is ``None``
`asyncio.get_event_loop` is used for getting default event loop
(optional)
:returns: :py:class:`list` of
:py:class:`aiogremlin.subprotocol.Message`
"""
lang = lang or self.lang
op = op or self.op
......@@ -170,6 +208,7 @@ class GremlinClientSession(GremlinClient):
@property
def session(self):
"""Getter setter property for session id."""
return self._session
@session.setter
......@@ -177,6 +216,14 @@ class GremlinClientSession(GremlinClient):
self._session = value
def reset_session(self, session=None):
"""
Reset session id.
:param str session: A unique session id (optional). If None, an id will
be generated using :py:func:`uuid.uuid4`.
:returns: New session id.
"""
if session is None:
session = str(uuid.uuid4())
self._session = session
......@@ -201,20 +248,29 @@ class GremlinResponse:
@property
def stream(self):
"""Read-only property used to get data from the stream in chunks.
:returns: :py:class:`aiogremlin.client.ResponseStream`"""
return self._stream
@property
def session(self):
"""Session ID (if applicable)."""
return self._session
@asyncio.coroutine
def get(self):
"""
:ref:`coroutine<coroutine>` method.
Get all messages from the stream.
:returns: :py:class:`list` :py:class:`aiogremlin.subprotocol.Message`
"""
return (yield from self._run())
@asyncio.coroutine
def _run(self):
"""
"""
results = []
while True:
message = yield from self._stream.read()
......@@ -244,12 +300,18 @@ class GremlinResponseStream:
@asyncio.coroutine
def read(self):
"""Read a message from the stream"""
"""
:ref:`coroutine<coroutine>` method
Read a message from the stream.
:returns: :py:class:`aiogremlin.subprotocol.Message`
"""
if self._stream.at_eof():
yield from self._ws.release()
message = None
else:
asyncio.async(self._ws.receive(), loop=self._loop)
asyncio.Task(self._ws.receive(), loop=self._loop)
try:
message = yield from self._stream.read()
except RequestError:
......@@ -268,10 +330,15 @@ def submit(gremlin, *,
timeout=None,
session=None,
loop=None):
"""Submit a script to the Gremlin Server.
"""
:ref:`coroutine<coroutine>`
Submit a script to the Gremlin Server.
:param str gremlin: The Gremlin script.
:param str url: url for Gremlin Server (optional). 'ws://localhost:8182/'
by default
:param dict bindings: A mapping of bindings for Gremlin script.
:param str lang: Language of scripts submitted to the server.
"gremlin-groovy" by default
:param str op: Gremlin Server op argument. "eval" by default.
......@@ -282,6 +349,7 @@ def submit(gremlin, *,
:param loop: :ref:`event loop<asyncio-event-loop>` If param is ``None``,
`asyncio.get_event_loop` is used for getting default event loop
(optional)
:returns: :py:class:`aiogremlin.client.GremlinResponse` object
"""
if loop is None:
......
......@@ -15,7 +15,9 @@ __all__ = ('GremlinClientWebSocketResponse',)
class GremlinClientWebSocketResponse(ClientWebSocketResponse):
"""Wraps :py:class:`aiohttp.websocket_client.ClientWebSocketResponse`
with minimal added functionality for the Gremln Server use case.
"""
def __init__(self, reader, writer, protocol, response, timeout, autoclose,
autoping, loop):
ClientWebSocketResponse.__init__(self, reader, writer, protocol,
......@@ -26,6 +28,11 @@ class GremlinClientWebSocketResponse(ClientWebSocketResponse):
@property
def parser(self):
"""
Read-only property.
:returns: :py:class:`aiohttp.parsers.StreamParser`
"""
return self._parser
@asyncio.coroutine
......@@ -74,6 +81,7 @@ class GremlinClientWebSocketResponse(ClientWebSocketResponse):
return True
def send(self, message, *, binary=True):
"""Send a message to the server."""
if binary:
method = self.send_bytes
else:
......@@ -89,6 +97,11 @@ class GremlinClientWebSocketResponse(ClientWebSocketResponse):
@asyncio.coroutine
def receive(self):
"""
:ref:`coroutine<coroutine>` method
Receive a message from the server and push it into the parser.
"""
msg = yield from super().receive()
if msg.tp == aiohttp.MsgType.binary:
self.parser.feed_data(msg.data.decode())
......
......@@ -10,7 +10,7 @@ except ImportError:
from aiogremlin.exceptions import RequestError, GremlinServerError
__all__ = ("GremlinWriter", "gremlin_response_parser")
__all__ = ("GremlinWriter", "gremlin_response_parser", "Message")
Message = collections.namedtuple(
......@@ -43,8 +43,8 @@ def gremlin_response_parser(out, buf):
class GremlinWriter:
def __init__(self, connection):
self._connection = connection
def __init__(self, ws):
self.ws = ws
def write(self, gremlin, bindings=None, lang="gremlin-groovy", op="eval",
processor="", session=None, binary=True,
......@@ -59,8 +59,8 @@ class GremlinWriter:
message = json.dumps(message)
if binary:
message = self._set_message_header(message, mime_type)
self._connection.send(message, binary=binary)
return self._connection
self.ws.send(message, binary=binary)
return self.ws
@staticmethod
def _set_message_header(message, mime_type):
......
......@@ -22,6 +22,9 @@ aiogremlin.client module
aiogremlin.connector module
---------------------------
This module is based on :py:class:`aiohttp.client.ClientSession` and
:py:class:`aiohttp.connector.BaseConnector`.
.. automodule:: aiogremlin.connector
:members:
:undoc-members:
......@@ -43,7 +46,6 @@ aiogremlin.response module
:members:
:undoc-members:
:show-inheritance:
:inherited-members:
aiogremlin.subprotocol module
-----------------------------
......
......@@ -12,7 +12,7 @@ based on the `asyncio`_ and `aiohttp`_ libraries.
Releases
========
The latest release of ``aiogremlin`` is **0.0.11**.
The latest release of :py:mod:`aiogremlin` is **0.0.11**.
Requirements
......@@ -68,12 +68,23 @@ Submit a script to the Gremlin Server::
[Message(status_code=200, data=[2], message={}, metadata='')]
The above example demonstrates how ``aiogremlin`` uses the
The above example demonstrates how :py:mod:`aiogremlin` uses the
: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>`.
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.
Contents:
.. toctree::
......@@ -94,3 +105,4 @@ Indices and tables
.. _`asyncio`: https://docs.python.org/3/library/asyncio.html
.. _`aiohttp`: http://aiohttp.readthedocs.org/en/latest/
.. _`ujson`: https://pypi.python.org/pypi/ujson
.. _Github: https://github.com/davebshow/aiogremlin/issues
......@@ -37,6 +37,8 @@ read the chunked responses one at a time::
lang="gremlin-groovy", op="eval", processor="",
timeout=None, session=None, loop=None):
:ref:`coroutine<coroutine>`
Submit a script to the Gremlin Server.
:param str gremlin: Gremlin script to submit to server.
......@@ -129,7 +131,7 @@ point to different endpoints::
.. method:: close()
:ref:`coroutine<coroutine>` method.
:ref:`coroutine<coroutine>` method
Close client. If client has not been detached from underlying
ws_connector, this coroutinemethod closes the latter as well.
......@@ -141,6 +143,10 @@ point to different endpoints::
.. method:: submit(gremlin, *, bindings=None, lang=None, op=None,
processor=None, binary=True, session=None, timeout=None)
:ref:`coroutine<coroutine>` method
Submit a script to the Gremlin Server.
:param str gremlin: Gremlin script to submit to server.
:param str url: url for Gremlin Server (optional). 'ws://localhost:8182/'
......@@ -165,6 +171,10 @@ point to different endpoints::
.. method:: execute(gremlin, *, bindings=None, lang=None, op=None,
processor=None, binary=True, session=None, timeout=None)
:ref:`coroutine<coroutine>` method
Submit a script to the Gremlin Server and get a list of the responses.
:param str gremlin: Gremlin script to submit to server.
:param str url: url for Gremlin Server (optional). 'ws://localhost:8182/'
......@@ -184,10 +194,30 @@ point to different endpoints::
:param str session: Session id (optional). Typically a uuid
:returns: :py:class:`list` of messages
:returns: :py:class:`list` of :py:class:`aiogremlin.subprotocol.Message`
Using Gremlin Server sessions with :py:class:`GremlinClientSession`.
--------------------------------------------------------------------
The Gremlin Server supports sessions to maintain state across server
messages. Although this is not the preffered method, it is quite useful in
certain situations. For convenience, :py:mod:`aiogremlin` provides the class
:py:class:`aiogremlin.client.GremlinClientSession`. It is basically the
same as the :py:class:`GremlinClient`, but it uses sessions by default::
>>> client = aiogremlin.GremlinClientSession()
>>> client.session
'533f15fb-dc2e-4768-86c5-5b136b380b65'
>>> client.reset_session()
'd7bdb0da-d4ec-4609-8ac0-df9713803d43'
That's basically it! For more info, see the
:ref:`Client Reference Guide<aiogremlin-client-reference>`
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment