gql: GraphQL Client for Python

Warnings

• breaking As of v4.0.0, the `gql()` and `dsl_gql()` functions now return a `GraphQLRequest` object instead of a `DocumentNode`. All `client.execute()` and `client.subscribe()` methods also now accept a `GraphQLRequest` object as their primary argument.
  Fix: Update calls to `gql()` and `dsl_gql()` to expect `GraphQLRequest` objects. Pass `GraphQLRequest` objects directly to `execute()` and `subscribe()` methods. The `GraphQLRequest` object encapsulates the document, variable values, and operation name.
• breaking The `AIOHTTPTransport`'s `ssl` parameter now defaults to `True` (enabling SSL certificate verification) starting from v4.0.0 (introduced in v4.0.0a0). Previously, it defaulted to `False` which could lead to security vulnerabilities by accepting self-signed certificates without warning.
  Fix: If your GraphQL endpoint uses a self-signed or otherwise untrusted SSL certificate and you need to bypass verification (not recommended for production), explicitly set `ssl=False` in the `AIOHTTPTransport` constructor. Otherwise, ensure your certificates are properly configured and trusted.
• breaking The `ConnectionClosed` exception has been replaced by `TransportConnectionClosed` for connection-related errors.
  Fix: Update any exception handling blocks to catch `TransportConnectionClosed` instead of `ConnectionClosed`. Import the new exception from `gql.transport.exceptions`.
• gotcha When using synchronous `client.execute()` or `client.subscribe()` methods from an asynchronous transport (like `AIOHTTPTransport`) in environments where an asyncio event loop is already running (e.g., Jupyter notebooks, IPython), it might cause issues or block. `gql` will try to run an event loop itself, which conflicts with an already running one.
  Fix: In such environments, explicitly use the asynchronous `await session.execute(query)` pattern within an `async def` function. If you must use synchronous client methods, consider using libraries like `nest_asyncio` to patch the event loop for compatibility.

Install

• pip install "gql[all]" Recommended with all optional dependencies
• pip install gql Minimal install

Imports

• Client

  from gql import Client

• gql

  from gql import gql

• AIOHTTPTransport

  from gql.transport.aiohttp import AIOHTTPTransport

• WSAsyncTransport

  from gql.transport.websockets import WSAsyncTransport

  Used for GraphQL subscriptions over WebSockets.
• GraphQLRequest

  from gql.graphql_request import GraphQLRequest

  As of v4.0.0, 'gql' and 'dsl_gql' functions return a 'GraphQLRequest' object, not a 'DocumentNode'. 'execute' methods also expect 'GraphQLRequest'.
• dsl_gql

  from gql.dsl import dsl_gql

• DSLQuery

  from gql.dsl import DSLQuery

• DSLSchema

  from gql.dsl import DSLSchema

Quickstart

This quickstart demonstrates how to set up an asynchronous `gql` client using `AIOHTTPTransport`, define a GraphQL query, and execute it. It includes handling potential authentication headers and uses the recommended `async with client as session:` pattern for managing connections. Ensure you have `aiohttp` installed (e.g., `pip install "gql[aiohttp]"` or `pip install "gql[all]"`) for this example to run.

import asyncio
import os
from gql import Client, gql
from gql.transport.aiohttp import AIOHTTPTransport

async def main():
    # Replace with your GraphQL endpoint
    # For a real application, consider using environment variables for the URL and auth.
    graphql_url = os.environ.get('GRAPHQL_ENDPOINT_URL', 'https://countries.trevorblades.com/graphql')
    auth_token = os.environ.get('GRAPHQL_AUTH_TOKEN', '')

    headers = {}
    if auth_token:
        headers['Authorization'] = f'Bearer {auth_token}'

    # Select your transport
    transport = AIOHTTPTransport(url=graphql_url, headers=headers)

    # Create a GraphQL client
    client = Client(transport=transport, fetch_schema_from_transport=True)

    # Provide a GraphQL query (now returns GraphQLRequest object in v4+)
    query = gql(
        """
        query getContinents {
            continents {
                code
                name
            }
        }
        """
    )

    # Using `async with` on the client will start a connection
    # and provide a `session` variable to execute queries on this connection.
    async with client as session:
        # Execute the query (now accepts GraphQLRequest object in v4+)
        result = await session.execute(query)
        print(result)

if __name__ == "__main__":
    # If an asyncio event loop is already running, use this instead:
    # import nest_asyncio
    # nest_asyncio.apply()
    # asyncio.run(main())
    asyncio.run(main())