Skip to main content

A Python GraphQL library that makes use of type hinting and concurrency support with the new async/await syntax.

Project description


A Python GraphQL library that makes use of type hinting and concurrency support with the new async/await syntax. With the help of type hints and dataclass it’s easy to build a GraphQL schema using nothing but Python objects and primitives

Consider the following:

from graphql import (
    GraphQLSchema, GraphQLObjectType, GraphQLField, GraphQLString)

schema = GraphQLSchema(
            'hello': GraphQLField(
                resolve=lambda obj, info: 'world')


from dataclasses import dataclass
from typegql import Schema

class RootQuery:
    hello: str

def resolve_hello(info):
    return 'world

 schema = Schema(query=RootQuery)

Clearly the second one looks more “Pythonic” and it’s easier to maintain for complex structures


pip install typegql


The following demonstrates how to use typegql for implementing a GraphQL API for a library of books. The example can be found in typegql/core/examples and you can run it with Sanic by executing python <path_to_example>/

Define your query

from dataclasses import dataclass
from typing import List
from typegql import Connection
from typegql.examples.library.types import Author, Category
from typegql.examples.library.types import Book
from typegql.examples.library import db

@dataclass(init=False, repr=False)
class Query:
    books: List[Book]
    authors: List[Author]
    categories: List[Category]

    books_connection: Connection[Book]

    async def resolve_authors(self, info, **kwargs):
        return db.get('authors')

    async def resolve_books(self, info, **kwargs):
        return db.get('books')

    async def resolve_categories(self, info, **kwargs):
        return db.get('categories')

   async def resolve_books_connection(self, info, **kwargs):
        data = db.get('books')
        return {
            'edges': [{
                'node': node
            } for node in data]}

Define your types

from dataclasses import dataclass, field
from datetime import datetime
from decimal import Decimal
from enum import Enum
from typing import List

from examples.library import db

class Gender(Enum):
    MALE = 'male'
    FEMALE = 'female'

class GeoLocation:
    latitude: Decimal
    longitude: Decimal

class Author:
    """Person that is usually a writer"""

    id: ID = field(metadata={'readonly': True})
    name: str
    gender: Optional[Gender] = None
    geo: Optional[GeoLocation] = None
    books: Optional[List[Book]] = None

class Category:
    id: ID = field(metadata={'readonly': True})
    name: str

class Book:
    """A book... for reading :|"""

    id: ID = field(metadata={'readonly': True})
    author_id: ID
    title: str
    author: Optional[Author] = field(default=None, metadata={'description': 'The author of this book'})
    categories: Optional[List[Category]] = None
    published: Optional[datetime] = None
    tags: Optional[List[str]] = None

    def __post_init__(self):
        self.published = datetime.strptime(self.published, '%Y-%m-%d %H:%M:%S')

    async def resolve_author(self, info):
        data = filter(lambda x: x['id'] == self.author_id, db.get('authors'))
        data = next(data)
        author = Author(**data)
        author.gender = Gender(author.gender)
        if 'geo' in data:
            author.geo = GeoLocation(**data.get('geo'))
        return author

    async def resolve_categories(self, selections, name=None):
        data = filter(lambda x: x['id'] in self.categories, db.get('categories'))
        for d in data:  # showcasing async generator
            yield Category(**d)

    def resolve_tags(self, selections):
        return ['testing', 'purpose']

Run your query

from typegql import Schema
from examples.library.query import Query

schema = Schema(Query)
query = '''
query BooksConnection {
  books_connection {
    edges {
      node {
        author {

async def run():
    result = await


TypeGQL supports DSL client for working with a GraphQL API. The client automatically converts snake to camelcase. Set camelcase=False if this is not desired.

pip install typegql[client]

For example:

from typegql.client import Client

async with Client(url, camelcase=True) as client:
    await client.introspection()
    dsl = client.dsl
    query =
    doc = dsl.query(query)

    status, result = await client.execute(doc)

Change Log

4.0.2 [2020-04-06]

  • updates graphql-core to 3.1.0

4.0.1 [2020-03-17]

  • fixes enum return value

4.0.0 [2020-03-16]

    • Schema now accepts a more granular list of custom graphql types. Signature is:
def __init__(self,
         query: Type,
         mutation: Optional[Type] = None,
         subscription: Optional[Type] = None,
         scalars: Optional[GraphQLScalarMap] = None,
         enums: Optional[GraphQLEnumMap] = None,
         interfaces: Optional[GraphQLInterfaceMap] = None,
         query_types: Optional[GraphQLObjectTypeMap] = None,
         mutation_types: Optional[GraphQLInputObjectTypeMap] = None,

3.1.0 [2020-01-29]

  • fixes an issue with camelcase parameters when a load method is provided

3.0.9 [2020-01-13]

  • fix client execution function
  • update dsl selections to work with FrozenList

3.0.8 [2020-01-07]

  • added ability to ignore attributes in building the schema by using field(metadata={‘skip’: True}). This can be useful when you don’t want to expose certain fields in GraphQL, like a user’s password for example.

3.0.5 [2019-12-16]

  • added support for subscriptions

3.0.4 [2019-12-04]

  • updates graphql-core-next to grapqhl-core >= 3
  • use Sequence instead of List where possible

3.0.3 [2019-11-29]

  • fixed a bug where a custom connection arguments don’t include the relay pagination arguments as well

3.0.2 [2019-11-26]

  • PEP 561 compliant

3.0.1 [2019-11-26]

  • BREAKING: Removed Graph as a baseclass
  • now makes use of dataclasses.dataclass and dataclasess.fields for building the Schema
  • bug fixing and improvements

2.0.9 [2019-10-29]

  • changed the name of an input object from ObjectMuation to ObjectInput

2.0.8 [2019-10-15]

  • allows forward reference between graph types (ie: Book has an author and an Author has books).
    this only works with python 3.7(using from __future__ import annotations, or python 3.8

2.0.6 [2019-06-24]

  • updates uvloop dependency

2.0.5 [2019-04-24]

  • fixed a bug when sending introspection schema

2.0.4 [2019-04-24]

  • updates assert for introspection add message with status and result
  • adds support for enum objects in resolve_field_velue_or_error

2.0.3 [2019-02-08]

  • changes Connection, Edge, Node and PageInfo to interfaces IConnection, IEdge, etc.
  • implements default Connection and PageInfo objects
  • removes has_next, has_previous from PageInfo

2.0.1 [2019-01-19]

  • all properties that don’t have a Field instance assigned to them will be ignored by the Schema
  • updates docs & example to reflect 2.0 changes
  • fixed a bug when using a List argument in mutations

1.0.7 [2018-12-09]

  • bug fixing
  • adds support for camelcase in Client

1.0.1 [2018-11-19]

  • adds support for client DSL



  • testing
  • travis
  • more testing
  • please help with testing :|

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for typegql, version 4.0.2
Filename, size File type Python version Upload date Hashes
Filename, size typegql-4.0.2-py3-none-any.whl (18.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size typegql-4.0.2.tar.gz (18.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page