Reference

Top-Level Functions

The primary gql package includes everything you need to execute GraphQL requests, with the exception of the transports which are optional:

  • the gql method to parse a GraphQL query

  • the Client class as the entrypoint to execute requests and create sessions

class gql.Client(schema: Optional[Union[str, GraphQLSchema]] = None, introspection: Optional[IntrospectionQuery] = None, transport: Optional[Union[Transport, AsyncTransport]] = None, fetch_schema_from_transport: bool = False, introspection_args: Optional[Dict] = None, execute_timeout: Optional[Union[int, float]] = 10, serialize_variables: bool = False, parse_results: bool = False, batch_interval: float = 0, batch_max: int = 10)

Bases: object

The Client class is the main entrypoint to execute GraphQL requests on a GQL transport.

It can take sync or async transports as argument and can either execute and subscribe to requests itself with the execute and subscribe methods OR can be used to get a sync or async session depending on the transport type.

To connect to an async transport and get an async session, use async with client as session:

To connect to a sync transport and get a sync session, use with client as session:

__init__(schema: Optional[Union[str, GraphQLSchema]] = None, introspection: Optional[IntrospectionQuery] = None, transport: Optional[Union[Transport, AsyncTransport]] = None, fetch_schema_from_transport: bool = False, introspection_args: Optional[Dict] = None, execute_timeout: Optional[Union[int, float]] = 10, serialize_variables: bool = False, parse_results: bool = False, batch_interval: float = 0, batch_max: int = 10)

Initialize the client with the given parameters.

Parameters

  • schema – an optional GraphQL Schema for local validation See Schema validation

  • transport – The provided transport.

  • fetch_schema_from_transport – Boolean to indicate that if we want to fetch the schema from the transport using an introspection query.

  • introspection_args – arguments passed to the get_introspection_query method of graphql-core.

  • execute_timeout – The maximum time in seconds for the execution of a request before a TimeoutError is raised. Only used for async transports. Passing None results in waiting forever for a response.

  • serialize_variables – whether the variable values should be serialized. Used for custom scalars and/or enums. Default: False.

  • parse_results – Whether gql will try to parse the serialized output sent by the backend. Can be used to deserialize custom scalars or enums.

  • batch_interval – Time to wait in seconds for batching requests together. Batching is disabled (by default) if 0.

  • batch_max – Maximum number of requests in a single batch.

property batching_enabled
async close_async()

Close the async transport and stop the optional reconnecting task.

close_sync()

Close the sync session and the sync transport.

If batching is enabled, this will block until the remaining queries in the batching queue have been processed.

async connect_async(reconnecting=False, **kwargs)

Connect asynchronously with the underlying async transport to produce a session.

That session will be a permanent auto-reconnecting session if reconnecting=True.

If you call this method, you should call the close_async method for cleanup.

Parameters
connect_sync()

Connect synchronously with the underlying sync transport to produce a session.

If you call this method, you should call the close_sync method for cleanup.

execute(document: DocumentNode, variable_values: Optional[Dict[str, Any]] = None, operation_name: Optional[str] = None, serialize_variables: Optional[bool] = None, parse_result: Optional[bool] = None, *, get_execution_result: Literal[False] = False, **kwargs) → Dict[str, Any]
execute(document: DocumentNode, variable_values: Optional[Dict[str, Any]] = None, operation_name: Optional[str] = None, serialize_variables: Optional[bool] = None, parse_result: Optional[bool] = None, *, get_execution_result: Literal[True], **kwargs) → ExecutionResult
execute(document: DocumentNode, variable_values: Optional[Dict[str, Any]] = None, operation_name: Optional[str] = None, serialize_variables: Optional[bool] = None, parse_result: Optional[bool] = None, *, get_execution_result: bool, **kwargs) → Union[Dict[str, Any], ExecutionResult]

Execute the provided document AST against the remote server using the transport provided during init.

This function WILL BLOCK until the result is received from the server.

Either the transport is sync and we execute the query synchronously directly OR the transport is async and we execute the query in the asyncio loop (blocking here until answer).

This method will:

  • connect using the transport to get a session

  • execute the GraphQL request on the transport session

  • close the session and close the connection to the server

If you have multiple requests to send, it is better to get your own session and execute the requests in your session.

The extra arguments passed in the method will be passed to the transport execute method.

execute_batch(requests: List[GraphQLRequest], *, serialize_variables: Optional[bool] = None, parse_result: Optional[bool] = None, get_execution_result: Literal[False], **kwargs) → List[Dict[str, Any]]
execute_batch(requests: List[GraphQLRequest], *, serialize_variables: Optional[bool] = None, parse_result: Optional[bool] = None, get_execution_result: Literal[True], **kwargs) → List[ExecutionResult]
execute_batch(requests: List[GraphQLRequest], *, serialize_variables: Optional[bool] = None, parse_result: Optional[bool] = None, get_execution_result: bool, **kwargs) → Union[List[Dict[str, Any]], List[ExecutionResult]]

Execute multiple GraphQL requests in a batch against the remote server using the transport provided during init.

This function WILL BLOCK until the result is received from the server.

Either the transport is sync and we execute the query synchronously directly OR the transport is async and we execute the query in the asyncio loop (blocking here until answer).

This method will:

  • connect using the transport to get a session

  • execute the GraphQL requests on the transport session

  • close the session and close the connection to the server

If you want to perform multiple executions, it is better to use the context manager to keep a session active.

The extra arguments passed in the method will be passed to the transport execute method.

subscribe(document: DocumentNode, variable_values: Optional[Dict[str, Any]] = None, operation_name: Optional[str] = None, serialize_variables: Optional[bool] = None, parse_result: Optional[bool] = None, *, get_execution_result: Literal[False] = False, **kwargs) → Generator[Dict[str, Any], None, None]
subscribe(document: DocumentNode, variable_values: Optional[Dict[str, Any]] = None, operation_name: Optional[str] = None, serialize_variables: Optional[bool] = None, parse_result: Optional[bool] = None, *, get_execution_result: Literal[True], **kwargs) → Generator[ExecutionResult, None, None]
subscribe(document: DocumentNode, variable_values: Optional[Dict[str, Any]] = None, operation_name: Optional[str] = None, serialize_variables: Optional[bool] = None, parse_result: Optional[bool] = None, *, get_execution_result: bool, **kwargs) → Union[Generator[Dict[str, Any], None, None], Generator[ExecutionResult, None, None]]

Execute a GraphQL subscription with a python generator.

We need an async transport for this functionality.

class gql.GraphQLRequest(document: DocumentNode, variable_values: Optional[Dict[str, Any]] = None, operation_name: Optional[str] = None)

Bases: object

GraphQL Request to be executed.

__init__(document: DocumentNode, variable_values: Optional[Dict[str, Any]] = None, operation_name: Optional[str] = None) → None
document: DocumentNode

GraphQL query as AST Node object.

operation_name: Optional[str] = None

Name of the operation that shall be executed. Only required in multi-operation documents (Default: None).

serialize_variable_values(schema: GraphQLSchema) → GraphQLRequest
variable_values: Optional[Dict[str, Any]] = None

Dictionary of input parameters (Default: None).

gql.gql(request_string: str | Source) → DocumentNode

Given a string containing a GraphQL request, parse it into a Document.

Parameters

request_string (str | Source) – the GraphQL request as a String

Returns

a Document which can be later executed or subscribed by a Client, by an async session or by a sync session

Raises

GraphQLError – if a syntax error is encountered.