ariadne-codegen

ariadne-codegen is a Python code generator that converts GraphQL schemas and operations into a fully typed, async (or sync) Python client built on Pydantic.

Key capabilities include:

• Fully typed models: Pydantic models for schema types, inputs, enums, fragments, and operation results.
• Typed client methods: Each operation becomes a method with typed arguments and return values.
• Async or sync: Generate an async client (default) or a synchronous one.
• Subscriptions: Real-time updates via WebSockets (graphql-transport-ws).
• File uploads: Support for multipart requests via the GraphQL multipart request spec.
• Custom scalars: Map GraphQL scalars to Python types using serialize/parse hooks.
• Extensible output: Inject mixins, copy files, or swap the base client (e.g., for custom auth or removing httpx/websockets dependencies).
• Flexible schema sources: Load schemas from local files, installed Python packages, or remote introspection.
• Plugin system: Customize generation via hooks.
• Advanced features: Programmatic query building, OpenTelemetry tracing, multiple clients per project, and schema-copy mode.

Use the @mixin directive in your GraphQL schema to extend generated classes with custom logic by adding extra base classes. This allows you to inject custom methods or properties into the generated models.

The directive requires two string literal arguments:

• from: The module path to import from.
• import: The name of the parent class to inherit from.

Important details:

• You do not need to declare the @mixin directive in your schema definition; ariadne-codegen registers it automatically.
• The directive only adds the import statement and the base class to the generated class; it does not copy any code. The imported module must be reachable in the runtime environment.
• If using a relative import (e.g., from: ".mixins"), you must include the corresponding file in your configuration using the files_to_include option.
• If using an absolute import (e.g., from: "my_package.mixins"), the module must be installable in your environment.
• If arguments are missing or are not string literals, generation will fail with a ParsingError.

fragment UserData on User @mixin(from: ".mixins", import: "UsersMixin") {
    id
}

When enable_custom_operations is enabled, ariadne-codegen generates several specialized modules to facilitate programmatic query building:

• custom_fields.py: Contains ...Fields classes for every object type in your schema, used to select specific fields.
• custom_typing_fields.py: Provides supporting types for field selection.
• custom_queries.py: Contains a Query class with builder methods for every root query field (if a Query type exists in the schema).
• custom_mutations.py: Contains a Mutation class with builder methods for every root mutation field (if a Mutation type exists in the schema).

To execute these built operations, the Client gains three new methods:

• query(...)
• mutation(...)
• execute_custom_operation(...)

Important Note on Return Types: Unlike the standard per-operation client methods which return parsed Pydantic models, client.query(...) and client.mutation(...) return the raw response as a dict[str, Any].

When you run the code generator, it produces a Python package (e.g., graphql_client/) containing several specialized files. The package structure typically includes:

• __init__.py: Contains re-imports and exports all generated classes for easy access.
• client.py: The main Client class containing async methods for every query, mutation, and subscription.
• async_base_client.py: The base class that the generated Client inherits from.
• base_model.py: Contains the BaseModel (extending Pydantic) used by all generated models.
• input_types.py: Models generated from GraphQL input types, used as arguments in client methods.
• enums.py: Python Enum classes generated from GraphQL enums.
• fragments.py: Classes generated from GraphQL fragments used in operations.
• exceptions.py: Custom exception classes for error handling.
• Operation-specific files (e.g., create_user.py, list_all_users.py): Each file contains the model corresponding to the return type of a specific operation. The filename is the snake_case version of the operation name.

Use schema_paths to build a single schema from multiple sources. Each entry is first treated as a local filesystem path; if not found, it is treated as a dotted Python import path.

Supported entry types:

• Local directory: All .graphql, .graphqls, and .gql files are included recursively.
• Local file: A specific file to be used.
• Python callable: An absolute import path to a callable that returns a list[str] of file paths.
• Python variable (file): An absolute import path to a variable holding a single schema file path.
• Python variable (directory): An absolute import path to a variable holding a directory path (all .graphql, .graphqls, and .gql files are included).

Note: schema_path, schema_paths, and remote_schema_url are mutually exclusive; you can only use one of these settings at a time.

[tool.ariadne-codegen]
schema_paths = [
  "some_gql_commontypes.get_schema_files",   # callable -> returns list of paths
  "other_pkg.SCHEMA_DIR",                     # variable -> directory
  "./my_other_packages/",                     # local directory
  "./foo/bar.graphql",                        # local file
]
queries_path = "queries.graphql"