6.0 KiB

Raw Blame History

Starlette

The little ASGI library that shines.

Starlette is a small library for working with ASGI.

It gives you Request and Response classes, a test client, and a decorator for writing super-minimal applications.

Requirements:

Python 3.6+

Installation:

pip3 install starlette

Example:

from starlette import Response


class App:
    def __init__(self, scope):
        self.scope = scope

    async def __call__(self, receive, send):
        response = Response('Hello, world!', media_type='text/plain')
        await response(receive, send)

You can run the application with any ASGI server, including uvicorn, daphne, or hypercorn,

— ⭐️ —

Responses

Starlette includes a few response classes that handle sending back the appropriate ASGI messages on the send channel.

Response

Signature: Response(content=b'', status_code=200, headers=None, media_type=None)

content - A string or bytestring.
status_code - An integer HTTP status code.
headers - A dictionary of strings or list of pairs of strings.
media_type - A string giving the content type.

Starlette will automatically include a content-length header. It will also set the content-type header, including a charset for text types.

Once you've instantiated a response, you can send it by calling it as an ASGI application instance.

class App:
    def __init__(self, scope):
        self.scope = scope

    async def __call__(self, receive, send):
        response = Response('Hello, world!', media_type='text/plain')
        await response(receive, send)

HTMLResponse

Takes some text or bytes and returns an HTML response.

from starlette import HTMLResponse


class App:
    def __init__(self, scope):
        self.scope = scope

    async def __call__(self, receive, send):
        response = HTMLResponse('<html><body><h1>Hello, world!</h1></body></html')
        await response(receive, send)

JSONResponse

Takes some data and returns an application/json encoded response.

from starlette import JSONResponse


class App:
    def __init__(self, scope):
        self.scope = scope

    async def __call__(self, receive, send):
        response = JSONResponse({'hello': 'world'})
        await response(receive, send)

StreamingResponse

Takes an async generator and streams the response body.

from starlette import Request, StreamingResponse
import asyncio


async def slow_numbers(minimum, maximum):
    yield('<html><body><ul>')
    for number in range(minimum, maximum + 1):
        yield '<li>%d</li>' % number
        await asyncio.sleep(0.5)
    yield('</ul></body></html>')


class App:
    def __init__(self, scope):
        self.scope = scope

    async def __call__(self, receive, send):
        generator = slow_numbers(1, 10)
        response = StreamingResponse(generator, media_type='text/html')
        await response(receive, send)

Requests

Starlette includes a Request class that gives you a nicer interface onto the incoming request, rather than accessing the ASGI scope and receive channel directly.

Request

Signature: Request(scope, receive)

class App:
    def __init__(self, scope):
        self.scope = scope

    async def __call__(self, receive, send):
        request = Request(self.scope, receive)
        content = '%s %s' % (request.method, request.url.path)
        response = Response(content, media_type='text/plain')
        await response(receive, send)

Method

The request method is accessed as request.method.

URL

The request URL is accessed as request.url.

The property is actually a subclass of str, and also exposes all the components that can be parsed out of the URL.

For example: request.url.path, request.url.port, request.url.scheme.

Headers

Headers are exposed as an immutable, case-insensitive, multi-dict.

For example: request.headers['content-type']

Query Parameters

Headers are exposed as an immutable multi-dict.

For example: request.query_params['abc']

Body

There are two interfaces for returning the body of the request:

The request body as bytes: await request.body()

The request body, parsed as JSON: await request.json()

Test Client

The test client allows you to make requests against your ASGI application, using the requests library.

from starlette import HTMLResponse, TestClient


class App:
    def __init__(self, scope):
        self.scope = scope

    async def __call__(self, receive, send):
        response = HTMLResponse('<html><body>Hello, world!</body></html>')
        await response(receive, send)


def test_app():
    client = TestClient(App)
    response = client.get('/')
    assert response.status_code == 200

Decorators

The asgi_application decorator turns an async function into an ASGI application.

The function must take a single request argument, and return a response.

from starlette import asgi_application, HTMLResponse


@asgi_application
async def app(request):
    return HTMLResponse('<html><body>Hello, world!</body></html>')

API Star is BSD licensed code.
Designed & built in Brighton, England.
— ⭐️ —

6.0 KiB Raw Blame History Unescape Escape