Merge branch 'master' into reorganize-towncrier

.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:
@@ -57,6 +62,9 @@ notifications:
     on_failure: always
 
 before_install:
+  # NOTE(vytas): wheels sometimes fail to build on s390x due to cache being
+  #   owned by another user.
+  - sudo chown -R travis:travis $HOME/.cache/pip
   # NOTE(vytas): libunwind-dev does not exist for s390x in Ubuntu 16.04
   - if [[ `uname -m` == *86* ]]; then sudo apt-get update && sudo apt-get install -y libunwind-dev; fi
   - pip install codecov

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
@@ -690,8 +691,8 @@ GitHub nick and an appropriate prefix:
 The core Falcon project maintainers are:
 
 - Kurt Griffiths, Project Lead (**kgriffs** on GH, Gitter, and Twitter)
-- John Vrbanac (**jmvrbanac** on GH and Gitter, and **jvrbanac** on Twitter)
-- Vytautas Liuolia (**vytas7** on GH and Gitter)
+- John Vrbanac (**jmvrbanac** on GH, Gitter, and Twitter)
+- Vytautas Liuolia (**vytas7** on GH and Gitter, and **vliuolia** on Twitter)
 - Nick Zaccardi (**nZac** on GH and Gitter)
 
 Please don't hesitate to reach out if you have any questions, or just need a

docs/_newsfragments/1630-set-response.feature.rst

@@ -0,0 +1,2 @@
+The :meth:`~.Response.set_headers` method now accepts an instance of any dict-like
+object that implements an ``items()`` method.

docs/_newsfragments/default-404-responder-specialized-error.feature.rst

@@ -0,0 +1,4 @@
+When no route matches a request, the framework will now raise a
+specialized subclass of :class:`~.falcon.HTTPNotFound`
+(:class:`~.falcon.HTTPRouteNotFound`) so that
+a custom error handler can distinguish that specific case if desired.

docs/_newsfragments/simulate-request-content-type.feature.rst

@@ -0,0 +1,3 @@
+:meth:`falcon.testing.simulate_request` now accepts a
+`content_type` keyword argument. This provides a more convenient way to set
+this common header vs. the `headers` argument.

docs/_static/custom.css

@@ -164,6 +164,13 @@ pre {
     font-size: smaller;
 }
 
