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:
-
class
gql.
Client
(schema: Optional[Union[str, graphql.type.schema.GraphQLSchema]] = None, introspection=None, transport: Optional[Union[gql.transport.transport.Transport, gql.transport.async_transport.AsyncTransport]] = None, fetch_schema_from_transport: bool = False, execute_timeout: Optional[Union[int, float]] = 10, serialize_variables: bool = False, parse_results: bool = False)¶ 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
andsubscribe
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
, useasync with client as session:
To connect to a sync transport and get a
sync session
, usewith client as session:
-
__init__
(schema: Optional[Union[str, graphql.type.schema.GraphQLSchema]] = None, introspection=None, transport: Optional[Union[gql.transport.transport.Transport, gql.transport.async_transport.AsyncTransport]] = None, fetch_schema_from_transport: bool = False, execute_timeout: Optional[Union[int, float]] = 10, serialize_variables: bool = False, parse_results: bool = False)¶ 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
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 unserialize custom scalars or enums.
-
execute
(document: graphql.language.ast.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: graphql.language.ast.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) → graphql.execution.execute.ExecutionResult -
execute
(document: graphql.language.ast.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], graphql.execution.execute.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.
-
subscribe
(document: graphql.language.ast.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: graphql.language.ast.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[graphql.execution.execute.ExecutionResult, None, None] -
subscribe
(document: graphql.language.ast.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[graphql.execution.execute.ExecutionResult, None, None]] Execute a GraphQL subscription with a python generator.
We need an async transport for this functionality.
-
-
gql.
gql
(request_string: str) → graphql.language.ast.DocumentNode¶ Given a String containing a GraphQL request, parse it into a Document.
- Parameters
request_string (str) – the GraphQL request as a String
- Returns
a Document which can be later executed or subscribed by a
Client
, by anasync session
or by async session
- Raises
GraphQLError – if a syntax error is encountered.