Introduction

GraphQL-core-3 is a Python port of GraphQL.js, the JavaScript reference implementation for GraphQL, a query language for APIs created by Facebook.

GraphQL consists of three parts:

  • A type system that you define
  • A query language that you use to query the API
  • An execution and validation engine

The reference implementation closely follows the Specification for GraphQL which consists of the following sections:

This division into subsections is reflected in the Sub-Packages of GraphQL-core 3. Each of these sub-packages implements the aspects specified in one of the sections of the specification.

Getting started

You can install GraphQL-core 3 using pip:

pip install "graphql-core>=3a"

You can also install GraphQL-core 3 with pipenv, if you prefer that:

pipenv install --pre "graphql-core>=3a"

Now you can start using GraphQL-core 3 by importing from the top-level graphql package. Nearly everything defined in the sub-packages can also be imported directly from the top-level package.

For instance, using the types defined in the graphql.type package, you can define a GraphQL schema, like this simple one:

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

schema = GraphQLSchema(
    query=GraphQLObjectType(
        name='RootQueryType',
        fields={
            'hello': GraphQLField(
                GraphQLString,
                resolve=lambda obj, info: 'world')
        }))

The graphql.execution package implements the mechanism for executing GraphQL queries. The top-level graphql() and graphql_sync() functions also parse and validate queries using the graphql.language and graphql.validation modules.

So to validate and execute a query against our simple schema, you can do:

from graphql import graphql_sync

query = '{ hello }'

print(graphql_sync(schema, query))

This will yield the following output:

ExecutionResult(data={'hello': 'world'}, errors=None)

Reporting Issues and Contributing

Please visit the GitHub repository of GraphQL-core 3 if you’re interested in the current development or want to report issues or send pull requests.