Compose GraphQL queries by composing Python types

pip install graphql-dsl

Let's take a manually written GraphQL query from the official docs:

query {
    hero {
        name
    }
    droid(id: "2000") {
        name
    }
}

With graphql-dsl you can construct a similar query with the following Python snippet:

from typing import NamedTuple
from graphql_dsl import *

class Hero(NamedTuple):
    name: str

class Droid(NamedTuple):
    name: str

class HeroAndDroid(NamedTuple):
    hero: Hero
    droid: Droid

class Input(NamedTuple):
    droid_id: ID

q = GQL( QUERY | HeroAndDroid
       | WITH  | Input
       | PASS  | Input.droid_id * TO * HeroAndDroid.droid * AS * 'id'
       )

print(q.query)

and the output will be:

query HeroAndDroid($droidId:ID!){hero{name}droid(id:$droidId){name}}

The value of q.query is a GraphQL query template that should be used with instances of Input to call servers with GraphQL API

import requests

q = GQL(...)

def call_server(droid_id: ID) -> HeroAndDroid:
    response = requests.post(
        url='https://<graphql-server-url>/',
        json=q.request_payload(Input(droid_id=droid_id)),
        headers={ 'Content-Type': 'application/json'
                , 'Accept': 'application/json'
                }
    )
    response.raise_for_status()
    return q.get_result(response.json())

Note that the query q resides at the top-level module scope, as the query constructor doesn't depend on the query's input values, it only needs to know about the shapes of input and output data.

The query builder supports both NamedTuple and @dataclass types, yet the latter has a slightly different field reference syntax (because dataclasses don't define class-level field getters):

from dataclasses import dataclass
from graphql_dsl import *

@dataclass
class Hero:
    name: str

@dataclass
class Droid:
    name: str

@dataclass
class HeroAndDroid:
    hero: Hero
    droid: Droid

@dataclass
class Input:
    droid_id: ID

q = GQL( QUERY | HeroAndDroid
       | WITH  | Input
       | PASS  | (Input, 'droid_id') * TO * (HeroAndDroid, 'droid') * AS * 'id'
       )

Find out more from Official Documentation.

Test Suite

Test environment is based on Nix.

nix-shell
pytest