Starlette-Graphene3

0.6.0 · active · verified Thu Apr 16

Starlette-Graphene3 is an ASGI application for seamlessly integrating Graphene v3 with Starlette and FastAPI. It provides support for GraphQL queries, mutations, subscriptions (over WebSockets), file uploading, and includes built-in GraphiQL/GraphQL Playground interfaces. The current version is 0.6.0, and releases appear to be infrequent, primarily driven by updates to underlying dependencies like Graphene and Starlette.

Common errors

```
ERROR: fastapi X.Y.Z has requirement starlette==A.B.C, but you'll have starlette D.E.F which is incompatible.
```
cause A version mismatch between FastAPI's required Starlette version and the version required by `starlette-graphene3`.

fix Update FastAPI and `starlette-graphene3` to their latest compatible versions. Check the dependency trees (e.g., `pip check` or inspect `pyproject.toml` files) to find compatible ranges. Often, upgrading FastAPI resolves this.
```
TypeError: Cannot return null for non-nullable field X.id.
```
cause This error often occurs when an asynchronous Graphene resolver is not properly awaited, causing a `Coroutine` object to be returned where a concrete value is expected, or if a non-nullable field indeed returns `None`.

fix Verify that all asynchronous resolvers are `await`ed correctly within the execution context. If writing custom execution logic, ensure `inspect.isawaitable()` is used and `await` is applied. Also, double-check that non-nullable fields genuinely return a value and not `None`.

Warnings

breaking Starlette's native GraphQLApp was removed in Starlette 0.17.0 (deprecated in 0.15.0). Applications relying on `from starlette.graphql import GraphQLApp` must migrate to third-party libraries like `starlette-graphene3` for Graphene v3 support.
Fix: Replace `from starlette.graphql import GraphQLApp` with `from starlette_graphene3 import GraphQLApp` and ensure your Graphene schema is compatible with Graphene v3.
gotcha When integrating with FastAPI, older versions (e.g., FastAPI 0.63.0) might have strict Starlette dependency requirements (e.g., `starlette==0.13.6`) that conflict with `starlette-graphene3`'s requirement (`starlette>=0.14.1`).
Fix: Upgrade FastAPI to a newer version that allows a compatible Starlette range, or carefully manage your `starlette` dependency to satisfy both libraries. Using a newer FastAPI is generally recommended.
gotcha For GraphQL file upload functionality, the `python-multipart` library must be installed separately. The base `starlette-graphene3` installation does not include it.
Fix: Run `pip install 'starlette-graphene3[all]'` or `pip install python-multipart` alongside `starlette-graphene3`.
gotcha Asynchronous resolvers (defined with `async def`) in Graphene 3 require proper handling of the awaitable return value in custom middleware or field resolvers, otherwise they might not execute correctly or lead to `TypeError: Cannot return null for non-nullable field` issues.
Fix: Ensure that custom Graphene execution logic correctly awaits coroutine objects returned by resolvers. The default `GraphQLApp` should handle this correctly, but custom executors or resolvers might need explicit `await` calls if they override core behavior.

Install

pip install starlette-graphene3 Stable Release
pip install 'starlette-graphene3[all]' # Includes python-multipart for file uploads With File Upload Support
pip install uvicorn ASGI Server (e.g., Uvicorn)

Imports

GraphQLApp
wrong:
```
from starlette.graphql import GraphQLApp
```
correct:
```
from starlette_graphene3 import GraphQLApp
```
Starlette's built-in GraphQLApp was deprecated in Starlette 0.15.0 and removed in 0.17.0, requiring migration to third-party libraries like starlette-graphene3 for Graphene v3 support.
make_graphiql_handler
```
from starlette_graphene3 import make_graphiql_handler
```
Used to serve the GraphiQL interactive IDE for GraphQL queries.

Quickstart

This quickstart demonstrates setting up a basic Starlette application with GraphQL using `starlette-graphene3`. It defines a simple query and a subscription, then mounts the `GraphQLApp` at the root path with the GraphiQL handler enabled for an interactive interface.

import asyncio
import graphene
from starlette.applications import Starlette
from starlette_graphene3 import GraphQLApp, make_graphiql_handler

class User(graphene.ObjectType):
    id = graphene.ID()
    name = graphene.String()

class Query(graphene.ObjectType):
    me = graphene.Field(User)

    def resolve_me(root, info):
        # In a real app, this would fetch data from a database or service
        return User(id="1", name="Test User")

class Subscription(graphene.ObjectType):
    count = graphene.Int(upto=graphene.Int())

    async def subscribe_count(root, info, upto=3):
        for i in range(upto):
            yield i
            await asyncio.sleep(1)

app = Starlette()
schema = graphene.Schema(query=Query, subscription=Subscription)

app.mount("/", GraphQLApp(schema, on_get=make_graphiql_handler()))

# To run this example, save it as `main.py` and execute:
# uvicorn main:app --reload
# Then open your browser to http://127.0.0.1:8000/

view raw JSON →