Applications

API Reference

starlette.applications.Starlette

Starlette(
    debug: bool = False,
    routes: Sequence[BaseRoute] | None = None,
    middleware: Sequence[Middleware] | None = None,
    exception_handlers: (
        Mapping[Any, ExceptionHandler] | None
    ) = None,
    on_startup: Sequence[Callable[[], Any]] | None = None,
    on_shutdown: Sequence[Callable[[], Any]] | None = None,
    lifespan: Lifespan[AppType] | None = None,
)

Creates an Starlette application.

Parameters:

• debug (bool, default: False ) –

  Boolean indicating if debug tracebacks should be returned on errors.

• routes (Sequence[BaseRoute] | None, default: None ) –

  A list of routes to serve incoming HTTP and WebSocket requests.

• middleware (Sequence[Middleware] | None, default: None ) –

  A list of middleware to run for every request. A starlette application will always automatically include two middleware classes. ServerErrorMiddleware is added as the very outermost middleware, to handle any uncaught errors occurring anywhere in the entire stack. ExceptionMiddleware is added as the very innermost middleware, to deal with handled exception cases occurring in the routing or endpoints.

• exception_handlers (Mapping[Any, ExceptionHandler] | None, default: None ) –

  A mapping of either integer status codes, or exception class types onto callables which handle the exceptions. Exception handler callables should be of the form handler(request, exc) -> response and may be either standard functions, or async functions.

• on_startup (Sequence[Callable[[], Any]] | None, default: None ) –

  A list of callables to run on application startup. Startup handler callables do not take any arguments, and may be either standard functions, or async functions.

• on_shutdown (Sequence[Callable[[], Any]] | None, default: None ) –

  A list of callables to run on application shutdown. Shutdown handler callables do not take any arguments, and may be either standard functions, or async functions.

• lifespan (Lifespan[AppType] | None, default: None ) –

  A lifespan context function, which can be used to perform startup and shutdown tasks. This is a newer style that replaces the on_startup and on_shutdown handlers. Use one or the other, not both.

Starlette includes an application class Starlette that nicely ties together all of its other functionality.

from contextlib import asynccontextmanager

from starlette.applications import Starlette
from starlette.responses import PlainTextResponse
from starlette.routing import Route, Mount, WebSocketRoute
from starlette.staticfiles import StaticFiles


def homepage(request):
    return PlainTextResponse('Hello, world!')

def user_me(request):
    username = "John Doe"
    return PlainTextResponse('Hello, %s!' % username)

def user(request):
    username = request.path_params['username']
    return PlainTextResponse('Hello, %s!' % username)

async def websocket_endpoint(websocket):
    await websocket.accept()
    await websocket.send_text('Hello, websocket!')
    await websocket.close()

@asynccontextmanager
async def lifespan(app):
    print('Startup')
    yield
    print('Shutdown')


routes = [
    Route('/', homepage),
    Route('/user/me', user_me),
    Route('/user/{username}', user),
    WebSocketRoute('/ws', websocket_endpoint),
    Mount('/static', StaticFiles(directory="static")),
]

app = Starlette(debug=True, routes=routes, lifespan=lifespan)

Storing state on the app instance

You can store arbitrary extra state on the application instance, using the generic app.state attribute.

For example:

app.state.ADMIN_EMAIL = 'admin@example.org'

Accessing the app instance

Where a request is available (i.e. endpoints and middleware), the app is available on request.app.