gql.utilities

gql.utilities.build_client_schema(introspection: IntrospectionQuery) GraphQLSchema

This is an alternative to the graphql-core function build_client_schema but with default include and skip directives added to the schema to fix issue #278

Warning

This function will be removed once the issue graphql-js#3419 has been fixed and ported to graphql-core so don’t use it outside gql.

gql.utilities.get_introspection_query_ast(descriptions: bool = True, specified_by_url: bool = False, directive_is_repeatable: bool = False, schema_description: bool = False, type_recursion_level: int = 7) DocumentNode

Get a query for introspection as a document using the DSL module.

Equivalent to the get_introspection_query function from graphql-core but using the DSL module and allowing to select the recursion level.

Optionally, you can exclude descriptions, include specification URLs, include repeatability of directives, and specify whether to include the schema description as well.

gql.utilities.node_tree(obj: Node, *, ignore_loc: bool = True, ignore_block: bool = True, ignored_keys: Optional[List] = None)

Method which returns a tree of Node elements as a String.

Useful to debug deep DocumentNode instances created by gql or dsl_gql.

WARNING: the output of this method is not guaranteed and may change without notice.

gql.utilities.parse_result(schema: GraphQLSchema, document: DocumentNode, result: Optional[Dict[str, Any]], operation_name: Optional[str] = None) Optional[Dict[str, Any]]

Unserialize a result received from a GraphQL backend.

Parameters
  • schema – the GraphQL schema

  • document – the document representing the query sent to the backend

  • result – the serialized result received from the backend

  • operation_name – the optional operation name

Returns

a parsed result with scalars and enums parsed depending on their definition in the schema.

Given a schema, a query and a serialized result, provide a new result with parsed values.

If the result contains only built-in GraphQL scalars (String, Int, Float, …) then the parsed result should be unchanged.

If the result contains custom scalars or enums, then those values will be parsed with the parse_value method of the custom scalar or enum definition in the schema.

gql.utilities.serialize_value(type_: GraphQLType, value: Any) Any

Given a GraphQL type and a Python value, return the serialized value.

This method will serialize the value recursively, entering into lists and dicts.

Can be used to serialize Enums and/or Custom Scalars in variable values.

Parameters
  • type – the GraphQL type

  • value – the provided value

gql.utilities.serialize_variable_values(schema: GraphQLSchema, document: DocumentNode, variable_values: Dict[str, Any], operation_name: Optional[str] = None) Dict[str, Any]

Given a GraphQL document and a schema, serialize the Dictionary of variable values.

Useful to serialize Enums and/or Custom Scalars in variable values.

Parameters
  • schema – the GraphQL schema

  • document – the document representing the query sent to the backend

  • variable_values – the dictionnary of variable values which needs to be serialized.

  • operation_name – the optional operation_name for the query.

gql.utilities.update_schema_enum(schema: GraphQLSchema, name: str, values: Union[Dict[str, Any], Type[Enum]], use_enum_values: bool = False)

Update in the schema the GraphQLEnumType corresponding to the given name.

Example:

from enum import Enum

class Color(Enum):
    RED = 0
    GREEN = 1
    BLUE = 2

update_schema_enum(schema, 'Color', Color)
Parameters
  • schema – a GraphQL Schema already containing the GraphQLEnumType type.

  • name – the name of the enum in the GraphQL schema

  • values – Either a Python Enum or a dict of values. The keys of the provided values should correspond to the keys of the existing enum in the schema.

  • use_enum_values – By default, we configure the GraphQLEnumType to serialize to enum instances (ie: .parse_value() returns Color.RED). If use_enum_values is set to True, then .parse_value() returns 0. use_enum_values=True is the defaut behaviour when passing an Enum to a GraphQLEnumType.

gql.utilities.update_schema_scalar(schema: GraphQLSchema, name: str, scalar: GraphQLScalarType)

Update the scalar in a schema with the scalar provided.

Parameters
  • schema – the GraphQL schema

  • name – the name of the custom scalar type in the schema

  • scalar – a provided scalar type

This can be used to update the default Custom Scalar implementation when the schema has been provided from a text file or from introspection.

gql.utilities.update_schema_scalars(schema: GraphQLSchema, scalars: List[GraphQLScalarType])

Update the scalars in a schema with the scalars provided.

Parameters
  • schema – the GraphQL schema

  • scalars – a list of provided scalar types

This can be used to update the default Custom Scalar implementation when the schema has been provided from a text file or from introspection.

If the name of the provided scalar is different than the name of the custom scalar, then you should use the update_schema_scalar method instead.