The Python driver for Gel

.. image:: https://github.com/geldata/gel-python/workflows/Tests/badge.svg?event=push&branch=master
:target: https://github.com/geldata/gel-python/actions

.. image:: https://img.shields.io/pypi/v/gel.svg
:target: https://pypi.python.org/pypi/gel

.. image:: https://img.shields.io/badge/join-github%20discussions-green
:target: https://github.com/geldata/gel/discussions

gel-python is the official Gel driver for Python.
It provides both blocking IO and asyncio implementations.

The library requires Python 3.9 or later.

Documentation

The project documentation can be found
here <https://docs.geldata.com/reference/clients/python#gel-python-intro>_.

Installation

The library is available on PyPI. Use pip to install it::

$ pip install gel

Basic Usage

.. code-block:: python

import datetime
import gel

def main():
    client = gel.create_client()
    # Create a User object type
    client.execute('''
        CREATE TYPE User {
            CREATE REQUIRED PROPERTY name -> str;
            CREATE PROPERTY dob -> cal::local_date;
        }
    ''')

    # Insert a new User object
    client.query('''
        INSERT User {
            name := <str>$name,
            dob := <cal::local_date>$dob
        }
    ''', name='Bob', dob=datetime.date(1984, 3, 1))

    # Select User objects.
    user_set = client.query(
        'SELECT User {name, dob} FILTER .name = <str>$name', name='Bob')
    # *user_set* now contains
    # Set{Object{name := 'Bob', dob := datetime.date(1984, 3, 1)}}

    # Close the client.
    client.close()

if __name__ == '__main__':
    main()

Using the `models` generator

We provide a models generator that lets you build queries programmatically, and generate Pydantic models directly from your schema.

To use, run the following command:

.. code-block:: bash

$ gel generate py/models

This will find your Python project and add a models package to it. Then you can use the generated models to build queries and mutate instances of your objects directly.

.. code-block:: python

import datetime
from models import User, std
from gel import create_client

def main():
    client = create_client()

    # Create a new User instance and save it to the database
    bob = User(name='Bob', dob=datetime.date(1984, 3, 1))
    client.save(bob)

    # Select all Users
    users = client.query(User)

    # Select all users with names like "Bob"
    bob_like = client.query(User.filter(lambda u: std.ilike(u.name, '%bob%')))

    # Update an object
    bob.name = 'Robert'
    client.save(bob)

    # Delete an object
    client.execute(User.filter(id=bob.id).delete())

    client.close()

if __name__ == '__main__':
    main()

Development

Instructions for installing Gel and gel-python locally can be found at
docs.geldata.com/resources/guides/contributing/code <https://docs.geldata.com/resources/guides/contributing/code>_.

To run the test suite, run $ python setup.py test.