gql.client¶
-
class
gql.client.
AsyncClientSession
(client: gql.client.Client)¶ Bases:
object
An instance of this class is created when using
async with
on aclient
.It contains the async methods (execute, subscribe) to send queries on an async transport using the same session.
-
__init__
(client: gql.client.Client)¶ - Parameters
client – the
client
used
-
async
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]¶ -
async
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 -
async
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] Coroutine to execute the provided document AST asynchronously using the async transport.
- Raises a TransportQueryError if an error has been returned in
the ExecutionResult.
- Parameters
document – GraphQL query as AST Node object.
variable_values – Dictionary of input parameters.
operation_name – Name of the operation that shall be executed.
serialize_variables – whether the variable values should be serialized. Used for custom scalars and/or enums. By default use the serialize_variables argument of the client.
parse_result – Whether gql will unserialize the result. By default use the parse_results argument of the client.
get_execution_result – return the full ExecutionResult instance instead of only the “data” field. Necessary if you want to get the “extensions” field.
The extra arguments are passed to the transport execute method.
-
async
fetch_schema
() → None¶ Fetch the GraphQL schema explicitely using introspection.
Don’t use this function and instead set the fetch_schema_from_transport attribute to True
-
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) → AsyncGenerator[Dict[str, Any], 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) → AsyncGenerator[graphql.execution.execute.ExecutionResult, 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[AsyncGenerator[Dict[str, Any], None], AsyncGenerator[graphql.execution.execute.ExecutionResult, None]] Coroutine to subscribe asynchronously to the provided document AST asynchronously using the async transport.
- Raises a TransportQueryError if an error has been returned in
the ExecutionResult.
- Parameters
document – GraphQL query as AST Node object.
variable_values – Dictionary of input parameters.
operation_name – Name of the operation that shall be executed.
serialize_variables – whether the variable values should be serialized. Used for custom scalars and/or enums. By default use the serialize_variables argument of the client.
parse_result – Whether gql will unserialize the result. By default use the parse_results argument of the client.
get_execution_result – yield the full ExecutionResult instance instead of only the “data” field. Necessary if you want to get the “extensions” field.
The extra arguments are passed to the transport subscribe method.
-
property
transport
¶
-
-
class
gql.client.
Client
(schema: Optional[Union[str, graphql.type.schema.GraphQLSchema]] = None, introspection: Optional[graphql.utilities.get_introspection_query.IntrospectionQuery] = 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: Optional[graphql.utilities.get_introspection_query.IntrospectionQuery] = 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.
-
async
close_async
()¶ Close the async transport and stop the optional reconnecting task.
-
close_sync
()¶ Close the sync transport.
-
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
reconnecting – if True, create a permanent reconnecting session
**kwargs – additional arguments for the
ReconnectingAsyncClientSession init method
.
-
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: 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.
-
-
class
gql.client.
ReconnectingAsyncClientSession
(client: gql.client.Client, retry_connect: Union[bool, Callable[[_CallableT], _CallableT]] = True, retry_execute: Union[bool, Callable[[_CallableT], _CallableT]] = True)¶ Bases:
gql.client.AsyncClientSession
An instance of this class is created when using the
connect_async
method of theClient
class withreconnecting=True
.It is used to provide a single session which will reconnect automatically if the connection fails.
-
__init__
(client: gql.client.Client, retry_connect: Union[bool, Callable[[_CallableT], _CallableT]] = True, retry_execute: Union[bool, Callable[[_CallableT], _CallableT]] = True)¶ - Parameters
client – the
client
used.retry_connect – Either a Boolean to activate/deactivate the retries for the connection to the transport OR a backoff decorator to provide specific retries parameters for the connections.
retry_execute – Either a Boolean to activate/deactivate the retries for the execute method OR a backoff decorator to provide specific retries parameters for this method.
-
async
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 = False, **kwargs) → Union[Dict[str, Any], graphql.execution.execute.ExecutionResult]¶ Coroutine to execute the provided document AST asynchronously using the async transport.
- Raises a TransportQueryError if an error has been returned in
the ExecutionResult.
- Parameters
document – GraphQL query as AST Node object.
variable_values – Dictionary of input parameters.
operation_name – Name of the operation that shall be executed.
serialize_variables – whether the variable values should be serialized. Used for custom scalars and/or enums. By default use the serialize_variables argument of the client.
parse_result – Whether gql will unserialize the result. By default use the parse_results argument of the client.
get_execution_result – return the full ExecutionResult instance instead of only the “data” field. Necessary if you want to get the “extensions” field.
The extra arguments are passed to the transport execute method.
-
async
fetch_schema
() → None¶ Fetch the GraphQL schema explicitely using introspection.
Don’t use this function and instead set the fetch_schema_from_transport attribute to True
-
async
start_connecting_task
()¶ Start the task responsible to restart the connection of the transport when requested by an event.
-
async
stop_connecting_task
()¶ Stop the connecting task.
-
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 = False, **kwargs) → Union[AsyncGenerator[Dict[str, Any], None], AsyncGenerator[graphql.execution.execute.ExecutionResult, None]]¶ Coroutine to subscribe asynchronously to the provided document AST asynchronously using the async transport.
- Raises a TransportQueryError if an error has been returned in
the ExecutionResult.
- Parameters
document – GraphQL query as AST Node object.
variable_values – Dictionary of input parameters.
operation_name – Name of the operation that shall be executed.
serialize_variables – whether the variable values should be serialized. Used for custom scalars and/or enums. By default use the serialize_variables argument of the client.
parse_result – Whether gql will unserialize the result. By default use the parse_results argument of the client.
get_execution_result – yield the full ExecutionResult instance instead of only the “data” field. Necessary if you want to get the “extensions” field.
The extra arguments are passed to the transport subscribe method.
-
property
transport
¶
-
-
class
gql.client.
SyncClientSession
(client: gql.client.Client)¶ Bases:
object
An instance of this class is created when using
with
on the client.It contains the sync method execute to send queries on a sync transport using the same session.
-
__init__
(client: gql.client.Client)¶ - Parameters
client – the
client
used
-
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 synchronously using the sync transport.
- Raises a TransportQueryError if an error has been returned in
the ExecutionResult.
- Parameters
document – GraphQL query as AST Node object.
variable_values – Dictionary of input parameters.
operation_name – Name of the operation that shall be executed.
serialize_variables – whether the variable values should be serialized. Used for custom scalars and/or enums. By default use the serialize_variables argument of the client.
parse_result – Whether gql will unserialize the result. By default use the parse_results argument of the client.
get_execution_result – return the full ExecutionResult instance instead of only the “data” field. Necessary if you want to get the “extensions” field.
The extra arguments are passed to the transport execute method.
-
fetch_schema
() → None¶ Fetch the GraphQL schema explicitely using introspection.
Don’t use this function and instead set the fetch_schema_from_transport attribute to True
-
property
transport
¶
-