2018-10-05 11:04:11 +00:00
2018-09-05 12:45:39 +00:00
Starlette includes an application class `Starlette` that nicely ties together all of
2018-08-28 14:11:53 +00:00
its other functionality.
```python
2018-09-05 10:39:38 +00:00
from starlette.applications import Starlette
2018-09-05 09:29:04 +00:00
from starlette.responses import PlainTextResponse
2018-08-28 14:11:53 +00:00
from starlette.staticfiles import StaticFiles
2018-09-05 09:29:04 +00:00
app = Starlette()
2018-09-04 10:52:29 +00:00
app.debug = True
2018-10-05 11:04:11 +00:00
app.mount('/static', StaticFiles(directory="static"))
2018-08-28 14:11:53 +00:00
@app .route('/')
def homepage(request):
return PlainTextResponse('Hello, world!')
2018-12-18 12:33:32 +00:00
@app .route('/user/me')
def user_me(request):
username = "John Doe"
return PlainTextResponse('Hello, %s!' % username)
2018-08-28 14:11:53 +00:00
@app .route('/user/{username}')
2018-10-29 09:22:45 +00:00
def user(request):
username = request.path_params['username']
2018-08-28 14:11:53 +00:00
return PlainTextResponse('Hello, %s!' % username)
@app .websocket_route('/ws')
2018-09-05 09:29:04 +00:00
async def websocket_endpoint(websocket):
await websocket.accept()
await websocket.send_text('Hello, websocket!')
await websocket.close()
2018-10-09 14:47:51 +00:00
@app .on_event('startup')
def startup():
print('Ready to go')
2018-08-28 14:11:53 +00:00
```
2018-09-04 10:52:29 +00:00
### Instantiating the application
2018-09-05 09:29:04 +00:00
* `Starlette(debug=False)` - Create a new Starlette application.
2018-09-04 10:52:29 +00:00
2018-08-28 14:11:53 +00:00
### Adding routes to the application
You can use any of the following to add handled routes to the application:
2018-09-04 10:52:29 +00:00
* `app.add_route(path, func, methods=["GET"])` - Add an HTTP route. The function may be either a coroutine or a regular function, with a signature like `func(request, **kwargs) -> response` .
* `app.add_websocket_route(path, func)` - Add a websocket session route. The function must be a coroutine, with a signature like `func(session, **kwargs)` .
* `@app.route(path)` - Add an HTTP route, decorator style.
* `@app.websocket_route(path)` - Add a WebSocket route, decorator style.
2018-10-21 07:37:29 +00:00
### Adding event handlers to the application
There are two ways to add event handlers:
* `@app.on_event(event_type)` - Add an event, decorator style
* `app.add_event_handler(event_type, func)` - Add an event through a function call.
2018-10-22 14:08:04 +00:00
`event_type` must be specified as either `'startup'` or `'shutdown'` .
2018-10-21 07:37:29 +00:00
2018-09-04 10:52:29 +00:00
### Submounting other applications
Submounting applications is a powerful way to include reusable ASGI applications.
* `app.mount(prefix, app)` - Include an ASGI app, mounted under the given path prefix
### Customizing exception handling
You can use either of the following to catch and handle particular types of
exceptions that occur within the application:
2018-11-08 11:59:15 +00:00
* `app.add_exception_handler(exc_class_or_status_code, handler)` - Add an error handler. The handler function may be either a coroutine or a regular function, with a signature like `func(request, exc) -> response` .
* `@app.exception_handler(exc_class_or_status_code)` - Add an error handler, decorator style.
2018-09-04 10:52:29 +00:00
* `app.debug` - Enable or disable error tracebacks in the browser.
2019-08-27 08:41:04 +00:00
### Storing state on the app instance
You can store arbitrary extra state on the application instance, using the
2019-08-27 22:11:03 +00:00
generic `app.state` attribute. This can then be accessed in middleware or endpoints via `request.app` .
2019-08-27 08:41:04 +00:00
For example:
```python
app.state.ADMIN_EMAIL = 'admin@example.org'
```