starlette-graphene

A focused GraphQL-over-HTTP ASGI application for Graphene and Starlette.

Requirements

• Python 3.11–3.14
• Graphene 3.x
• Starlette

Install

uv add starlette-graphene graphene starlette

pip install starlette-graphene

Quick start

import graphene
from starlette.applications import Starlette

from starlette_graphene import GraphQLApp


class Query(graphene.ObjectType):
    hello = graphene.String()

    @staticmethod
    def resolve_hello(root, info):
        return "Hello, world!"


app = Starlette()
app.mount("/graphql", GraphQLApp(graphene.Schema(query=Query)))

Send a JSON operation:

curl -X POST http://127.0.0.1:8000/graphql \
  -H 'content-type: application/json' \
  --data '{"query":"{ hello }"}'

{"data":{"hello":"Hello, world!"}}

Context

Use context_value for a static context, or pass a sync/async callable that accepts the Starlette request connection. The callable result becomes info.context.

async def build_context(connection):
    return {"request": connection}

app.mount("/graphql", GraphQLApp(schema, context_value=build_context))

HTTP behavior

The endpoint accepts JSON and raw-GraphQL POST requests, and read-only GET requests. It returns GraphQL execution errors in the response body; malformed transport input receives an HTTP 4xx response. See the HTTP API reference for the full contract.

Migration

Version 1.0 removes the embedded GraphiQL page and changes several transport behaviors. Read the 1.0 migration guide before upgrading from 0.x.

Development

uv sync --all-groups
make lint
make test
make build

make test enforces 100% branch coverage for the supported public contract.

License

starlette-graphene is distributed under the Apache License 2.0.