feat: ASGI support

This patch adds the much-anticipated async support to Falcon by way of a
new ASGI interface, additional testing helpers, and updated internals.

Note that only the HTTP ASGI interface is implemented. WebSocket support
is planned to follow.

Docs will be fully fleshed-out in a follow-up PR.

Changelog snippets will also be added in a follow-up PR.

In order to reconcile differences between the WSGI and ASGI interfaces,
several breaking changes were made in this patch, as follows:

BREAKING CHANGE: create_environ no longer sets a default user agent header

BREAKING CHANGE: Renamed `protocol` kwarg for create_environ() to
	`http_version` and also the renamed kwarg only takes the version string
	(no longer prefixed with "HTTP/")

BREAKING CHANGE: Renamed `app` kwarg for create_environ() to `root_path`.
	and deprecated, may be removed in a future release.

BREAKING CHANGE: get_http_status() is deprecated, no longer accepts floats

BREAKING CHANGE: BoundedStream.writeable() changed to writable() per the
	standard file-like I/O interface (the old name was a misspelling).

BREAKING CHANGE: api_helpers.prepare_middleware() no longer accepts a single
	object; the value that is passed must be an iterable.

BREAKING CHANGE: Removed outer "finally" block from API and APP; add an
	exception handler for the base Exception type if you need to deal with
	unhandled exceptions.

BREAKING CHANGE: falcon.request.access_route will now include the value of
  the remote_addr property as the last element in the route, if not already present
  in one of the headers that are checked.

BREAKING CHANGE: When the 'REMOTE_ADDR' field is not present in the WSGI
	environ, Falcon will assume '127.0.0.1' for the value, rather than
	simply returning `None` for Request.remote_addr.

.gitignore

@@ -11,6 +11,7 @@
 *.py[cod]
 .eggs
 .installed.cfg
+.mypy_cache
 build
 develop-eggs
 dist
@@ -20,6 +21,7 @@ lib64
 parts
 sdist
 var
+pip-wheel-metadata
 
 # Installer logs
 pip-log.txt

.travis.yml

@@ -9,13 +9,16 @@ cache:
 
 matrix:
     include:
-        - python: pypy3.5-6.0
+        - python: pypy3.6-7.2.0
           env: TOXENV=pypy3
         - python: 3.8
           env: TOXENV=pep8
         - python: 3.8
           env: TOXENV=pep8-examples
-        - python: 3.5
+          # NOTE(kgriffs):  3.5.2 is the default Python 3 version on Ubuntu 16.04
+          #   so we pin to that for testing to make sure we are working around
+          #   and quirks that were fixed in later micro versions.
+        - python: 3.5.2
           env: TOXENV=py35
         - python: 3.6
           env: TOXENV=py36

CONTRIBUTING.md

@@ -27,20 +27,26 @@ Please note that all contributors and maintainers of this project are subject to
 
 Before submitting a pull request, please ensure you have added or updated tests as appropriate, and that all existing tests still pass with your changes. Please also ensure that your coding style follows PEP 8.
 
-You can check all this by running the following from within the Falcon project directory (requires Python 3.8 to be installed on your system):
+You can check all this by running the following from within the Falcon project directory (requires Python 3.8 and 3.5 to be installed on your system):
 
 ```bash
 $ tools/mintest.sh
-
 ```
 
-You may also use Python 3.5, 3.6 or 3.7 if you don't have 3.8 installed on your system. Substitute "py35", "py36" or "py37" as appropriate. For example:
+You may also use Python 3.6 or 3.7 if you don't have 3.8 installed on your system. Substitute "py36" or "py37" as appropriate. For example:
 
 
 ```bash
 $ pip install -U tox coverage
 $ rm -f .coverage.*
-$ tox -e pep8 && tox -e py37 && tools/testing/combine_coverage.sh
+$ tox -e pep8 && tox -e py35,py37 && tools/testing/combine_coverage.sh
+```
+
+If you are using pyenv, you will need to make sure both 3.8 and 3.5 are available in the current shell, e.g.:
+
+```bash
+$ pyenv shell 3.8.0 3.5.8
+```
 
 #### Reviews
 

README.rst

@@ -231,7 +231,8 @@ Installing it is as simple as:
 Installing the Falcon wheel is a great way to get up and running
 quickly in a development environment, but for an extra speed boost when
 deploying your application in production, Falcon can compile itself with
-Cython.
+Cython. Note, however, that Cython is currently incompatible with
+the falcon.asgi module.
 
 The following commands tell pip to install Cython, and then to invoke
 Falcon's ``setup.py``, which will in turn detect the presence of Cython

docs/api/testing.rst

@@ -11,5 +11,5 @@ Reference
         simulate_request, simulate_get, simulate_head, simulate_post,
         simulate_put, simulate_options, simulate_patch, simulate_delete,
         TestClient, TestCase, SimpleTestResource, StartResponseMock,
-        capture_responder_args, rand_string, create_environ, redirected,
-        closed_wsgi_iterable
+        capture_responder_args, rand_string, create_environ, create_req,
+        create_asgi_req, redirected, closed_wsgi_iterable

docs/user/install.rst

@@ -35,7 +35,8 @@ Installing it is as simple as:
 Installing the Falcon wheel is a great way to get up and running
 quickly in a development environment, but for an extra speed boost when
 deploying your application in production, Falcon can compile itself with
-Cython.
+Cython. Note, however, that Cython is currently incompatible with
+the falcon.asgi module.
 
 The following commands tell pip to install Cython, and then to invoke
 Falcon's ``setup.py``, which will in turn detect the presence of Cython

falcon/__init__.py

@@ -12,9 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Primary package for Falcon, the minimalist WSGI library.
+"""Primary package for Falcon, the minimalist web API framework.
 
-Falcon is a minimalist WSGI library for building speedy web APIs and app
+Falcon is a minimalist web API framework for building speedy web APIs and app
 backends. The `falcon` package can be used to directly access most of
 the framework's classes, functions, and variables::
 
@@ -24,6 +24,9 @@
 
 """
 
+import logging as _logging
+import sys as _sys
+
 # Hoist classes and functions into the falcon namespace
 from falcon.version import __version__  # NOQA
 from falcon.constants import *  # NOQA
@@ -44,3 +47,12 @@
 from falcon.hooks import before, after  # NOQA
 from falcon.request import Request, RequestOptions, Forwarded  # NOQA
 from falcon.response import Response, ResponseOptions  # NOQA
+
+
+PY35 = _sys.version_info.minor == 5
+
+
+# NOTE(kgriffs): Only to be used internally on the rare occasion that we
+#   need to log something that we can't communicate any other way.
+_logger = _logging.getLogger('falcon')
+_logger.addHandler(_logging.NullHandler())