graphql-api

GraphQL-API for Python

Documentation | PyPI | GitHub

A powerful and intuitive Python library for building GraphQL APIs, designed with a code-first, decorator-based approach.

graphql-api simplifies schema definition by leveraging Python's type hints, dataclasses, and Pydantic models, allowing you to build robust and maintainable GraphQL services with minimal boilerplate.

Key Features

• Decorator-Based Schema: Define your GraphQL schema declaratively using simple and intuitive decorators.
• Type Hinting: Automatically converts Python type hints into GraphQL types.
• Implicit Type Inference: Automatically maps Pydantic models, dataclasses, and classes with fields - no explicit decorators needed.
• Pydantic & Dataclass Support: Seamlessly use Pydantic and Dataclass models as GraphQL types.
• Asynchronous Execution: Full support for async and await for high-performance, non-blocking resolvers.
• Apollo Federation: Built-in support for creating federated services.
• Subscriptions: Implement real-time functionality with GraphQL subscriptions.
• Middleware: Add custom logic to your resolvers with a flexible middleware system.
• Relay Support: Includes helpers for building Relay-compliant schemas.

Installation

pip install graphql-api

Quick Start

Create a simple GraphQL API in just a few lines of code.

# example.py
from graphql_api.api import GraphQLAPI

# 1. Initialize the API
api = GraphQLAPI()

# 2. Define your root type with decorators
@api.type(is_root_type=True)
class Query:
    """
    The root query for our amazing API.
    """
    @api.field
    def hello(self, name: str = "World") -> str:
        """
        A classic greeting.
        """
        return f"Hello, {name}!"

# 3. Define a query
graphql_query = """
    query Greetings {
        hello(name: "Developer")
    }
"""

# 4. Execute the query
if __name__ == "__main__":
    result = api.execute(graphql_query)
    print(result.data)

Running this script will produce:

$ python example.py
{'hello': 'Hello, Developer'}

Examples

Using Pydantic Models

Leverage Pydantic for data validation and structure. graphql-api will automatically convert your models into GraphQL types.

from pydantic import BaseModel
from typing import List
from graphql_api.api import GraphQLAPI

class Book(BaseModel):
    title: str
    author: str

@api.type(is_root_type=True)
class BookAPI:
    @api.field
    def get_books(self) -> List[Book]:
        return [
            Book(title="The Hitchhiker's Guide to the Galaxy", author="Douglas Adams"),
            Book(title="1984", author="George Orwell"),
        ]

api = GraphQLAPI()

graphql_query = """
    query {
        getBooks {
            title
            author
        }
    }
"""

result = api.execute(graphql_query)
# result.data will contain the list of books

Asynchronous Resolvers

Define async resolvers for non-blocking I/O operations.

import asyncio
from graphql_api.api import GraphQLAPI

api = GraphQLAPI()

@api.type(is_root_type=True)
class AsyncAPI:
    @api.field
    async def fetch_data(self) -> str:
        await asyncio.sleep(1)
        return "Data fetched successfully!"

# To execute async queries, you'll need an async executor
# or to run it within an async context.
async def main():
    result = await api.execute("""
        query {
            fetchData
        }
    """)
    print(result.data)

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

Mutations with Dataclasses

Use dataclasses to define the structure of your data, and mark fields as mutable to automatically separate them into the GraphQL Mutation type.

from dataclasses import dataclass
from graphql_api.api import GraphQLAPI

@dataclass
class User:
    id: int
    name: str

# A simple in-memory database
db = {1: User(id=1, name="Alice")}

api = GraphQLAPI()

@api.type(is_root_type=True)
class Root:
    @api.field
    def get_user(self, user_id: int) -> User:
        return db.get(user_id)

    @api.field(mutable=True)
    def add_user(self, user_id: int, name: str) -> User:
        new_user = User(id=user_id, name=name)
        db[user_id] = new_user
        return new_user

GraphQL automatically separates queries and mutations - you don't need separate classes. Fields marked with mutable=True are placed in the Mutation type, while regular fields go in the Query type. Fields with AsyncGenerator return types are automatically detected as subscriptions. This automatic mapping means you can define all your operations in a single class and let graphql-api handle the schema organization for you.

Related Projects

• graphql-http - Serve your API over HTTP with authentication and GraphiQL
• graphql-db - SQLAlchemy integration for database-backed APIs
• graphql-mcp - Expose your API as MCP tools for AI agents

See the documentation for advanced schema patterns, federation, remote GraphQL, and more.

Documentation

Visit the official documentation for comprehensive guides, tutorials, and API reference.

Key Topics

• Getting Started - Quick introduction and basic usage
• Defining Schemas - Learn schema definition patterns
• Field Types - Understanding GraphQL type system
• Mutations - Implementing data modifications
• Remote GraphQL - Connect to remote APIs
• Federation - Apollo Federation support
• API Reference - Complete API documentation

Running Tests

To contribute or run the test suite locally:

# Install dependencies
uv sync

# Run tests
uv run pytest