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

@@ -20,6 +20,7 @@ lib64
 parts
 sdist
 var
+pip-wheel-metadata
 
 # Installer logs
 pip-log.txt

.travis.yml

@@ -9,7 +9,7 @@ cache:
 
 matrix:
     include:
-        - python: pypy3.5-6.0
+        - python: pypy3.6-7.1.1
           env: TOXENV=pypy3
         - python: 3.7
           env: TOXENV=pep8

CONTRIBUTING.md

@@ -27,20 +27,18 @@ 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.7 to be installed on your system):
+You can check all this by running the following from within the Falcon project directory (requires Python 3.7 and 3.5 to be installed on your system):
 
 ```bash
 $ tools/mintest.sh
 
 ```
 
-You may also use Python 3.5 or 3.6 if you don't have 3.7 installed on your system. Substitute "py35" or "py36" as appropriate. For example:
-
+If you are useing pyenv, you will need to make sure both 3.7 and 3.5 are available in the current shell, e.g.:
 
 ```bash
-$ pip install -U tox coverage
-$ rm -f .coverage.*
-$ tox -e pep8 && tox -e py35 && tools/testing/combine_coverage.sh
+$ pyenv shell 3.7.3 3.5.7
+```
 
 #### Reviews
 

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

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,8 @@
 
 """
 
+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 +46,5 @@
 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