01-introduction.md

title	Introduction
slug	/

Ariadne Code Generator

Python code generator that turns a GraphQL schema and your operations into a fully typed, async (or sync) Python client built on Pydantic. You write your queries, mutations and subscriptions in GraphQL, and ariadne-codegen generates a typed Python method for each one, returning Pydantic models - so you get autocompletion and static type checking instead of hand-writing query strings and parsing raw JSON.

📖 Documentation · Step-by-step example · Configuration reference

Features

• Fully typed models - Pydantic models for schema types, inputs, enums, fragments, and every operation's result.
• Typed client methods - each query, mutation, and subscription becomes a method with typed arguments and a typed return value.
• Async or sync - generate an async client (default) or a synchronous one.
• Subscriptions - real-time updates over WebSockets (graphql-transport-ws).
• File uploads - multipart requests via the GraphQL multipart request spec.
• Custom scalars - map GraphQL scalars to your own Python types with serialize/parse hooks.
• Extensible output - inject mixins into generated models, copy in your own files, or swap the base client (custom auth, or to drop the httpx/websockets deps).
• Flexible schema sources - a local file, installed Python packages, or remote introspection.
• Plugin system - customize generation through hooks, plus ready-made plugins (shorter results, extracted operation strings, forward refs, …).
• More - programmatic query building, OpenTelemetry tracing, multiple clients per project, a schema-copy mode, and deprecation warnings for deprecated parts of your schema.

Installation

pip install ariadne-codegen

Add subscription (WebSocket) support with:

pip install ariadne-codegen[subscriptions]

Quickstart

Generate a typed client from three files.

1. Describe your schema in schema.graphql:

type Query {
  hello(name: String!): String!
}

2. Write the operations you need in queries.graphql:

query Greet($name: String!) {
  hello(name: $name)
}

3. Point ariadne-codegen at them in pyproject.toml:

[tool.ariadne-codegen]
schema_path = "schema.graphql"
queries_path = "queries.graphql"

Then generate the client:

ariadne-codegen

This creates a Python package (named graphql_client by default) next to your config, with the typed client and Pydantic models generated from your schema and operations:

graphql_client/
    __init__.py
    async_base_client.py   # networking base client
    base_model.py
    client.py              # the typed Client, with a greet() method
    enums.py
    exceptions.py
    greet.py               # result model for the Greet operation
    input_types.py

You get one result module per operation plus shared modules for enums, input types, fragments and scalars. Import the client and use it right away:

import asyncio
from graphql_client import Client


async def main():
    async with Client(url="https://example.com/graphql") as client:
        result = await client.greet(name="World")
        print(result.hello)


asyncio.run(main())

greet is a typed method generated from your Greet operation, and result is a validated Pydantic model. See the step-by-step example for a walk-through of everything that gets generated.

Contributing

Contributions are welcome! See Contributing for how to report bugs, work on issues, and open pull requests.

Also make sure you follow @AriadneGraphQL on Twitter for latest updates, news and random musings!

Crafted with ❤️ by Mirumee Labs ariadne@mirumee.com