# gql.client

class gql.client.AsyncClientSession(client: Client)

  Bases: `object`

  An instance of this class is created when using `async with` on a `client`.

  It contains the async methods (execute, subscribe) to send queries on an async transport using the same session.

  __init__(client: Client)
    Parameters:

      client – the `client` used

  async close()

    Close the transport and cleanup the batching task if batching is enabled.

    Will wait until all the remaining requests in the batch processing queue have been executed.

  async connect()

    Connect the transport and initialize the batch task loop if batching is enabled.

  async execute(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[False] = False, **kwargs: Any) → Dict[str, Any]
  async execute(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[True], **kwargs: Any) → ExecutionResult
  async execute(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: bool, **kwargs: Any) → Dict[str, Any] | ExecutionResult

    Coroutine to execute the provided request asynchronously using the async transport.

    Raises a TransportQueryError if an error has been returned in

      the ExecutionResult.

    Parameters:

      - request – GraphQL query as `GraphQLRequest`.

      - 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 deserialize 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 execute_batch(requests: List[GraphQLRequest], *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[False] = False, **kwargs: Any) → List[Dict[str, Any]]
  async execute_batch(requests: List[GraphQLRequest], *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[True], **kwargs: Any) → List[ExecutionResult]
  async execute_batch(requests: List[GraphQLRequest], *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: bool, **kwargs: Any) → List[Dict[str, Any]] | List[ExecutionResult]

    Execute multiple GraphQL requests in a batch, using the async transport. This method sends the requests to the server all at once.

    Raises a TransportQueryError if an error has been returned in any

      ExecutionResult.

    Parameters:

      - requests – List of requests that will 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 deserialize 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 explicitly using introspection.

    Don’t use this function and instead set the fetch_schema_from_transport attribute to True

  async subscribe(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[False] = False, **kwargs: Any) → AsyncGenerator[Dict[str, Any], None]
  async subscribe(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[True], **kwargs: Any) → AsyncGenerator[ExecutionResult, None]
  async subscribe(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: bool, **kwargs: Any) → AsyncGenerator[Dict[str, Any], None] | AsyncGenerator[ExecutionResult, None]

    Coroutine to subscribe asynchronously to the provided request asynchronously using the async transport.

    Raises a TransportQueryError if an error has been returned in

      the ExecutionResult.

    Parameters:

      - request – GraphQL query as `GraphQLRequest`.

      - 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 deserialize 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: str | GraphQLSchema | None = None, introspection: IntrospectionQuery | None = None, transport: Transport | AsyncTransport | None = None, fetch_schema_from_transport: bool = False, introspection_args: Dict | None = None, execute_timeout: int | float | None = 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: str | GraphQLSchema | None = None, introspection: IntrospectionQuery | None = None, transport: Transport | AsyncTransport | None = None, fetch_schema_from_transport: bool = False, introspection_args: Dict | None = None, execute_timeout: int | float | None = 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 `gql.utilities.get_introspection_query_ast()` method.

      - 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: bool
  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:

      - 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(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[False] = False, **kwargs: Any) → Dict[str, Any]
  execute(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[True], **kwargs: Any) → ExecutionResult
  execute(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: bool, **kwargs: Any) → Dict[str, Any] | ExecutionResult

    Execute the provided request 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: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[False] = False, **kwargs: Any) → List[Dict[str, Any]]
  execute_batch(requests: List[GraphQLRequest], *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[True], **kwargs: Any) → List[ExecutionResult]
  execute_batch(requests: List[GraphQLRequest], *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: bool, **kwargs: Any) → 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(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[False] = False, **kwargs: Any) → Generator[Dict[str, Any], None, None]
  subscribe(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[True], **kwargs: Any) → Generator[ExecutionResult, None, None]
  subscribe(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: bool, **kwargs: Any) → 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.client.ReconnectingAsyncClientSession(client: Client, *, retry_connect: bool | Callable[[_CallableT], _CallableT] = True, retry_execute: bool | Callable[[_CallableT], _CallableT] = True)

  Bases: `AsyncClientSession`

  An instance of this class is created when using the `connect_async` method of the `Client` class with `reconnecting=True`.

  It is used to provide a single session which will reconnect automatically if the connection fails.

  __init__(client: Client, *, retry_connect: bool | Callable[[_CallableT], _CallableT] = True, retry_execute: 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 retry decorator (e.g., from tenacity) to provide specific retries parameters for the connections.

      - retry_execute – Either a Boolean to activate/deactivate the retries for the execute method OR a retry decorator (e.g., from tenacity) to provide specific retries parameters for this method.

  async close()

    Stop the connect task and cleanup the batching task if batching is enabled.

  async connect()

    Start the connect task and initialize the batch task loop if batching is enabled.

  async execute(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: bool = False, **kwargs: Any) → Dict[str, Any] | ExecutionResult

    Coroutine to execute the provided request asynchronously using the async transport.

    Raises a TransportQueryError if an error has been returned in

      the ExecutionResult.

    Parameters:

      - request – GraphQL query as `GraphQLRequest`.

      - 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 deserialize 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 execute_batch(requests: List[GraphQLRequest], *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: bool = False, **kwargs: Any) → List[Dict[str, Any]] | List[ExecutionResult]

    Execute multiple GraphQL requests in a batch, using the async transport. This method sends the requests to the server all at once.

    Raises a TransportQueryError if an error has been returned in any

      ExecutionResult.

    Parameters:

      - requests – List of requests that will 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 deserialize 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 explicitly 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.

  async subscribe(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: bool = False, **kwargs: Any) → AsyncGenerator[Dict[str, Any], None] | AsyncGenerator[ExecutionResult, None]

    Coroutine to subscribe asynchronously to the provided request asynchronously using the async transport.

    Raises a TransportQueryError if an error has been returned in

      the ExecutionResult.

    Parameters:

      - request – GraphQL query as `GraphQLRequest`.

      - 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 deserialize 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: 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: Client)
    Parameters:

      client – the `client` used

  close()

    Close the transport and cleanup the batching thread if batching is enabled.

    Will wait until all the remaining requests in the batch processing queue have been executed.

  connect()

    Connect the transport and initialize the batch threading loop if batching is enabled.

  execute(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[False] = False, **kwargs: Any) → Dict[str, Any]
  execute(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: Literal[True], **kwargs: Any) → ExecutionResult
  execute(request: GraphQLRequest, *, serialize_variables: bool | None = None, parse_result: bool | None = None, get_execution_result: bool, **kwargs: Any) → Dict[str, Any] | ExecutionResult

    Execute the provided request synchronously using the sync transport.

    Raises a TransportQueryError if an error has been returned in

      the ExecutionResult.

    Parameters:

      - request – GraphQL query as `GraphQLRequest`.

      - 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 deserialize 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.

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

    Execute multiple GraphQL requests in a batch, using the sync transport. This method sends the requests to the server all at once.

    Raises a TransportQueryError if an error has been returned in any

      ExecutionResult.

    Parameters:

      - requests – List of requests that will 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 deserialize 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 explicitly using introspection.

    Don’t use this function and instead set the fetch_schema_from_transport attribute to True

  property transport