Client API¶
GraphQLClient¶
-
class
aiographql.client.
GraphQLClient
(endpoint: str, headers: Optional[Mapping[str, str]] = None, method: Optional[str] = None, schema: Optional[graphql.type.schema.GraphQLSchema] = None, session: Optional[aiohttp.client.ClientSession] = None)¶ Client implementation handling all interactions with a specified endpoint. The following example shows how to make a simple query.
client = GraphQLClient( endpoint="http://127.0.0.1:8080/v1/graphql", headers={"Authorization": "Bearer <token>"}, ) response: GraphQLResponse = await client.query("{ city { name } }")
You can also use an application scoped
aiohttp.ClientSession
throughout the life of the client as show below.async with aiohttp.ClientSession() as session: client = GraphQLClient( endpoint="http://127.0.0.1:8080/v1/graphql", session=session )
Parameters: - endpoint – URI of graph api.
- headers – Default headers to use for every request made by this client. By default the client adds ‘Content-Type: application/json’ and ‘Accept-Encoding: gzip’ to all requests. These can be overridden by specifying then here.
- method – Default method to use when submitting a GraphQL request to the specified endpoint.
- session – Optional aiohttp.ClientSession to use when making requests. This is expected to be externally managed.
-
get
(request: aiographql.client.request.GraphQLRequest, headers: Optional[Dict[str, str]] = None, operation: Optional[str] = None, variables: Optional[Dict[str, Any]] = None, session: Optional[aiohttp.client.ClientSession] = None) → aiographql.client.response.GraphQLResponse¶ Helper method that wraps :method: GraphQLClient.query with method explicitly set as
GraphQLQueryMethod.get
.Parameters: - request – Request to send to the GraphQL server.
- headers – Additional headers to be set when sending HTTP request.
- operation – GraphQL operation name to use if the GraphQLRequest.query contains named operations. This will override any default operation set.
- variables – Query variables to set for the provided request. This will override the default values for any existing variables in the request if set.
- session – Optional aiohttp.ClientSession to use for requests
Returns: The resulting GraphQLResponse object.
-
get_schema
(refresh: bool = False, headers: Optional[Dict[str, str]] = None) → graphql.type.schema.GraphQLSchema¶ Get the introspected schema for the endpoint used by this client. If an unexpired cache exists, this is returned unless the refresh parameter is set to True.
Parameters: - refresh – Refresh the cached schema by forcing an introspection of the GraphQL endpoint.
- headers – Request headers
Returns: The GraphQL schema as introspected. This maybe a previously cached value.
-
introspect
(headers: Optional[Dict[str, str]] = None) → graphql.type.schema.GraphQLSchema¶ Introspect the GraphQL endpoint specified for this client and return a graphql.GraphQLSchema object specifying the schema associated with this endpoint.
Returns: GraphQL schema for the configured endpoint
-
post
(request: aiographql.client.request.GraphQLRequest, headers: Optional[Dict[str, str]] = None, operation: Optional[str] = None, variables: Optional[Dict[str, Any]] = None, session: Optional[aiohttp.client.ClientSession] = None) → aiographql.client.response.GraphQLResponse¶ Helper method that wraps GraphQLClient.query with method explicitly set as
GraphQLQueryMethod.post
.Parameters: - request – Request to send to the GraphQL server.
- headers – Additional headers to be set when sending HTTP request.
- operation – GraphQL operation name to use if the GraphQLRequest.query contains named operations. This will override any default operation set.
- variables – Query variables to set for the provided request. This will override the default values for any existing variables in the request if set.
- session – Optional aiohttp.ClientSession to use for requests
Returns: The resulting GraphQLResponse object.
-
query
(request: Union[aiographql.client.request.GraphQLRequest, str], method: Optional[str] = None, headers: Optional[Dict[str, str]] = None, operation: Optional[str] = None, variables: Optional[Dict[str, Any]] = None, session: Optional[aiohttp.client.ClientSession] = None) → aiographql.client.response.GraphQLResponse¶ Method to send provided
GraphQLRequest
to the configured endpoint as an HTTP request. This method handles the configuration of headers HTTP method specific handling of request parameters and/or data as required.- The order of precedence, least to greatest, of headers is as follows,
- client headers (
GraphQLClient.headers
) - request headers (
GraphQLRequest.headers
) - headers specified as method parameter
- client headers (
In accordance to the GraphQL specification, any non 2XX response is treated as an error and raises GraphQLTransactionException instance.
Parameters: - request – Request to send to the GraphQL server.
- method – HTTP method to use when submitting request (POST/GET). If once is not specified, the client default (GraphQLClient.method) is used.
- headers – Additional headers to be set when sending HTTP request.
- operation – GraphQL operation name to use if the GraphQLRequest.query contains named operations. This will override any default operation set.
- variables – Query variables to set for the provided request. This will override the default values for any existing variables in the request if set.
- session – Optional aiohttp.ClientSession to use for requests
Returns: The resulting response object.
-
subscribe
(request: aiographql.client.request.GraphQLRequest, headers: Optional[Dict[str, str]] = None, operation: Optional[str] = None, variables: Optional[Dict[str, Any]] = None, callbacks: Union[cafeteria.asyncio.callbacks.CallbackRegistry, Dict[aiographql.client.subscription.GraphQLSubscriptionEventType, Union[Callable, Coroutine[T_co, T_contra, V_co], Callback, List[Union[Callable, Coroutine[T_co, T_contra, V_co], Callback]]]], None] = None, on_data: Union[Callable, Coroutine[T_co, T_contra, V_co], Callback, None] = None, on_error: Union[Callable, Coroutine[T_co, T_contra, V_co], Callback, None] = None, session: Optional[aiohttp.client.ClientSession] = None) → aiographql.client.subscription.GraphQLSubscription¶ Create and initialise a GraphQL subscription. Once subscribed and a known event is received, all registered callbacks for the event type is triggered with the
aiographql.client.GraphQLSubscriptionEvent
instance passed in the first argument.The following example will start a subscription that prints all data events as it receives them.
# initialise and subscribe to events in the background subscription: GraphQLSubscription = await client.subscribe( request="{ notifications: { id, summary } }", on_data=lambda event: print(f"Data: {event}"), on_error=lambda event: print(f"Error: {event}"), ) # process events for 10 seconds then unsubscribe await asyncio.wait(subscription.task, timeout=10) subscription.unsubscribe()
Parameters: - request – Request to send to the GraphQL server.
- headers – Additional headers to be set when sending HTTP request.
- operation – GraphQL operation name to use if the GraphQLRequest.query contains named operations. This will override any default operation set.
- variables – Query variables to set for the provided request. This will override the default values for any existing variables in the request if set.
- session – Optional aiohttp.ClientSession to use for requests
- callbacks – Custom callback registry mapping an event to one more more callback methods. If not provided, a new instance is created.
- on_data – Callback to use when data event is received.
- on_error – Callback to use when an error occurs.
- session – Optional session to use for connecting the graphql endpoint, if one is not provided, a new session is created for the duration of the subscription.
Returns: The resulting GraphQLResponse object.
Returns: The initialised subscription.
-
validate
(request: aiographql.client.request.GraphQLRequest, schema: Optional[graphql.type.schema.GraphQLSchema] = None, headers: Optional[Dict[str, str]] = None, force: bool = False) → None¶ Validate a given request against a schema (provided or fetched). Validation is skipped if the request’s validate property is set to False unless forced.
Parameters: - request – Request that is to be validated.
- schema – Schema against which provided request should be validated, if different from GraphQLRequest.schema or as fetched from the client endpoint.
- headers – Headers to be set when fetching the schema from the client endpoint. If provided, request headers are ignored.
- force – Force validation even if the provided request has validation disabled.
GraphQLSubscription¶
-
class
aiographql.client.
GraphQLSubscription
(request: GraphQLRequest, headers: InitVar[Optional[Dict[str, str]]] = None, operation: InitVar[Optional[str]] = None, variables: InitVar[Optional[Dict[str, Any]]] = None, callbacks: Optional[CallbacksType] = <factory>, stop_event_types: List[GraphQLSubscriptionEventType] = <factory>)¶ Subscription container, with an attached
cafeteria.asyncio.callbacks.CallbackRegistry
. When subscribed, the task will be populated with theasyncio.Task
instance.By default the subscription will be stopped, if an error, connection error or complete (
GraphQLSubscriptionEventType
) is received.Subscription instances are intended to be used as immutable objects. However, callbacks and stop_event_types can be updated after initialisation.
Parameters: - id – A unique subscription identifier that will be passed into any events generated by this subscription.
- callbacks – A
CallbackRegistry
containing a mapping ofGraphQLSubscriptionEventType
callback methods to trigger. - stop_event_types – Events that cause the subscription to stop. By default, connection error, query error or connection complete events received are considered stop events.
-
active
() → bool¶ Check if the subscription is active.
Returns: True if subscribed and active.
-
connection_init_request
() → Dict[str, Any]¶ Connection init payload to use when initiating a new subscription.
Returns: Connection initialise payload.
-
connection_start_request
() → Dict[str, Any]¶ Connection start payload to use when starting a subscription.
Returns: Connection start payload.
-
connection_stop_request
() → Dict[str, Any]¶ Connection stop payload to use when stopping a subscription.
Returns: Connection stop payload.
-
handle
(event: aiographql.client.subscription.GraphQLSubscriptionEvent) → NoReturn¶ Helper method to dispatch any configured callbacks for the specified event type.
Parameters: event – Event to dispatch callbacks for.
-
is_stop_event
(event: aiographql.client.subscription.GraphQLSubscriptionEvent) → bool¶ Check if the provided event is configured as a stop even for this subscription.
Parameters: event – Event to check. Returns: True if event is in stop_event_types.
-
subscribe
(endpoint: str, force: bool = False, session: Optional[aiohttp.client.ClientSession] = None) → None¶ Create a websocket subscription and set internal task.
Parameters: - endpoint – GraphQL endpoint to subscribe to
- force – Force re-subscription if already subscribed
- session – Optional session to use for requests
-
unsubscribe
() → None¶ Unsubscribe current websocket subscription if active and clear internal task.
Data Containers¶
GraphQLRequest¶
-
class
aiographql.client.
GraphQLRequest
(query: str, operation: InitVar[Optional[str]] = None, variables: Dict[str, Any] = <factory>, validate: bool = True, headers: Dict[str, str] = <factory>)¶ GraphQL Request object that can be reused or used to store multiple named queries with default operationName`, *variables and header to use.
Parameters: - query – GraphQL query string.
- operation – Optional name of operation to use from the query.
- variables – Variable dictionary pass with the query to the server.
- validate – If True, the request query is validated against the latest available schema from the server.
- headers – Headers to use, in addition to client default headers when making the HTTP request.
GraphQLResponse¶
-
class
aiographql.client.
GraphQLResponse
(request: GraphQLRequest, headers: InitVar[Optional[Dict[str, str]]] = None, operation: InitVar[Optional[str]] = None, variables: InitVar[Optional[Dict[str, Any]]] = None, json: Dict[str, Any] = <factory>)¶ GraphQL Response object wrapping response data and any errors. This object also contains the a copy of the
GraphQLRequest
that produced this response.-
data
¶ The data payload the server responded with.
-
errors
¶ A list of
GraphQLError
objects if server responded with query errors.
-
query
¶ The query string used to produce this response.
-
GraphQLSubscriptionEvent¶
-
class
aiographql.client.
GraphQLSubscriptionEvent
(request: GraphQLRequest, headers: InitVar[Optional[Dict[str, str]]] = None, operation: InitVar[Optional[str]] = None, variables: InitVar[Optional[Dict[str, Any]]] = None, json: Dict[str, Any] = <factory>, subscription_id: Optional[str] = None)¶ GraphQL subscription event wrapping the payload received from the server.
Parameters: subscription_id – The id of the subscription that generated this event. -
id
¶ The id of the event, if available.
-
payload
¶ The id of the subscription that generated this event.
-
type
¶ The type of event (
GraphQLSubscriptionEventType
).
-
Constants¶
GraphqQLQueryMethod¶
GraphQLSubscriptionEventType¶
-
class
aiographql.client.
GraphQLSubscriptionEventType
¶ GraphQL Subscription Event Types
-
COMPLETE
= 'complete'¶
-
CONNECTION_ACK
= 'connection_ack'¶
-
CONNECTION_ERROR
= 'connection_error'¶
-
CONNECTION_INIT
= 'connection_init'¶
-
CONNECTION_TERMINATE
= 'connection_terminate'¶
-
DATA
= 'data'¶
-
ERROR
= 'error'¶
-
KEEP_ALIVE
= 'ka'¶
-
START
= 'start'¶
-
STOP
= 'stop'¶
-