Skip to main content

Comprehensive GraphQL implementation for Python.

Project description


GitHub Workflow Status Codecov PyPI PyPI - Python Version Wheel Read the Docs (version)

py-gql is a pure python GraphQL implementation aimed at creating GraphQL servers and providing common tooling.

It supports:

  • Parsing the GraphQL query language and schema definition language.
  • Building a GraphQL type schema programmatically and from Schema Definition files (including support for schema directives).
  • Validating and Executing a GraphQL request against a type schema.

Quick links


pip install py-gql

For more details see install.rst.

Usage & Examples

from py_gql import build_schema, graphql_blocking

schema = build_schema(
    type Query {
        hello(value: String = "world"): String!

def resolve_hello(*_, value):
    return "Hello {}!".format(value)

result = graphql_blocking(schema, '{ hello(value: "World") }')

assert result.response() == {
    "data": {
        "hello": "Hello World!"

For more usage examples, you can refer to the User Guide and some more involved examples available in the examples folder.

The tests should also provide some contrived examples.

Goals & Status

This project was initially born as an experiment / learning project following some frustration with graphql-core and Graphene I encountered at work.

The main goals were originally to:

  • Get a deeper understanding of GraphQL

  • Provide an alternative to graphql-core which:

    • tracks the latest version of the spec (which graphql-core didn't at the time)
    • does so without being a port of the JS code which leads to some weird edge case when we tried to extend the library
    • keeps support for Python 2
    • (subjective) attempts to be a bit more usable for our use cases, the ideal result would sit somewhere in between Graphene and graphql-core
    • makes it easier for us to build / include some extra tooling such as custom tracing, custom validation and SDL based tools as well as builder infrastructure to support easily implementing graphql layers over existing data layers (such as ORM)

Not all these points are satisfied yet, and some have been changed over time, but py-gql should be ready for general use. It is however still in a fairly experimental phase and to reflect that versions are still in the 0.x.y.The API is still subject to change as different part of the codebase are iterated on and are getting more use against production codebases.

Development setup

Make sure you are using Python 3.6+ (you can run the tests under 3.5 but `other development tasks such as black are not guaranteed to work).

Clone this repo and create a virtualenv before installing the development dependencies:

git clone
python -m venv $WORKON_HOME/py-gql --copies
pip install -U -r requirements-dev.txt
pip install -e .

Development tasks are available through invoke. Check or use inv -l to list all available tasks and inv --help {TASK} to get help on a specific task. Most of the tools used should be usable directly, but the tasks provide some common aliases and targets.

As a shortcut, inv check will run all checks that are normally run on CI (lint, typecheck and tests).

CI is done on Github Actions.


  • The last tag should correspond to the latest release version
  • master contains unreleased changes that are planned to be released
  • dev is used for experimenting and hard changes such as rebase and force pushed should be expected. For now this is the branch I used in side projects and where most of the iteration happens.

Download files

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

Files for py-gql, version 0.6.1
Filename, size File type Python version Upload date Hashes
Filename, size py_gql-0.6.1-py3-none-any.whl (143.2 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size py_gql-0.6.1.tar.gz (247.9 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