gql.transport.websockets

class gql.transport.websockets.WebsocketsTransport(url: str, headers: Optional[Union[Headers, Mapping[str, str], Iterable[Tuple[str, str]], SupportsKeysAndGetItem]] = None, ssl: Union[SSLContext, bool] = False, init_payload: Dict[str, Any] = {}, connect_timeout: Optional[Union[int, float]] = 10, close_timeout: Optional[Union[int, float]] = 10, ack_timeout: Optional[Union[int, float]] = 10, keep_alive_timeout: Optional[Union[int, float]] = None, ping_interval: Optional[Union[int, float]] = None, pong_timeout: Optional[Union[int, float]] = None, answer_pings: bool = True, connect_args: Dict[str, Any] = {}, subprotocols: Optional[List[Subprotocol]] = None)

Bases: WebsocketsTransportBase

Async Transport used to execute GraphQL queries on remote servers with websocket connection.

This transport uses asyncio and the websockets library in order to send requests on a websocket connection.

APOLLO_SUBPROTOCOL = 'graphql-ws'
GRAPHQLWS_SUBPROTOCOL = 'graphql-transport-ws'
__init__(url: str, headers: Optional[Union[Headers, Mapping[str, str], Iterable[Tuple[str, str]], SupportsKeysAndGetItem]] = None, ssl: Union[SSLContext, bool] = False, init_payload: Dict[str, Any] = {}, connect_timeout: Optional[Union[int, float]] = 10, close_timeout: Optional[Union[int, float]] = 10, ack_timeout: Optional[Union[int, float]] = 10, keep_alive_timeout: Optional[Union[int, float]] = None, ping_interval: Optional[Union[int, float]] = None, pong_timeout: Optional[Union[int, float]] = None, answer_pings: bool = True, connect_args: Dict[str, Any] = {}, subprotocols: Optional[List[Subprotocol]] = None) None

Initialize the transport with the given parameters.

Parameters
  • url – The GraphQL server URL. Example: ‘wss://server.com:PORT/graphql’.

  • headers – Dict of HTTP Headers.

  • ssl – ssl_context of the connection. Use ssl=False to disable encryption

  • init_payload – Dict of the payload sent in the connection_init message.

  • connect_timeout – Timeout in seconds for the establishment of the websocket connection. If None is provided this will wait forever.

  • close_timeout – Timeout in seconds for the close. If None is provided this will wait forever.

  • ack_timeout – Timeout in seconds to wait for the connection_ack message from the server. If None is provided this will wait forever.

  • keep_alive_timeout – Optional Timeout in seconds to receive a sign of liveness from the server.

  • ping_interval – Delay in seconds between pings sent by the client to the backend for the graphql-ws protocol. None (by default) means that we don’t send pings. Note: there are also pings sent by the underlying websockets protocol. See the keepalive documentation for more information about this.

  • pong_timeout – Delay in seconds to receive a pong from the backend after we sent a ping (only for the graphql-ws protocol). By default equal to half of the ping_interval.

  • answer_pings – Whether the client answers the pings from the backend (for the graphql-ws protocol). By default: True

  • connect_args – Other parameters forwarded to websockets.connect

  • subprotocols – list of subprotocols sent to the backend in the ‘subprotocols’ http header. By default: both apollo and graphql-ws subprotocols.

ping_received: asyncio.Event

ping_received is an asyncio Event which will fire each time a ping is received with the graphql-ws protocol

pong_received: asyncio.Event

pong_received is an asyncio Event which will fire each time a pong is received with the graphql-ws protocol

async send_ping(payload: Optional[Any] = None) None

Send a ping message for the graphql-ws protocol

async send_pong(payload: Optional[Any] = None) None

Send a pong message for the graphql-ws protocol

async close() None

Coroutine used to Close an established connection

async connect() None

Coroutine which will:

  • connect to the websocket address

  • send the init message

  • wait for the connection acknowledge from the server

  • create an asyncio task which will be used to receive and parse the websocket answers

Should be cleaned with a call to the close coroutine

async execute(document: DocumentNode, variable_values: Optional[Dict[str, Any]] = None, operation_name: Optional[str] = None) ExecutionResult

Execute the provided document AST against the configured remote server using the current session.

Send a query but close the async generator as soon as we have the first answer.

The result is sent as an ExecutionResult object.

async subscribe(document: DocumentNode, variable_values: Optional[Dict[str, Any]] = None, operation_name: Optional[str] = None, send_stop: Optional[bool] = True) AsyncGenerator[ExecutionResult, None]

Send a query and receive the results using a python async generator.

The query can be a graphql query, mutation or subscription.

The results are sent as an ExecutionResult object.

async wait_closed() None
payloads: Dict[str, Any]

payloads is a dict which will contain the payloads received for example with the graphql-ws protocol: ‘ping’, ‘pong’, ‘connection_ack’