Goblin - Async Python toolkit for the TinkerPop 3 Gremlin Server

Goblin is an asynchronous Python toolkit for the TinkerPop 3 Gremlin Server. In order to leverage Python’s support for asynchronous programming paradigms, Goblin is implemented using the async/await syntax introduced in Python 3.5, and does not support earlier Python versions. Goblin is built on top of aiogremlin and provides full compatibility with the aiogremlin GLV and driver.

Main features:

  • High level asynchronous Object Graph Mapper (OGM)
  • Integration with the official gremlin-python Gremlin Language Variant (GLV) - now provided by aiogremlin
  • Native Python support for asynchronous programing including coroutines, iterators, and context managers as specified in PEP 492
  • Asynchronous Python driver for the Gremlin Server - now provided by aiogremlin


The latest release of goblin is 2.0.0.


  • Python 3.5+
  • TinkerPop 3.2.4


  • aiogremlin 3.2.4
  • inflection 0.3.1


Install using pip:

$ pip install goblin

The Basics


Define custom vertex/edge classes using the provided base classes, properties, and data types:

>>> from goblin import element, properties

>>> class Person(element.Vertex):
...     name = properties.Property(properties.String)
...     age = properties.Property(properties.Integer)

>>> class Knows(element.Edge):
...     notes = properties.Property(properties.String, default='N/A')

Create a Goblin App and register the element classes:

>>> from goblin import Goblin

>>> app = loop.run_until_complete(
...     Goblin.open(loop))
>>> app.register(Person, Knows)

Other than user defined properties, elements provide no interface. Use a Session object to interact with the database:

>>> async def go(app):
...     session = await app.session()
...     leif = Person()
...     leif.name = 'Leif'
...     leif.age = 28
...     jon = Person()
...     jon.name = 'Jonathan'
...     works_with = Knows(leif, jon)
...     session.add(leif, jon, works_with)
...     await session.flush()
...     result = await session.g.E(works_with.id).next()
...     assert result is works_with
...     people = session.traversal(Person)  # element class based traversal source
...     async for person in people:
...         print(person)

>>> loop.run_until_complete(go(app))
# <__main__.Person object at 0x7fba0b7fa6a0>
# <__main__.Person object at 0x7fba0b7fae48>

Note that a Goblin session does not necessarily correspond to a Gremlin Server session. Instead, all elements created using a session are ‘live’ in the sense that if the results of a traversal executed against the session result in different property values for an element, that element will be updated to reflect these changes.

For more information on using the OGM, see the OGM docs

Gremlin Language Variant

Generate and submit Gremlin traversals in native Python:

>>> from goblin import DriverRemoteConnection  # alias for aiogremlin.DriverRemoteConnection
>>> from goblin import Graph  # alias for aiogremlin.Graph

>>> 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()
...    await remote_connection.close()
...    return vertices

>>> results = loop.run_until_complete(go(loop))
>>> results
# [v[1], v[2], v[3], v[4], v[5], v[6]]

>>> loop.run_until_complete(go(g))
# {'properties': {'name': [{'value': 'Leif', 'id': 3}]}, 'label': 'developer', 'id': 2, 'type': 'vertex'}

For more information on using the Graph, see the aiogremlin documentation or the GLV docs


Submit scripts and bindings to the Gremlin Server:

>>> import asyncio
>>> from goblin import Cluster  # alias for aiogremlin.Cluster

>>> loop = asyncio.get_event_loop()

>>> async def go(loop):
...     cluster = await Cluster.open('ws://localhost:8182/gremlin', loop)
...     client = await cluster.connect()
...     resp = await client.submit(
...         "g.addV('developer').property(k1, v1)",
...         bindings={'k1': 'name', 'v1': 'Leif'})
...         async for msg in resp:
...             print(msg)
...      await cluster.close()

>>> loop.run_until_complete(go(loop))

For more information on using the driver, see the aiogremlin documentation or the Driver docs


Indices and tables