tartiflette-starlette 0.2.0

tartiflette-starlette is a wrapper that provides ASGI support for the Tartiflette Python GraphQL engine.

Build your GraphQL API with Tartiflette, then use the included TartifletteApp and get the following:

• Compatibility with any ASGI server and framework.
• Standalone and sub-app serving.
• Built-in GraphiQL client.

Note: WebSocket subscriptions aren't supported yet.

Table of contents

• Quickstart
• Installation
• User guide
• API Reference
• FAQ

Quickstart

from tartiflette import Resolver
from tartiflette_starlette import TartifletteApp

@Resolver("Query.hello")
async def hello(parent, args, context, info):
    name = args["name"]
    return f"Hello, {name}!"

sdl = """
  type Query {
    hello(name: String): String
  }
"""

app = TartifletteApp(sdl=sdl)

Save the file as graphql.py and start a uvicorn server:

uvicorn graphql:app

Note: the GraphQL endpoint is exposed on / by default.

Make a request:

curl -H "Content-Type: application/graphql"  -d '{ hello(name: "Chuck") }' http://localhost:8000

Response:

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

Or access http://localhost:8000 in a browser to make interactive queries using the built-in GraphiQL client:

Installation

1. Install Tartiflette's external dependencies as explained in the Tartiflette tutorial.
2. Install tartiflette-starlette from PyPI:

pip install tartiflette-starlette

This will also install Tartiflette and Starlette, so you're good to go!

Note: tartiflette-starlette requires Python 3.6+.

User guide

The TartifletteApp class is an ASGI3-compliant application. There are two ways to use it:

• Serve it as a standalone ASGI app.
• Mount it as an endpoint of another ASGI app (e.g. a Starlette application).

Standalone ASGI app

The Quickstart example shows how to build a TartifletteApp and serve it as a standalone ASGI app.

The app is served using Uvicorn, but any other ASGI web server will do, for example:

• uvicorn
• hypercorn
• daphne

Submounting on another ASGI app

How it works

Most ASGI web frameworks provide a way to mount another ASGI app at a given URL prefix. You can use this to serve a TartifletteApp at an endpoint such as /graphql on the root ASGI application.

This is useful to have a GraphQL endpoint and other (non-GraphQL) endpoints within a single application. For example, to have a REST endpoint at /api/users and a GraphQL endpoint at /graphql.

Important: this should work with any web framework that supports ASGI submounting — it doesn't have to be Starlette. See also: What is the role of Starlette?

Starlette example

from starlette.applications import Starlette
from starlette.responses import PlainTextResponse
from tartiflette import Resolver
from tartiflette_starlette import TartifletteApp

app = Starlette()

@app.route("/")
async def home(request):
  return PlainTextResponse("Hello, world!")

@Resolver("Query.hello")
async def hello(parent, args, context, info):
    name = args["name"]
    return f"Hello, {name}!"

sdl = """
  type Query {
    hello(name: String): String
  }
"""

graphql = TartifletteApp(sdl=sdl)
app.mount("/graphql", graphql)

Save the file as app.py, and serve it with uvicorn:

uvicorn app:app

Make a request:

curl -H "Content-Type: application/graphql"  -d '{ hello(name: "Chuck") }' http://localhost:8000/graphql/

Response:

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

Making requests

tartiflette-starlette complies with the GraphQL spec, which allows you to pass the query in several ways:

• URL query string (methods: GET, POST):

curl 'http://localhost:8000?query=\{hello(name:"Chuck")\}'

• JSON-encoded body (methods: POST):

curl \
  -H "Content-Type: application/json" \
  -d '{"query": "{ hello(name: \"Chuck\") }"}' \
  http://localhost:8000

• Raw body with the application/graphql content type (methods: POST):

curl \
  -H "Content-Type: application/graphql" \
  -d '{ hello(name: "Chuck") }' \
  http://localhost:8000

Note: you may have your GraphQL API served at a different endpoint.

Accessing request information

You can access the Starlette Request object from resolvers using context["req"]:

@Resolver("Query.whoami")
async def resolve_whoami(parent, args, context, info) -> str:
    request = context["req"]
    return getattr(request.state, "user", "a mystery")

See also Requests in the Starlette documentation.

API Reference

tartiflette_starlette.TartifletteApp

Parameters

Note: all parameters are keyword-only.

• engine (Engine): a Tartiflette engine. Required if sdl is not given.
• sdl (str): a GraphQL schema defined using the GraphQL Schema Definition Language. Required if engine is not given.
• graphiql (bool): whether to show the GraphiQL client when accessing the endpoint in a web browser. Defaults to True.
• path (str): the path which clients should make GraphQL queries to. Defaults to "".
• schema_name (str): name of the GraphQL schema from the Schema Registry which should be used — mostly for advanced usage. Defaults to "default".

Methods

• __call__(scope, receive, send): implementation of the ASGI3 callable interface.

Error responses

FAQ

Does this package ship with Tartiflette?

Yes. Everything is included, which allows you to start building your GraphQL API right away. See also Installation.

Do I need to learn GraphQL/Tartiflette to use this package?

Yes: once you've got the TartifletteApp ASGI app up and running, you're in Tartiflette territory.

Here are some resources to get you started:

• Tartiflette tutorial
• Introduction to GraphQL
• Tartiflette API reference

What is the role of Starlette?

tartiflette-starlette uses Starlette as a lightweight ASGI toolkit: internally, it uses Starlette's request and response classes.

Luckily, this does not require your applications to use Starlette at all.

For example, if you're submounting your GraphQL app on an app built with an async web framework, the framework doesn't need to use Starlette — it just needs to speak ASGI.

What is ASGI?

ASGI provides a standard interface between async-capable Python web servers, frameworks, and applications.

See also the ASGI documentation.

Contributing

Want to contribute? Awesome! Be sure to read our Contributing guidelines.

Changelog

Changes to this project are recorded in the changelog.

License

MIT