GraphQL Server for Python

Common errors

• ModuleNotFoundError: No module named 'graphql_server.GraphQLView'

  cause Attempting to import `GraphQLView` (or `GraphQLRouter`) directly from the top-level `graphql_server` package, which is a meta-package and does not expose these symbols directly.
  fix Change the import to `from graphql_server.flask import GraphQLView` (for Flask) or `from graphql_server.starlette import GraphQLRouter` (for Starlette), etc., depending on your chosen framework.

• TypeError: 'NoneType' object is not callable

  cause Often occurs when the GraphQL schema is not properly defined, instantiated, or passed as an argument to `GraphQLView` or `GraphQLRouter`.
  fix Ensure you have a valid `graphene.Schema(...)` object (or equivalent) and that it's correctly passed as the `schema` argument when initializing your GraphQL endpoint handler.

• AssertionError: You must provide a 'schema' or 'schema_path' to GraphQLView.

  cause The `GraphQLView` or `GraphQLRouter` was instantiated without a valid GraphQL schema object or a path to a schema file.
  fix Provide a `graphene.Schema` instance (e.g., `GraphQLRouter(schema=my_graphene_schema)`) or a schema path if using an alternative schema loading mechanism.

Warnings

• breaking Version 3.x of `graphql-server` is a meta-package; direct imports like `from graphql_server import GraphQLView` are no longer valid. Instead, you must import from framework-specific submodules (e.g., `from graphql_server.flask import GraphQLView`).
  Fix: Update your import statements to point to the correct framework-specific submodule, such as `graphql_server.flask`, `graphql_server.starlette`, or `graphql_server.django`.
• gotcha Installing `graphql-server` installs all framework integrations by default. If you only need one (e.g., for Flask), it's more efficient to install the specific package (e.g., `pip install graphql-server-flask`).
  Fix: For smaller deployments or to manage dependencies more precisely, install only the specific framework integration package you intend to use (e.g., `pip install graphql-server-starlette`).
• gotcha GraphQL Server for Python relies on `graphql-core` for the underlying GraphQL implementation and `graphene` (or similar) for schema definition. Ensure these dependencies are correctly installed and your schema is properly constructed.
  Fix: Always define a valid `graphene.Schema` object or similar schema representation and pass it to your `GraphQLView` or `GraphQLRouter` instance. Check `graphql-core` and `graphene` documentation for schema building best practices.

Install

• pip install graphql-server Install all framework integrations
• pip install graphql-server-starlette # Or -flask, -django, etc. Install specific framework integration

Imports

• GraphQLRouter
  wrong:

  from graphql_server import GraphQLRouter

  correct:

  from graphql_server.starlette import GraphQLRouter

  GraphQLRouter is specific to the Starlette integration. Attempting to import directly from the top-level `graphql_server` package will result in a ModuleNotFoundError as `graphql-server` is a meta-package.
• GraphQLView
  wrong:

  from graphql_server import GraphQLView

  correct:

  from graphql_server.flask import GraphQLView

  GraphQLView is specific to the Flask integration. Direct import from `graphql_server` is incorrect due to the meta-package structure.
• run_http_query

  from graphql_server_core.http import run_http_query

  This is a core utility for HTTP query execution, part of the `graphql-server-core` package, which is a dependency of `graphql-server`.

Quickstart

This quickstart demonstrates setting up a basic GraphQL server with Starlette and `graphql-server-starlette`. It defines a simple schema using `graphene`, then exposes it via `GraphQLRouter` at `/graphql` and a GraphQL Playground UI at `/graphql-playground`. You'll need `starlette`, `uvicorn`, `graphene`, and `graphql-server` installed.

import graphene
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route
from graphql_server.starlette import GraphQLRouter

# 1. Define your GraphQL schema using Graphene
class Query(graphene.ObjectType):
    hello = graphene.String(name=graphene.String(default_value="World"))

    def resolve_hello(self, info, name):
        return f"Hello, {name}!"

schema = graphene.Schema(query=Query)

# 2. Integrate with Starlette using GraphQLRouter
async def homepage(request):
    return JSONResponse({"message": "Visit /graphql for the API or /graphql-playground for the UI."}) 

routes = [
    Route("/", homepage),
    Route("/graphql", GraphQLRouter(schema)),
    Route("/graphql-playground", GraphQLRouter(schema, playground=True))
]

app = Starlette(routes=routes)

# To run this app, save it as `app.py` and execute:
# uvicorn app:app --reload
# Then visit http://127.0.0.1:8000/graphql-playground in your browser.