GQL: Python GraphQL Client Library

Introduction

GQL is a GraphQL Client Python library intended to help Python application make GraphQL API call while enjoying the advantages that come with GraphQL.

• Strongly Typed response objects (dynamically created in build time to match your query)
• Query Validation that checks your code's queries against the GraphQL server's schema.

Installation

Simply install from PyPi:

pip install gql-next

Then go to your project folder and run gql init

Quick Start

gql works by parsing query files (**/*.graphql by default) into their own Python module where an class, named after the operation defined in the file, allows you to make that query and get a typed response.

For example, given the following file get_film.graphql file:

query GetFilm($id: ID!) {
  film(id: $id) {
    title
    director
  }
}

A get_film.py will be created defining a GetFilm class:

# AUTOGENERATED file. Do not Change!
from typing import Any, Callable, Mapping, List
from enum import Enum
from dataclasses import dataclass
from dataclasses_json import dataclass_json
from gql.clients import Client, AsyncIOClient


@dataclass_json
@dataclass
class GetFilm:
    @dataclass_json
    @dataclass
    class GetFilmData:
        @dataclass_json
        @dataclass
        class Film:
            title: str
            director: str
        film: Film = None

    data: GetFilmData = None
    errors: Any = None

    @classmethod
    def execute(cls, id: str, on_before_callback: Callable[[Mapping[str, str], Mapping[str, str]], None] = None) -> GetFilm:
        ...

    @classmethod
    async def execute_async(cls, id: str, on_before_callback: Callable[[Mapping[str, str], Mapping[str, str]], None] = None) -> GetFilm:
        ...

Allowing you to make the GraphQL query:

from .get_film import GetFilm

result = GetFilm.execute('meaning_of_life')
film = result.data.film

Important notes:

• Operations defined in graphql query must be named so that we can name the relevant Python Class which you can then import in your code

How it works

The gql client

gql init

Initializes a project to use GQL as client - writes a .gql.json configuration file.

gql run

Run through your project's files and compile GraphQL queries into into Python types.

gql watch

Useful during development. Listen to file changes in your project's folder and continuously builds GraphQL queries as they change. This allows you to:

• Immediately verify query changes you make are valid.
• Enjoy your IDE's autocomplete features on GraphQL auto-generated objects while developing as watch will auto-update them as you change queries.

Sponsors