py_gql is a pure python implementation of the GraphQL query language for Python 3.5+.

The main py_gql package provides the minimum required to build GraphQL schemas and execute queries against them while the relevant submodules allow you to customize the library’s behaviour or implement your own GraphQL layer on top of py_gql.

async py_gql.graphql(schema, document, *, variables=None, operation_name=None, root=None, context=None, validators=None, default_resolver=None, middlewares=None, instrumentation=None)[source]#

Same as process_graphql_query but enforcing usage of AsyncIO.

Resolvers are expected to be async functions. Sync functions will be executed in a thread.

Return type


py_gql.graphql_blocking(schema, document, *, variables=None, operation_name=None, root=None, context=None, validators=None, default_resolver=None, middlewares=None, instrumentation=None)[source]#

Same as process_graphql_query but enforcing usage of sync resolvers.

Return type


py_gql.process_graphql_query(schema, document, *, variables=None, operation_name=None, root=None, context=None, validators=None, default_resolver=None, middlewares=None, instrumentation=None, disable_introspection=False, executor_cls=<class 'py_gql.execution.executor.Executor'>, executor_args=None)[source]#

Main GraphQL entrypoint encapsulating query processing from start to finish including parsing, validation, variable coercion and execution.

  • schema (Schema) – Schema to execute the query against

  • document (Union[str, Document]) – The query document

  • variables (Optional[Mapping[str, Any]]) – Raw, JSON decoded variables parsed from the request

  • operation_name (Optional[str]) – Operation to execute If specified, the operation with the given name will be executed. If not, this executes the single operation without disambiguation.

  • root (Optional[Any]) – Root resolution value passed to top-level resolver

  • context (Optional[Any]) – Custom application-specific execution context. Use this to pass in anything your resolvers require like database connection, user information, etc. Limits on the type(s) used here will depend on your own resolver implementations and the executor class you use. Most thread safe data-structures should work.

  • validators (Optional[Sequence[Type[ValidationVisitor]]]) – Custom validators. Setting this will replace the defaults so if you just want to add some rules, append to py_gql.validation.SPECIFIED_RULES.

  • default_resolver (Optional[Callable[…, Any]]) – Alternative default resolver. For field which do not specify a resolver, this will be used instead of py_gql.execution.default_resolver.

  • middlewares (Optional[Sequence[Callable[…, Any]]]) – List of middleware functions. Middlewares are used to wrap the resolution of all fields with common logic, they are good canidates for logging, authentication, and execution guards.

  • instrumentation (Optional[Instrumentation]) – Instrumentation instance. Use MultiInstrumentation to compose mutiple instances together.

  • disable_introspection (bool) – Use this to prevent schema introspection. This can be useful when you want to hide your full schema while keeping your API available. Note that this deviates the GraphQL specification and will likely break some clients so use this with caution.

  • executor_cls (Type[Executor]) –

    Executor class to use. Must be a subclass of py_gql.execution.Executor.

    This defines how your resolvers are going to be executed and the type of values you’ll get out of this function. executor_args will be passed on class instantiation as keyword arguments.

  • executor_args (Optional[Mapping[str, Any]]) – Extra executor arguments.

Return type



Execution result.


The returned value will depend on the executor class. They ususually return a type wrapping the GraphQLResult object such as Awaitable[GraphQLResult]. You can refer to graphql_async or graphql_blocking for example usage.

class py_gql.GraphQLExtension[source]#

Encode a GraphQL response extension.

Use in conjonction with GraphQLResult.add_extension() to encode the response alongside an execution result.


Extension payload; must be JSON serialisable.

Return type


property name#

Returns: Name of the extension used as the key in the response.

Return type


class py_gql.GraphQLResult(data=<object object>, errors=None)[source]#

Wrapper encoding the behaviour described in the Response part of the specification.

  • data (Optional[Dict[str, Any]]) – The data part of the response.

  • errors (Optional[Sequence[GraphQLResponseError]]) – The errors part of the response. All errors will be included in the response using to_dict().


Add an extensions to the result.


instance (Extension) –


ValueError – Extension with the same name has already been added


Generate an ordered response dict.

Return type

Dict[str, Any]


Encode response as JSON using the standard lib json module.


**kw – Keyword args passed to to json.dumps

Return type


py_gql.build_schema(document, *, ignore_extensions=False, additional_types=None, schema_directives=None)[source]#

Build an executable schema from a GraphQL document.

This includes:

  • Generating types from their definitions

  • Applying schema and type extensions

  • Applying schema directives

  • document (Union[Document, str]) – SDL document

  • ignore_extensions (bool) – Whether to apply schema and type extensions or not.

  • additional_types (Optional[List[NamedType]]) – User supplied list of types Use this to specify some custom implementation for scalar, enums, etc. - In case of object types, interfaces, etc. the supplied type will override the extracted type without checking for compatibility. - Extension will be applied to these types. As a result, the resulting types may not be the same objects that were provided, so users should not rely on type identity.

  • schema_directives (Optional[Mapping[str, Type[SchemaDirective]]]) –

    Schema directive classes. Members must be subclasses of py_gql.schema.SchemaDirective and must either define a non-null definition attribute or the corresponding definition must be present in the document. See apply_schema_directives() for more details.


    Specified directives such as @deperecated do not need to be specified this way and are always processed internally to ensure compliance with the specification.

Return type



Executable schema