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.

9 files changed, 212 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.
diff --git a/docs/index.txt b/docs/index.txt
index 31a641e168..6d6f5528c4 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -226,6 +226,7 @@ testing of Django applications:
 * **Deployment:**
   :doc:`Overview <howto/deployment/index>` |
   :doc:`WSGI servers <howto/deployment/wsgi/index>` |
+  :doc:`ASGI servers <howto/deployment/asgi/index>` |
   :doc:`Deploying static files <howto/static-files/deployment>` |
   :doc:`Tracking code errors by email <howto/error-reporting>`
 
diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt
index febfa3546e..44d536fb33 100644
--- a/docs/internals/contributing/writing-code/unit-tests.txt
+++ b/docs/internals/contributing/writing-code/unit-tests.txt
@@ -262,6 +262,7 @@ If you want to run the full suite of tests, you'll need to install a number of
 dependencies:
 
 *  argon2-cffi_ 16.1.0+
+*  asgiref_ (required)
 *  bcrypt_
 *  docutils_
 *  geoip2_
@@ -306,6 +307,7 @@ To run some of the autoreload tests, you'll need to install the Watchman_
 service.
 
 .. _argon2-cffi: https://pypi.org/project/argon2_cffi/
+.. _asgiref: https://pypi.org/project/asgiref/
 .. _bcrypt: https://pypi.org/project/bcrypt/
 .. _docutils: https://pypi.org/project/docutils/
 .. _geoip2: https://pypi.org/project/geoip2/
diff --git a/docs/ref/exceptions.txt b/docs/ref/exceptions.txt
index ee3f5260c9..208b4d6672 100644
--- a/docs/ref/exceptions.txt
+++ b/docs/ref/exceptions.txt
@@ -162,6 +162,40 @@ or model are classified as ``NON_FIELD_ERRORS``. This constant is used
 as a key in dictionaries that otherwise map fields to their respective
 list of errors.
 
+``RequestAborted``
+------------------
+
+.. exception:: RequestAborted
+
+    .. versionadded:: 3.0
+
+    The :exc:`RequestAborted` exception is raised when a HTTP body being read
+    in by the handler is cut off midstream and the client connection closes,
+    or when the client does not send data and hits a timeout where the server
+    closes the connection.
+
+    It is internal to the HTTP handler modules and you are unlikely to see
+    it elsewhere. If you are modifying HTTP handling code, you should raise
+    this when you encounter an aborted request to make sure the socket is
+    closed cleanly.
+
+``SynchronousOnlyOperation``
+----------------------------
+
+.. exception:: SynchronousOnlyOperation
+
+    .. versionadded:: 3.0
+
+    The :exc:`SynchronousOnlyOperation` exception is raised when code that
+    is only allowed in synchronous Python code is called from an asynchronous
+    context (a thread with a running asynchronous event loop). These parts of
+    Django are generally heavily reliant on thread-safety to function and don't
+    work correctly under coroutines sharing the same thread.
+
+    If you are trying to call code that is synchronous-only from an
+    asynchronous thread, then create a synchronous thread and call it in that.
+    You can accomplish this is with ``asgiref.sync.sync_to_async``.
+
 .. currentmodule:: django.urls
 
 URL Resolver exceptions
diff --git a/docs/releases/3.0.txt b/docs/releases/3.0.txt
index ba7e9f18da..51d7f7c8bf 100644
--- a/docs/releases/3.0.txt
+++ b/docs/releases/3.0.txt
@@ -44,6 +44,28 @@ MariaDB support
 Django now officially supports `MariaDB <https://mariadb.org/>`_ 10.1 and
 higher. See :ref:`MariaDB notes <mariadb-notes>` for more details.
 
+ASGI support
+------------
+
+Django 3.0 begins our journey to making Django fully async-capable by providing
+support for running as an `ASGI <https://asgi.readthedocs.io/>`_ application.
+
+This is in addition to our existing WSGI support. Django intends to support
+both for the foreseeable future. Async features will only be available to
+applications that run under ASGI, however.
+
+There is no need to switch your applications over unless you want to start
+experimenting with asynchronous code, but we have
+:doc:`documentation on deploying with ASGI </howto/deployment/asgi/index>` if
+you want to learn more.
+
+Note that as a side-effect of this change, Django is now aware of asynchronous
+event loops and will block you calling code marked as "async unsafe" - such as
+ORM operations - from an asynchronous context. If you were using Django from
+async code before, this may trigger if you were doing it incorrectly. If you
+see a ``SynchronousOnlyOperation`` error, then closely examine your code and
+move any database operations to be in a synchronous child thread.
+
 Minor features
 --------------
 
diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist
index e4460b384d..445a64adfc 100644
--- a/docs/spelling_wordlist
+++ b/docs/spelling_wordlist
@@ -24,6 +24,7 @@ arctangent
 arg
 args
 assistive
+async
 atomicity
 attr
 auth
@@ -115,6 +116,7 @@ conf
 config
 contenttypes
 contrib
+coroutines
 covariance
 criticals
 cron
@@ -133,6 +135,7 @@ customizations
 Dahl
 Daly
 Danga
+Daphne
 Darussalam
 databrowse
 datafile
@@ -750,6 +753,7 @@ utc
 UTF
 util
 utils
+Uvicorn
 uwsgi
 uWSGI
 validator