Merge branch 'master' into fix-777-errors

docs/api/util.rst

@@ -15,7 +15,7 @@ Miscellaneous
 
 .. automodule:: falcon
     :members: deprecated, http_now, dt_to_http, http_date_to_dt,
-        to_query_str, get_http_status, get_bound_method
+        to_query_str, get_http_status, get_bound_method, is_python_func
 
 .. autoclass:: falcon.TimezoneGMT
     :members:

falcon/app_helpers.py

@@ -81,7 +81,13 @@ def prepare_middleware(middleware, independent_middleware=False, asgi=False):
             )
 
             for m in (process_request, process_resource, process_response):
-                if m and not iscoroutinefunction(m):
+                # NOTE(kgriffs): iscoroutinefunction() always returns False
+                #   for cythonized functions.
+                #
+                #   https://github.com/cython/cython/issues/2273
+                #   https://bugs.python.org/issue38225
+                #
+                if m and not iscoroutinefunction(m) and util.is_python_func(m):
                     msg = (
                         '{} must be implemented as an awaitable coroutine. If '
                         'you would like to retain compatibility '

falcon/asgi/app.py

@@ -23,7 +23,7 @@
 from falcon.http_error import HTTPError
 from falcon.http_status import HTTPStatus
 import falcon.routing
-from falcon.util.misc import http_status_to_code
+from falcon.util.misc import http_status_to_code, is_python_func
 from falcon.util.sync import _wrap_non_coroutine_unsafe, get_loop
 from .request import Request
 from .response import Response
@@ -653,7 +653,13 @@ async def handle(req, resp, ex, params):
 
         handler = _wrap_non_coroutine_unsafe(handler)
 
-        if not iscoroutinefunction(handler):
+        # NOTE(kgriffs): iscoroutinefunction() always returns False
+        #   for cythonized functions.
+        #
+        #   https://github.com/cython/cython/issues/2273
+        #   https://bugs.python.org/issue38225
+        #
+        if not iscoroutinefunction(handler) and is_python_func(handler):
             raise CompatibilityError(
                 'The handler must be an awaitable coroutine function in order '
                 'to be used safely with an ASGI app.'
@@ -681,8 +687,8 @@ def _schedule_callbacks(self, resp):
 
         loop = get_loop()
 
-        for cb in callbacks:
-            if iscoroutinefunction(cb):
+        for cb, is_async in callbacks:
+            if is_async:
                 loop.create_task(cb())
             else:
                 loop.run_in_executor(None, cb)

falcon/asgi/request.py

@@ -73,7 +73,7 @@ class Request(falcon.request.Request):
 
     __slots__ = [
         '_asgi_headers',
-        '_asgi_server_cached'
+        '_asgi_server_cached',
         '_receive',
         '_stream',
         'scope',

falcon/asgi/response.py

@@ -15,10 +15,11 @@
 """ASGI Response class."""
 
 from asyncio.coroutines import CoroWrapper
-from inspect import iscoroutine
+from inspect import iscoroutine, iscoroutinefunction
 
 from falcon import _UNSET
 import falcon.response
+from falcon.util.misc import is_python_func
 
 __all__ = ['Response']
 
@@ -151,20 +152,16 @@ async def render_body(self):
         return data
 
     def schedule(self, callback):
-        """Schedules a callback to run soon after sending the HTTP response.
+        """Schedule an async callback to run soon after sending the HTTP response.
 
-        This method can be used to execute a background job after the
-        response has been returned to the client.
+        This method can be used to execute a background job after the response
+        has been returned to the client.
 
-        If the callback is an async coroutine function, it will be scheduled
-        to run on the event loop as soon as possible. Alternatively, if a
-        synchronous callable is passed, it will be run on the event loop's
-        default ``Executor`` (which can be overridden via
-        :py:meth:`asyncio.AbstractEventLoop.set_default_executor`).
+        The callback is assumed to be an async coroutine function. It will be
+        scheduled to run on the event loop as soon as possible.
 
         The callback will be invoked without arguments. Use
-        :py:meth`functools.partial` to pass arguments to the callback
-        as needed.
+        :py:meth:`functools.partial` to pass arguments to the callback as needed.
 
         Note:
             If an unhandled exception is raised while processing the request,
@@ -180,6 +177,58 @@ def schedule(self, callback):
             must use async libraries or delegate to an Executor pool to avoid
             blocking the processing of subsequent requests.
 
+        Args:
+            callback(object): An async coroutine function. The callback will be
+            invoked without arguments.
+        """
+
+        # NOTE(kgriffs): We also have to do the CoroWrapper check because
+        #   iscoroutine is less reliable under Python 3.6.
+        if not iscoroutinefunction(callback):
+            if iscoroutine(callback) or isinstance(callback, CoroWrapper):
+                raise TypeError(
+                    'The callback object appears to '
+                    'be a coroutine, rather than a coroutine function. Please '
+                    'pass the function itself, rather than the result obtained '
+                    'by calling the function. '
+                )
+            elif is_python_func(callback):  # pragma: nocover
+                raise TypeError('The callback must be a coroutine function.')
+
+            # NOTE(kgriffs): The implicit "else" branch is actually covered
+            #   by tests running in a Cython environment, but we can't
+            #   detect it with the coverage tool.
+
+        rc = (callback, True)
+
+        if not self._registered_callbacks:
+            self._registered_callbacks = [rc]
+        else:
+            self._registered_callbacks.append(rc)
+
+    def schedule_sync(self, callback):
+        """Schedule a synchronous callback to run soon after sending the HTTP response.
+
+        This method can be used to execute a background job after the
+        response has been returned to the client.
+
+        The callback is assumed to be a synchronous (non-coroutine) function.
+        It will be scheduled on the event loop's default ``Executor`` (which
+        can be overridden via
+        :py:meth:`asyncio.AbstractEventLoop.set_default_executor`).
+
+        The callback will be invoked without arguments. Use
+        :py:meth:`functools.partial` to pass arguments to the callback
+        as needed.
+
+        Note:
+            If an unhandled exception is raised while processing the request,
+            the callback will not be scheduled to run.
+
+        Note:
+            When an SSE emitter has been set on the response, the callback will
+            be scheduled before the first call to the emitter.
+
         Warning:
             Synchronous callables run on the event loop's default ``Executor``,
             which uses an instance of ``ThreadPoolExecutor`` unless
@@ -195,20 +244,12 @@ def schedule(self, callback):
                 callable. The callback will be called without arguments.
         """
 
-        # NOTE(kgriffs): We also have to do the CoroWrapper check because
-        #   iscoroutine is less reliable under Python 3.6.
-        if iscoroutine(callback) or isinstance(callback, CoroWrapper):
-            raise TypeError(
-                'The callback object appears to '
-                'be a coroutine, rather than a coroutine function. Please '
-                'pass the function itself, rather than the result obtained '
-                'by calling the function. '
-            )
+        rc = (callback, False)
 
         if not self._registered_callbacks:
-            self._registered_callbacks = [callback]
+            self._registered_callbacks = [rc]
         else:
-            self._registered_callbacks.append(callback)
+            self._registered_callbacks.append(rc)
 
     def set_stream(self, stream, content_length):
         """Convenience method for setting both `stream` and `content_length`.

falcon/hooks.py

@@ -27,7 +27,7 @@
     '|'.join(method.lower() for method in COMBINED_METHODS)))
 
 
