{"id":9336,"library":"starlette-graphene3","title":"Starlette-Graphene3","description":"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.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/ciscorn/starlette-graphene3","tags":["starlette","graphene","graphql","asgi","fastapi","websocket","subscriptions"],"install":[{"cmd":"pip install starlette-graphene3","lang":"bash","label":"Stable Release"},{"cmd":"pip install 'starlette-graphene3[all]' # Includes python-multipart for file uploads","lang":"bash","label":"With File Upload Support"},{"cmd":"pip install uvicorn","lang":"bash","label":"ASGI Server (e.g., Uvicorn)"}],"dependencies":[{"reason":"Core GraphQL library for defining schemas, types, queries, mutations, and subscriptions.","package":"graphene","optional":false},{"reason":"Required by Graphene for GraphQL execution.","package":"graphql-core","optional":false},{"reason":"ASGI web framework that this library integrates with.","package":"starlette","optional":false},{"reason":"Enables file uploading functionality through GraphQL.","package":"python-multipart","optional":true},{"reason":"A highly performant ASGI server commonly used to run Starlette applications in development and production.","package":"uvicorn","optional":true}],"imports":[{"note":"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.","wrong":"from starlette.graphql import GraphQLApp","symbol":"GraphQLApp","correct":"from starlette_graphene3 import GraphQLApp"},{"note":"Used to serve the GraphiQL interactive IDE for GraphQL queries.","symbol":"make_graphiql_handler","correct":"from starlette_graphene3 import make_graphiql_handler"}],"quickstart":{"code":"import asyncio\nimport graphene\nfrom starlette.applications import Starlette\nfrom starlette_graphene3 import GraphQLApp, make_graphiql_handler\n\nclass User(graphene.ObjectType):\n    id = graphene.ID()\n    name = graphene.String()\n\nclass Query(graphene.ObjectType):\n    me = graphene.Field(User)\n\n    def resolve_me(root, info):\n        # In a real app, this would fetch data from a database or service\n        return User(id=\"1\", name=\"Test User\")\n\nclass Subscription(graphene.ObjectType):\n    count = graphene.Int(upto=graphene.Int())\n\n    async def subscribe_count(root, info, upto=3):\n        for i in range(upto):\n            yield i\n            await asyncio.sleep(1)\n\napp = Starlette()\nschema = graphene.Schema(query=Query, subscription=Subscription)\n\napp.mount(\"/\", GraphQLApp(schema, on_get=make_graphiql_handler()))\n\n# To run this example, save it as `main.py` and execute:\n# uvicorn main:app --reload\n# Then open your browser to http://127.0.0.1:8000/","lang":"python","description":"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."},"warnings":[{"fix":"Replace `from starlette.graphql import GraphQLApp` with `from starlette_graphene3 import GraphQLApp` and ensure your Graphene schema is compatible with Graphene v3.","message":"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.","severity":"breaking","affected_versions":"Starlette >=0.15.0"},{"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.","message":"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`).","severity":"gotcha","affected_versions":"FastAPI <0.68.0 (approx), starlette-graphene3 all versions"},{"fix":"Run `pip install 'starlette-graphene3[all]'` or `pip install python-multipart` alongside `starlette-graphene3`.","message":"For GraphQL file upload functionality, the `python-multipart` library must be installed separately. The base `starlette-graphene3` installation does not include it.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Graphene v3 (all versions used by starlette-graphene3)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"A version mismatch between FastAPI's required Starlette version and the version required by `starlette-graphene3`.","error":"ERROR: fastapi X.Y.Z has requirement starlette==A.B.C, but you'll have starlette D.E.F which is incompatible."},{"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`.","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`.","error":"TypeError: Cannot return null for non-nullable field X.id."}]}