feat: ASGI support

.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,22 +9,27 @@ cache:
 
 matrix:
     include:
-        - python: pypy3.5-6.0
+        - python: pypy3.6-7.1.1
           env: TOXENV=pypy3
         - python: 3.8
           env: TOXENV=pep8
         - python: 3.8
           env: TOXENV=pep8-examples
-        - python: 3.5
+        - python: 3.8
+          env: TOXENV=mypy
+          # 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
+        - python: 3.6
+          env: TOXENV=py36_cython
         - python: 3.7
           env: TOXENV=py37
         - python: 3.8
           env: TOXENV=py38
-        - python: 3.8
-          env: TOXENV=mypy
         - python: 3.8
           env: TOXENV=py38_cython
         - python: 3.8
@@ -47,7 +52,7 @@ matrix:
         - python: 3.8
           env: TOXENV=check_vendored
 
-script: tox
+script: tox -- -v
 
 notifications:
   webhooks:

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,18 @@
 from falcon.hooks import before, after  # NOQA
 from falcon.request import Request, RequestOptions, Forwarded  # NOQA
 from falcon.response import Response, ResponseOptions  # NOQA
+
+
+ASGI_SUPPORTED = _sys.version_info.minor > 5
+"""Set to ``True`` when ASGI is supported for the current Python version."""
+
+
+# NOTE(kgriffs): Special singleton to be used internally whenever using
+#   None would be ambiguous.
+_UNSET = object()
+
+
+# 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())