-def before(action, *args, **kwargs):
+def before(action, *args, is_async=False, **kwargs):
     """Decorator to execute the given action function *before* the responder.
 
     The `params` argument that is passed to the hook
@@ -57,6 +57,22 @@ def do_something(req, resp, resource, params):
             order given, immediately following the *req*, *resp*, *resource*,
             and *params* arguments.
 
+    Keyword Args:
+        is_async (bool): Set to ``True`` for ASGI apps to provide a hint that
+            the decorated responder is a coroutine function (i.e., that it
+            is defined with ``async def``) or that it returns an awaitable
+            coroutine object.
+
+            Normally, when the function source is declared using ``async def``,
+            the resulting function object is flagged to indicate it returns a
+            coroutine when invoked, and this can be automatically detected.
+            However, it is possible to use a regular function to return an
+            awaitable coroutine object, in which case a hint is required to let
+            the framework know what to expect. Also, a hint is always required
+            when using a cythonized coroutine function, since Cython does not
+            flag them in a way that can be detected in advance, even when the
+            function is declared using ``async def``.
+
         **kwargs: Any additional keyword arguments will be passed through to
             *action*.
     """
@@ -72,7 +88,13 @@ def _before(responder_or_resource):
                     # will capture the same responder variable that is shared
                     # between iterations of the for loop, above.
                     def let(responder=responder):
-                        do_before_all = _wrap_with_before(responder, action, args, kwargs)
+                        do_before_all = _wrap_with_before(
+                            responder,
+                            action,
+                            args,
+                            kwargs,
+                            is_async
+                        )
 
                         setattr(resource, responder_name, do_before_all)
 
@@ -82,14 +104,14 @@ def let(responder=responder):
 
         else:
             responder = responder_or_resource
-            do_before_one = _wrap_with_before(responder, action, args, kwargs)
+            do_before_one = _wrap_with_before(responder, action, args, kwargs, is_async)
 
             return do_before_one
 
     return _before
 
 