+
+/* NOTE(kgriffs): Make sure that characters in plain text blocks line up correctly. */
+.highlight-none .highlight pre {
+    line-height: 1em;
+    font-family: monospace;
+}
+
 /* Fix drifting to the left in some parameters lists. */
 .field-body li .highlight pre {
     float: right;
@@ -254,3 +261,9 @@ dl.field-list.simple dd ul li p:not(:first-child) {
 dl.attribute > dd > p {
     margin: 0;
 }
+
+/* NOTE(kgriffs): Fix spacing issue with embedded Note blocks, and make
+     things generally more readable by spacing the paragraphs. */
+.field-list p {
+    margin-bottom: 1em;
+}

docs/api/app.rst

@@ -3,18 +3,30 @@
 The App Class
 =============
 
-Falcon's App class is a WSGI "application" that you can host with any
-standard-compliant WSGI server.
+Falcon supports both the WSGI (:class:`falcon.App`) and
+ASGI (:class:`falcon.asgi.App`) protocols. This is done
+by instantiating the respective ``App`` class to create a
+callable WSGI or ASGI "application".
+
+Because Falcon's ``App`` classes are built on
+`WSGI <https://www.python.org/dev/peps/pep-3333/>`_ and
+`ASGI <https://asgi.readthedocs.io/en/latest/>`_,
+you can host them with any standard-compliant server.
 
 .. code:: python
 
     import falcon
+    import falcon.asgi
 
-    app = falcon.App()
+    wsgi_app = falcon.App()
+    asgi_app = falcon.asgi.App()
 
 .. autoclass:: falcon.App
     :members:
 
+.. autoclass:: falcon.asgi.App
+    :members:
+
 .. autoclass:: falcon.RequestOptions
     :members:
 

docs/api/cookies.rst

@@ -99,8 +99,9 @@ the request.
 When running your application in a development environment, you can
 disable this default behavior by setting
 :py:attr:`~.ResponseOptions.secure_cookies_by_default` to ``False``
-via :any:`App.resp_options`. This lets you test your app locally
-without having to set up TLS. You can make this option configurable to
+via :py:attr:`falcon.App.resp_options` or
+:py:attr:`falcon.asgi.App.resp_options`. This lets you test your app
+locally without having to set up TLS. You can make this option configurable to
 easily switch between development and production environments.
 
 See also: `RFC 6265, Section 4.1.2.5`_

docs/api/errors.rst

@@ -63,7 +63,7 @@ All classes are available directly in the ``falcon`` package namespace::
 Note also that any exception (not just instances of
 :class:`~.HTTPError`) can be caught, logged, and otherwise handled
 at the global level by registering one or more custom error handlers.
-See also :meth:`~.App.add_error_handler` to learn more about this
+See also :meth:`~.falcon.App.add_error_handler` to learn more about this
 feature.
 
 .. note::
@@ -87,20 +87,107 @@ Mixins
 Predefined Errors
 -----------------
 
-.. automodule:: falcon
-    :noindex:
-    :members: HTTPBadRequest,
-        HTTPInvalidHeader, HTTPMissingHeader,
-        HTTPInvalidParam, HTTPMissingParam,
-        HTTPUnauthorized, HTTPForbidden, HTTPNotFound, HTTPMethodNotAllowed,
-        HTTPNotAcceptable, HTTPConflict, HTTPGone, HTTPLengthRequired,
-        HTTPPreconditionFailed, HTTPPayloadTooLarge, HTTPUriTooLong,
-        HTTPUnsupportedMediaType, HTTPRangeNotSatisfiable,
-        HTTPUnprocessableEntity, HTTPLocked, HTTPFailedDependency,
-        HTTPPreconditionRequired, HTTPTooManyRequests,
-        HTTPRequestHeaderFieldsTooLarge,
-        HTTPUnavailableForLegalReasons,
-        HTTPInternalServerError, HTTPNotImplemented, HTTPBadGateway,
-        HTTPServiceUnavailable, HTTPGatewayTimeout, HTTPVersionNotSupported,
-        HTTPInsufficientStorage, HTTPLoopDetected,
-        HTTPNetworkAuthenticationRequired
+.. autoclass:: falcon.HTTPBadRequest
+    :members:
+
+.. autoclass:: falcon.HTTPInvalidHeader
+    :members:
+
+.. autoclass:: falcon.HTTPMissingHeader
+    :members:
+
+.. autoclass:: falcon.HTTPInvalidParam
+    :members:
+
+.. autoclass:: falcon.HTTPMissingParam
+    :members:
+
+.. autoclass:: falcon.HTTPUnauthorized
+    :members:
+
+.. autoclass:: falcon.HTTPForbidden
+    :members:
+
+.. autoclass:: falcon.HTTPNotFound
+    :members:
+
+.. autoclass:: falcon.HTTPRouteNotFound
+    :members:
+
+.. autoclass:: falcon.HTTPMethodNotAllowed
+    :members:
+
+.. autoclass:: falcon.HTTPNotAcceptable
+    :members:
+
+.. autoclass:: falcon.HTTPConflict
+    :members:
+
+.. autoclass:: falcon.HTTPGone
+    :members:
+
+.. autoclass:: falcon.HTTPLengthRequired
+    :members:
+
+.. autoclass:: falcon.HTTPPreconditionFailed
+    :members:
+
+.. autoclass:: falcon.HTTPPayloadTooLarge
+    :members:
+
+.. autoclass:: falcon.HTTPUriTooLong
+    :members:
+
+.. autoclass:: falcon.HTTPUnsupportedMediaType
+    :members:
+
+.. autoclass:: falcon.HTTPRangeNotSatisfiable
+    :members:
+
+.. autoclass:: falcon.HTTPUnprocessableEntity
+    :members:
+
+.. autoclass:: falcon.HTTPLocked
+    :members:
+
+.. autoclass:: falcon.HTTPFailedDependency
+    :members:
+
+.. autoclass:: falcon.HTTPPreconditionRequired
+    :members:
+
+.. autoclass:: falcon.HTTPTooManyRequests
+    :members:
+
+.. autoclass:: falcon.HTTPRequestHeaderFieldsTooLarge
+    :members:
+
+.. autoclass:: falcon.HTTPUnavailableForLegalReasons
+    :members:
+
+.. autoclass:: falcon.HTTPInternalServerError
+    :members:
+
+.. autoclass:: falcon.HTTPNotImplemented
+    :members:
+
+.. autoclass:: falcon.HTTPBadGateway
+    :members:
+
+.. autoclass:: falcon.HTTPServiceUnavailable
+    :members:
+
+.. autoclass:: falcon.HTTPGatewayTimeout
+    :members:
+
+.. autoclass:: falcon.HTTPVersionNotSupported
+    :members:
+
+.. autoclass:: falcon.HTTPInsufficientStorage
+    :members:
+
+.. autoclass:: falcon.HTTPLoopDetected
+    :members:
+
+.. autoclass:: falcon.HTTPNetworkAuthenticationRequired
+    :members:

docs/api/index.rst

@@ -1,5 +1,5 @@
-Classes and Functions
-=====================
+Framework Reference
+===================
 
 .. toctree::
    :maxdepth: 2

docs/api/middleware.rst

@@ -158,7 +158,7 @@ which case the framework will use the latter exception to update the
 
     By default, the framework installs two handlers, one for
     :class:`~.HTTPError` and one for :class:`~.HTTPStatus`. These can
-    be overridden via :meth:`~.App.add_error_handler`.
+    be overridden via :meth:`~.falcon.App.add_error_handler`.
 
 Regardless, the framework will continue unwinding the middleware
 stack. For example, if *mob2.process_request* were to raise an