185fb1a3d1 | ||
---|---|---|
scripts | ||
starlette | ||
tests | ||
.codecov.yml | ||
.gitignore | ||
.travis.yml | ||
LICENSE.md | ||
README.md | ||
requirements.txt | ||
setup.py |
README.md
Starlette
✨ The little ASGI library that shines. ✨
Starlette is a small library for working with ASGI.
It gives you Request
and Response
classes, routing, 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=None)
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)
Requests present a mapping interface, so you can use them in the same
way as a scope
.
For instance: request['path']
will return the ASGI path.
If you don't need to access the request body you can instantiate a request
without providing an argument to receive
.
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 a few different 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()
You can also access the request body as a stream, using the async for
syntax:
class App:
def __init__(self, scope):
self.scope = scope
async def __call__(self, receive, send):
request = Request(self.scope, receive)
body = b''
async for chunk in request.stream():
body += chunk
response = Response(content, media_type='text/plain')
await response(receive, send)
If you access .stream()
then the byte chunks are provided without storing
the entire body to memory. Any subsequent calls to .body()
and .json()
will
raise an error.
Routing
Starlette includes a Router
class which is an ASGI application that
dispatches to other ASGI applications.
from starlette import Router, Path, PathPrefix
from myproject import Homepage, StaticFiles
app = Router([
Path('/', app=Homepage, methods=['GET']),
PathPrefix('/static', app=StaticFiles, methods=['GET'])
])
Paths can use URI templating style to capture path components.
Path('/users/{username}', app=User, methods=['GET'])
Path components are made available in the scope, as scope["kwargs"]
.
Because each target of the router is an ASGI instance itself, routers allow for easy composition. For example:
app = Router([
Path('/', app=Homepage, methods=['GET']),
PathPrefix('/users', app=Router([
Path('/', app=Users, methods=['GET', 'POST']),
Path('/{username}', app=User, methods=['GET']),
]))
])
The router will respond with "404 Not found" or "406 Method not allowed" responses for requests which do not match.
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>')
Starlette is BSD licensed code.
Designed & built in Brighton, England.
— ⭐️ —