-def after(action, *args, **kwargs):
+def after(action, *args, is_async=False, **kwargs):
     """Decorator to execute the given action function *after* the responder.
 
     Args:
@@ -102,6 +124,22 @@ def after(action, *args, **kwargs):
             order given, immediately following the *req*, *resp*, *resource*,
             and *params* arguments.
 
+    Keyword Args:
+        is_async (bool): Set to ``True`` for ASGI apps to provide a hint that
+            the decorated responder is a coroutine function (i.e., that it
+            is defined with ``async def``) or that it returns an awaitable
+            coroutine object.
+
+            Normally, when the function source is declared using ``async def``,
+            the resulting function object is flagged to indicate it returns a
+            coroutine when invoked, and this can be automatically detected.
+            However, it is possible to use a regular function to return an
+            awaitable coroutine object, in which case a hint is required to let
+            the framework know what to expect. Also, a hint is always required
+            when using a cythonized coroutine function, since Cython does not
+            flag them in a way that can be detected in advance, even when the
+            function is declared using ``async def``.
+
         **kwargs: Any additional keyword arguments will be passed through to
             *action*.
     """
@@ -113,7 +151,13 @@ def _after(responder_or_resource):
             for responder_name, responder in getmembers(resource, callable):
                 if _DECORABLE_METHOD_NAME.match(responder_name):
                     def let(responder=responder):
-                        do_after_all = _wrap_with_after(responder, action, args, kwargs)
+                        do_after_all = _wrap_with_after(
+                            responder,
+                            action,
+                            args,
+                            kwargs,
+                            is_async
+                        )
 
                         setattr(resource, responder_name, do_after_all)
 
@@ -123,7 +167,7 @@ def let(responder=responder):
 
         else:
             responder = responder_or_resource
-            do_after_one = _wrap_with_after(responder, action, args, kwargs)
+            do_after_one = _wrap_with_after(responder, action, args, kwargs, is_async)
 
             return do_after_one
 
@@ -135,7 +179,7 @@ def let(responder=responder):
 # -----------------------------------------------------------------------------
 
 
-def _wrap_with_after(responder, action, action_args, action_kwargs):
+def _wrap_with_after(responder, action, action_args, action_kwargs, is_async):
     """Execute the given action function after a responder method.
 
     Args:
@@ -144,13 +188,21 @@ def _wrap_with_after(responder, action, action_args, action_kwargs):
             method, taking the form ``func(req, resp, resource)``.
         action_args: Additional positional agruments to pass to *action*.
         action_kwargs: Additional keyword arguments to pass to *action*.
+        is_async: Set to ``True`` for cythonized responders that are
+            actually coroutine functions, since such responders can not
+            be auto-detected. A hint is also required for regular functions
+            that happen to return an awaitable coroutine object.
     """
 
     responder_argnames = get_argnames(responder)
     extra_argnames = responder_argnames[2:]  # Skip req, resp
 
-    if iscoroutinefunction(responder):
-        action = _wrap_non_coroutine_unsafe(action)
+    if is_async or iscoroutinefunction(responder):
+        # NOTE(kgriffs): I manually verified that the implicit "else" branch
+        #   is actually covered, but coverage isn't tracking it for
+        #   some reason.
+        if not is_async:  # pragma: nocover
+            action = _wrap_non_coroutine_unsafe(action)
 
         @wraps(responder)
         async def do_after(self, req, resp, *args, **kwargs):
@@ -171,7 +223,7 @@ def do_after(self, req, resp, *args, **kwargs):
     return do_after
 
 
-def _wrap_with_before(responder, action, action_args, action_kwargs):
+def _wrap_with_before(responder, action, action_args, action_kwargs, is_async):
     """Execute the given action function before a responder method.
 
     Args:
@@ -180,13 +232,21 @@ def _wrap_with_before(responder, action, action_args, action_kwargs):
             method, taking the form ``func(req, resp, resource, params)``.
         action_args: Additional positional agruments to pass to *action*.
         action_kwargs: Additional keyword arguments to pass to *action*.
+        is_async: Set to ``True`` for cythonized responders that are
+            actually coroutine functions, since such responders can not
+            be auto-detected. A hint is also required for regular functions
+            that happen to return an awaitable coroutine object.
     """
 
     responder_argnames = get_argnames(responder)
     extra_argnames = responder_argnames[2:]  # Skip req, resp
 
-    if iscoroutinefunction(responder):
-        action = _wrap_non_coroutine_unsafe(action)
+    if is_async or iscoroutinefunction(responder):
+        # NOTE(kgriffs): I manually verified that the implicit "else" branch
+        #   is actually covered, but coverage isn't tracking it for
+        #   some reason.
+        if not is_async:  # pragma: nocover
+            action = _wrap_non_coroutine_unsafe(action)
 
         @wraps(responder)
         async def do_before(self, req, resp, *args, **kwargs):