Ariadne

1.0.1 · active · verified Fri Apr 10

Ariadne is a Python library for implementing GraphQL servers using a schema-first approach. It emphasizes a simple, extensible API for defining GraphQL schemas using Schema Definition Language (SDL) and connecting business logic with minimal boilerplate. It supports queries, mutations, subscriptions, custom scalars, and integrates with ASGI/WSGI frameworks like Django, FastAPI, Flask, and Starlette. The project maintains an active and frequent release cadence, with regular patch, minor, and occasional alpha releases, as seen with versions like 1.0.1 and subsequent 1.1.0a2.

Warnings

breaking Version 1.0.0 introduced several breaking changes including the removal of deprecated `EnumType.bind_to_default_values`, Apollo tracing, OpenTracing, and `extend_federated_schema`. It also made base handler class names consistent and adjusted `convert_names_case` behavior.
Fix: Consult the official migration guide (linked in GitHub release notes for 1.0.0) to update your codebase. Replace removed functionalities with their modern equivalents or adjust naming conventions.
breaking In version 0.29.0, deprecated utilities `FallbackResolvers` and `convert_kwargs_to_snake_case` were removed, along with legacy code paths for versions prior to 0.20.
Fix: Migrate from `FallbackResolvers` to standard resolver patterns. If you relied on `convert_kwargs_to_snake_case` for automatic argument case conversion, you will need to implement this conversion manually in your resolvers or use other utility functions if available in newer versions.
gotcha The `errors` key in GraphQL responses is intended for technical errors (e.g., parsing, validation, execution issues), not for communicating application-level business logic errors (like permission denied or validation failures to end-users).
Fix: For user-facing errors, define custom fields within your GraphQL types (e.g., `type Mutation { login(data: LoginInput): LoginPayload } type LoginPayload { user: User error: String }`) to return specific error messages as part of the data payload.

Install

pip install ariadne uvicorn Install Ariadne and Uvicorn (ASGI server for quickstart)

Imports

gql
```
from ariadne import gql
```
Used to parse GraphQL Schema Definition Language (SDL) strings.
QueryType
```
from ariadne import QueryType
```
Used to define resolvers for queries.
make_executable_schema
```
from ariadne import make_executable_schema
```
Combines schema definitions and resolvers into a runnable GraphQL schema.
start_dev_server
```
from ariadne import start_dev_server
```
Provides a convenient development server with GraphiQL explorer. For production, integrate with ASGI/WSGI frameworks like FastAPI or Flask.

Quickstart

This quickstart sets up a basic Ariadne GraphQL server with a 'Person' type and a 'people' query. It defines the schema in SDL, creates a resolver for the 'people' field, and runs a development server with GraphiQL for interactive API exploration.

from ariadne import gql, QueryType, make_executable_schema, start_dev_server

# Define GraphQL schema using Schema Definition Language (SDL)
type_defs = gql("""
    type Query {
        people: [Person!]!
    }

    type Person {
        firstName: String!
        lastName: String!
    }
""")

# Create a QueryType instance to define query resolvers
query = QueryType()

# Define the resolver for the 'people' field
@query.field("people")
def resolve_people(*_):
    return [
        {"firstName": "John", "lastName": "Doe"},
        {"firstName": "Jane", "lastName": "Smith"},
    ]

# Combine type definitions and resolvers into an executable schema
schema = make_executable_schema(type_defs, query)

# Run the development server
if __name__ == "__main__":
    # Access the GraphQL endpoint and GraphiQL at http://127.0.0.1:8000
    start_dev_server(schema, port=8000)

view raw JSON →