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
asyncandawaitfor 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
For simple APIs, register plain functions directly — no class required:
# example.py
from graphql_api.api import GraphQLAPI
api = GraphQLAPI()
@api.query
def hello(name: str = "World") -> str:
"""A classic greeting."""
return f"Hello, {name}!"
@api.mutation
def set_name(name: str) -> str:
return f"Name set to {name}"
if __name__ == "__main__":
result = api.execute('query { hello(name: "Developer") }')
print(result.data)
$ python example.py
{'hello': 'Hello, Developer!'}
Use @api.query, @api.mutation, and @api.subscription for root-level
fields. For nested object types, reach for the class-based form below.
Class-based form
When you need object types with their own fields (relationships, computed properties, nested resolvers), define a root class:
from graphql_api.api import GraphQLAPI
api = GraphQLAPI()
@api.type(is_root_type=True)
class Query:
"""The root query for our amazing API."""
@api.field
def hello(self, name: str = "World") -> str:
return f"Hello, {name}!"
result = api.execute('query { hello(name: "Developer") }')
print(result.data)
# {'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
1 maintainer
Metadata
1 maintainer
Release files for graphql-api 1.6.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| graphql_api-1.6.10.tar.gz | 266.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| graphql_api-1.6.10-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 340.0 kB
Release files / graphql_api-1.6.10.tar.gz
| Download URL | graphql_api-1.6.10.tar.gz |
|---|---|
| Size | 266.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a43648d9100b2a4093d2cf4a959d8da93ad3f539fe8d1e01927df8f2cf2213e8
|
|
BLAKE2b-256 checksum How to use checksums |
3a95cf16f1854a0337287db067b9af347ad3aa6b0b00086efdd40ec10c7ad94d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.6 {"installer":{"name":"uv","version":"0.12.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / graphql_api-1.6.10-py3-none-any.whl
| Download URL | graphql_api-1.6.10-py3-none-any.whl |
|---|---|
| Size | 73.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3743082fdae44f486eb7cf942bb8e3ef8774a2e506406e018a5954b0115ab480
|
|
BLAKE2b-256 checksum How to use checksums |
281fe4774d032d622a321f9df71bc7c806ab5186efa2425267c87f3f2b5649ed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.6 {"installer":{"name":"uv","version":"0.12.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
