Getting started

aiographql-client is a modern, lightweight, and type-safe Python client for GraphQL, built on top of asyncio, aiohttp, and graphql-core. It is designed for developers who value performance, flexibility, and a great developer experience.

Key Features

  • Async-first: Built from the ground up for asyncio.

  • Multiple Transports: Support for both aiohttp (default) and httpx.

  • Subscriptions: Built-in support for GraphQL subscriptions over WebSockets.

  • Type Safety: Leverages graphql-core for query validation and Pydantic/dataclasses for data modeling.

  • Flexible Configuration: Easily customize headers, timeouts, and connection pools.

  • Production Ready: Used in high-performance production environments.

Quick Start

Getting started is as simple as passing your GraphQL query to aiographql.client.GraphQLClient.query().

import asyncio
from aiographql.client import GraphQLClient

async def main():
    # Initialize the client
    client = GraphQLClient(
        endpoint="https://countries.trevorblades.com/",
    )

    # Execute a simple query
    response = await client.query("{ countries { name code } }")

    # Access data
    if not response.errors:
        for country in response.data["countries"][:5]:
            print(f"{country['name']} ({country['code']})")
    else:
        print(f"Errors: {response.errors}")

if __name__ == "__main__":
    asyncio.run(main())

For more detailed examples on how to use the library, see Usage Examples.

Hint

The JS GraphQL plugin allows for easier working with GraphQL and also adds auto-complete during development.

Available Extras

  • aiohttp: Installs aiohttp for the default HTTP transport and WebSocket subscriptions.

  • httpx: Installs httpx for the alternative HTTP transport and websockets for subscriptions.

  • pydantic: Installs pydantic (v2) for enhanced data modeling and validation.

Installation

pip install "aiographql-client[aiohttp,pydantic]"

poetry add "aiographql-client[aiohttp,pydantic]"