Fixed #30451 -- Added ASGI handler and coroutine-safety.

This adds an ASGI handler, asgi.py file for the default project layout,
a few async utilities and adds async-safety to many parts of Django.

4 files changed, 149 insertions, 5 deletions

diff --git a/docs/howto/deployment/asgi/daphne.txt b/docs/howto/deployment/asgi/daphne.txt
new file mode 100644
index 0000000000..94d1ac897b
--- /dev/null
+++ b/docs/howto/deployment/asgi/daphne.txt
@@ -0,0 +1,33 @@
+=============================
+How to use Django with Daphne
+=============================
+
+.. highlight:: bash
+
+Daphne_ is a pure-Python ASGI server for UNIX, maintained by members of the
+Django project. It acts as the reference server for ASGI.
+
+.. _Daphne: https://pypi.org/project/daphne/
+
+Installing Daphne
+===================
+
+You can install Daphne with ``pip``::
+
+    python -m pip install daphne
+
+Running Django in Daphne
+========================
+
+When Daphne is installed, a ``daphne`` command is available which starts the
+Daphne server process. At its simplest, Daphne needs to be called with the
+location of a module containing an ASGI application object, followed by what
+the application is called (separated by a colon).
+
+For a typical Django project, invoking Daphne would look like::
+
+    daphne myproject.asgi:application
+
+This will start one process listening on ``127.0.0.1:8000``. It requires that
+your project be on the Python path; to ensure that run this command from the
+same directory as your ``manage.py`` file.
diff --git a/docs/howto/deployment/asgi/index.txt b/docs/howto/deployment/asgi/index.txt
new file mode 100644
index 0000000000..f09d79a67e
--- /dev/null
+++ b/docs/howto/deployment/asgi/index.txt
@@ -0,0 +1,71 @@
+=======================
+How to deploy with ASGI
+=======================
+
+As well as WSGI, Django also supports deploying on ASGI_, the emerging Python
+standard for asynchronous web servers and applications.
+
+.. _ASGI: https://asgi.readthedocs.io/en/latest/
+
+Django's :djadmin:`startproject` management command sets up a default ASGI
+configuration for you, which you can tweak as needed for your project, and
+direct any ASGI-compliant application server to use.
+
+Django includes getting-started documentation for the following ASGI servers:
+
+.. toctree::
+   :maxdepth: 1
+
+   daphne
+   uvicorn
+
+The ``application`` object
+==========================
+
+Like WSGI, ASGI has you supply an ``application`` callable which
+the application server uses to communicate with your code. It's commonly
+provided as an object named ``application`` in a Python module accessible to
+the server.
+
+The :djadmin:`startproject` command creates a file
+:file:`<project_name>/asgi.py` that contains such an ``application`` callable.
+
+It's not used by the development server (``runserver``), but can be used by
+any ASGI server either in development or in production.
+
+ASGI servers usually take the path to the application callable as a string;
+for most Django projects, this will look like ``myproject.asgi:application``.
+
+.. warning::
+
+    While Django's default ASGI handler will run all your code in a synchronous
+    thread, if you choose to run your own async handler you must be aware of
+    async-safety.
+
+    Do not call blocking synchronous functions or libraries in any async code.
+    Django prevents you from doing this with the parts of Django that are not
+    async-safe, but the same may not be true of third-party apps or Python
+    libraries.
+
+Configuring the settings module
+===============================
+
+When the ASGI server loads your application, Django needs to import the
+settings module — that's where your entire application is defined.
+
+Django uses the :envvar:`DJANGO_SETTINGS_MODULE` environment variable to locate
+the appropriate settings module. It must contain the dotted path to the
+settings module. You can use a different value for development and production;
+it all depends on how you organize your settings.
+
+If this variable isn't set, the default :file:`asgi.py` sets it to
+``mysite.settings``, where ``mysite`` is the name of your project.
+
+Applying ASGI middleware
+========================
+
+To apply ASGI middleware, or to embed Django in another ASGI application, you
+can wrap Django's ``application`` object in the ``asgi.py`` file. For example::
+
+    from some_asgi_library import AmazingMiddleware
+    application = AmazingMiddleware(application)
diff --git a/docs/howto/deployment/asgi/uvicorn.txt b/docs/howto/deployment/asgi/uvicorn.txt
new file mode 100644
index 0000000000..70d32da113
--- /dev/null
+++ b/docs/howto/deployment/asgi/uvicorn.txt
@@ -0,0 +1,35 @@
+==============================
+How to use Django with Uvicorn
+==============================
+
+.. highlight:: bash
+
+Uvicorn_ is an ASGI server based on ``uvloop`` and ``httptools``, with an
+emphasis on speed.
+
+Installing Uvicorn
+==================
+
+You can install Uvicorn with ``pip``::
+
+    python -m pip install uvicorn
+
+Running Django in Uvicorn
+=========================
+
+When Uvicorn is installed, a ``uvicorn`` command is available which runs ASGI
+applications. Uvicorn needs to be called with the location of a module
+containing a ASGI application object, followed by what the application is
+called (separated by a colon).
+
+For a typical Django project, invoking Uvicorn would look like::
+
+    uvicorn myproject.asgi:application
+
+This will start one process listening on ``127.0.0.1:8000``. It requires that
+your project be on the Python path; to ensure that run this command from the
+same directory as your ``manage.py`` file.
+
+For more advanced usage, please read the `Uvicorn documentation <Uvicorn_>`_.
+
+.. _Uvicorn: https://www.uvicorn.org/
diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt
index 8ffda2cf63..1b2f497922 100644
--- a/docs/howto/deployment/index.txt
+++ b/docs/howto/deployment/index.txt
@@ -2,16 +2,21 @@
 Deploying Django
 ================
 
-Django's chock-full of shortcuts to make Web developer's lives easier, but all
+Django is full of shortcuts to make Web developers' lives easier, but all
 those tools are of no use if you can't easily deploy your sites. Since Django's
 inception, ease of deployment has been a major goal.
 
+This section contains guides to the two main ways to deploy Django. WSGI is the
+main Python standard for communicating between Web servers and applications,
+but it only supports synchronous code.
+
+ASGI is the new, asynchronous-friendly standard that will allow your Django
+site to use asynchronous Python features, and asynchronous Django features as
+they are developed.
+
 .. toctree::
    :maxdepth: 1
 
    wsgi/index
+   asgi/index
    checklist
-
-If you're new to deploying Django and/or Python, we'd recommend you try
-:doc:`mod_wsgi </howto/deployment/wsgi/modwsgi>` first. In most cases it'll be
-the easiest, fastest, and most stable deployment choice.