From 92063504977eacf64fef09529e7b6d935a79964f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 8 Feb 2022 16:47:58 +0000 Subject: [PATCH] Docs refresh (#1365) --- README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++------ docs/index.md | 32 ++++++++++++++++------- 2 files changed, 86 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 53d9cd5fb..e0954c5a7 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@

-The lightning-fast ASGI server. +An ASGI web server, for Python.

--- @@ -15,13 +15,13 @@ **Requirements**: Python 3.7+ (For Python 3.6 support, install version 0.16.0.) -Uvicorn is a lightning-fast ASGI server implementation, using [uvloop][uvloop] and [httptools][httptools]. +Uvicorn is an ASGI web server implementation for Python. Until recently Python has lacked a minimal low-level server/application interface for -asyncio frameworks. The [ASGI specification][asgi] fills this gap, and means we're now able to -start building a common set of tooling usable across all asyncio frameworks. +async frameworks. The [ASGI specification][asgi] fills this gap, and means we're now able to +start building a common set of tooling usable across all async frameworks. -Uvicorn currently supports HTTP/1.1 and WebSockets. Support for HTTP/2 is planned. +Uvicorn supports HTTP/1.1 and WebSockets. ## Quickstart @@ -79,8 +79,63 @@ $ uvicorn example:app --- -

Uvicorn is BSD licensed code.
Designed & built in Brighton, England.
— 🦄 —

+## Why ASGI? + +Most well established Python Web frameworks started out as WSGI-based frameworks. + +WSGI applications are a single, synchronous callable that takes a request and returns a response. +This doesn’t allow for long-lived connections, like you get with long-poll HTTP or WebSocket connections, +which WSGI doesn't support well. + +Having an async concurrency model also allows for options such as lightweight background tasks, +and can be less of a limiting factor for endpoints that have long periods being blocked on network +I/O such as dealing with slow HTTP requests. + +--- + +## Alternative ASGI servers + +A strength of the ASGI protocol is that it decouples the server implementation +from the application framework. This allows for an ecosystem of interoperating +webservers and application frameworks. + +### Daphne + +The first ASGI server implementation, originally developed to power Django Channels, is [the Daphne webserver][daphne]. + +It is run widely in production, and supports HTTP/1.1, HTTP/2, and WebSockets. + +Any of the example applications given here can equally well be run using `daphne` instead. + +``` +$ pip install daphne +$ daphne app:App +``` + +### Hypercorn + +[Hypercorn][hypercorn] was initially part of the Quart web framework, before +being separated out into a standalone ASGI server. + +Hypercorn supports HTTP/1.1, HTTP/2, and WebSockets. + +It also supports [the excellent `trio` async framework][trio], as an alternative to `asyncio`. + +``` +$ pip install hypercorn +$ hypercorn app:App +``` + +### Mangum + +[Mangum][mangum] is an adapter for using ASGI applications with AWS Lambda & API Gateway. + +--- + +

Uvicorn is BSD licensed code.
Designed & crafted with care.
— 🦄 —

-[uvloop]: https://github.com/MagicStack/uvloop -[httptools]: https://github.com/MagicStack/httptools [asgi]: https://asgi.readthedocs.io/en/latest/ +[daphne]: https://github.com/django/daphne +[hypercorn]: https://gitlab.com/pgjones/hypercorn +[mangum]: https://mangum.io +[trio]: https://trio.readthedocs.io diff --git a/docs/index.md b/docs/index.md index 942c98af7..6f57b098a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,7 +3,7 @@

-The lightning-fast ASGI server. +An ASGI web server, for Python.

@@ -19,17 +19,13 @@ # Introduction -Uvicorn is a lightning-fast ASGI server implementation, using [uvloop][uvloop] and [httptools][httptools]. +Uvicorn is an ASGI web server implementation for Python. Until recently Python has lacked a minimal low-level server/application interface for -asyncio frameworks. The [ASGI specification][asgi] fills this gap, and means we're now able to -start building a common set of tooling usable across all asyncio frameworks. +async frameworks. The [ASGI specification][asgi] fills this gap, and means we're now able to +start building a common set of tooling usable across all async frameworks. -ASGI should help enable an ecosystem of Python web frameworks that are highly competitive against Node -and Go in terms of achieving high throughput in IO-bound contexts. It also provides support for HTTP/2 and -WebSockets, which cannot be handled by WSGI. - -Uvicorn currently supports HTTP/1.1 and WebSockets. Support for HTTP/2 is planned. +Uvicorn currently supports HTTP/1.1 and WebSockets. ## Quickstart @@ -422,8 +418,26 @@ async def app(scope, receive, send): --- +## Why ASGI? + +Most well established Python Web frameworks started out as WSGI-based frameworks. + +WSGI applications are a single, synchronous callable that takes a request and returns a response. +This doesn’t allow for long-lived connections, like you get with long-poll HTTP or WebSocket connections, +which WSGI doesn't support well. + +Having an async concurrency model also allows for options such as lightweight background tasks, +and can be less of a limiting factor for endpoints that have long periods being blocked on network +I/O such as dealing with slow HTTP requests. + +--- + ## Alternative ASGI servers +A strength of the ASGI protocol is that it decouples the server implementation +from the application framework. This allows for an ecosystem of interoperating +webservers and application frameworks. + ### Daphne The first ASGI server implementation, originally developed to power Django Channels, is [the Daphne webserver][daphne].