def _wrap_with_after(responder, action, action_args, action_kwargs): """Execute the given action function after a responder method. Args: responder: The responder method to wrap. action: A function with a signature similar to a resource responder 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*. """ responder_argnames = get_argnames(responder) extra_argnames = responder_argnames[2:] # Skip req, resp if iscoroutinefunction(responder): action = _wrap_non_coroutine_unsafe(action) @wraps(responder) async def do_after(self, req, resp, *args, **kwargs): if args: _merge_responder_args(args, kwargs, extra_argnames) await responder(self, req, resp, **kwargs) await action(req, resp, self, *action_args, **action_kwargs) else: @wraps(responder) def do_after(self, req, resp, *args, **kwargs): if args: _merge_responder_args(args, kwargs, extra_argnames) responder(self, req, resp, **kwargs) action(req, resp, self, *action_args, **action_kwargs) return do_after
def add_error_handler(self, exception, handler=None): if not handler: try: handler = exception.handle except AttributeError: # NOTE(kgriffs): Delegate to the parent method for error handling. pass handler = _wrap_non_coroutine_unsafe(handler) if handler and not iscoroutinefunction(handler): raise CompatibilityError( 'The handler must be an awaitable coroutine function in order ' 'to be used safely with an ASGI app.') super().add_error_handler(exception, handler=handler)
def _wrap_with_before(responder, action, action_args, action_kwargs, is_async): """Execute the given action function before a responder method. Args: responder: The responder method to wrap. action: A function with a similar signature to a resource responder 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 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): if args: _merge_responder_args(args, kwargs, extra_argnames) await action(req, resp, self, kwargs, *action_args, **action_kwargs) await responder(self, req, resp, **kwargs) else: @wraps(responder) def do_before(self, req, resp, *args, **kwargs): if args: _merge_responder_args(args, kwargs, extra_argnames) action(req, resp, self, kwargs, *action_args, **action_kwargs) responder(self, req, resp, **kwargs) return do_before
def add_error_handler(self, exception, handler=None): """Register a handler for one or more exception types. Error handlers may be registered for any exception type, including :class:`~.HTTPError` or :class:`~.HTTPStatus`. This feature provides a central location for logging and otherwise handling exceptions raised by responders, hooks, and middleware components. A handler can raise an instance of :class:`~.HTTPError` or :class:`~.HTTPStatus` to communicate information about the issue to the client. Alternatively, a handler may modify `resp` directly. An error handler "matches" a raised exception if the exception is an instance of the corresponding exception type. If more than one error handler matches the raised exception, the framework will choose the most specific one, as determined by the method resolution order of the raised exception type. If multiple error handlers are registered for the *same* exception class, then the most recently-registered handler is used. For example, suppose we register error handlers as follows:: app = App() app.add_error_handler(falcon.HTTPNotFound, custom_handle_not_found) app.add_error_handler(falcon.HTTPError, custom_handle_http_error) app.add_error_handler(Exception, custom_handle_uncaught_exception) app.add_error_handler(falcon.HTTPNotFound, custom_handle_404) If an instance of ``falcon.HTTPForbidden`` is raised, it will be handled by ``custom_handle_http_error()``. ``falcon.HTTPError`` is a superclass of ``falcon.HTTPForbidden`` and a subclass of ``Exception``, so it is the most specific exception type with a registered handler. If an instance of ``falcon.HTTPNotFound`` is raised, it will be handled by ``custom_handle_404()``, not by ``custom_handle_not_found()``, because ``custom_handle_404()`` was registered more recently. .. Note:: By default, the framework installs three handlers, one for :class:`~.HTTPError`, one for :class:`~.HTTPStatus`, and one for the standard ``Exception`` type, which prevents passing uncaught exceptions to the WSGI server. These can be overridden by adding a custom error handler method for the exception type in question. Args: exception (type or iterable of types): When handling a request, whenever an error occurs that is an instance of the specified type(s), the associated handler will be called. Either a single type or an iterable of types may be specified. handler (callable): A coroutine function taking the form ``async func(req, resp, ex, params)``. If not specified explicitly, the handler will default to ``exception.handle``, where ``exception`` is the error type specified above, and ``handle`` is a static method (i.e., decorated with ``@staticmethod``) that accepts the same params just described. For example:: class CustomException(CustomBaseException): @staticmethod async def handle(req, resp, ex, params): # TODO: Log the error # Convert to an instance of falcon.HTTPError raise falcon.HTTPError(falcon.HTTP_792) If an iterable of exception types is specified instead of a single type, the handler must be explicitly specified. """ if handler is None: try: handler = exception.handle except AttributeError: raise AttributeError('handler must either be specified ' 'explicitly or defined as a static' 'method named "handle" that is a ' 'member of the given exception class.') handler = _wrap_non_coroutine_unsafe(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.') try: exception_tuple = tuple(exception) except TypeError: exception_tuple = (exception, ) for exc in exception_tuple: if not issubclass(exc, BaseException): raise TypeError('"exception" must be an exception type.') self._error_handlers[exc] = handler
def add_error_handler(self, exception, handler=None): """Register a handler for one or more exception types. Error handlers may be registered for any exception type, including :class:`~.HTTPError` or :class:`~.HTTPStatus`. This feature provides a central location for logging and otherwise handling exceptions raised by responders, hooks, and middleware components. A handler can raise an instance of :class:`~.HTTPError` or :class:`~.HTTPStatus` to communicate information about the issue to the client. Alternatively, a handler may modify `resp` directly. An error handler "matches" a raised exception if the exception is an instance of the corresponding exception type. If more than one error handler matches the raised exception, the framework will choose the most specific one, as determined by the method resolution order of the raised exception type. If multiple error handlers are registered for the *same* exception class, then the most recently-registered handler is used. For example, suppose we register error handlers as follows:: app = App() app.add_error_handler(falcon.HTTPNotFound, custom_handle_not_found) app.add_error_handler(falcon.HTTPError, custom_handle_http_error) app.add_error_handler(Exception, custom_handle_uncaught_exception) app.add_error_handler(falcon.HTTPNotFound, custom_handle_404) If an instance of ``falcon.HTTPForbidden`` is raised, it will be handled by ``custom_handle_http_error()``. ``falcon.HTTPError`` is a superclass of ``falcon.HTTPForbidden`` and a subclass of ``Exception``, so it is the most specific exception type with a registered handler. If an instance of ``falcon.HTTPNotFound`` is raised, it will be handled by ``custom_handle_404()``, not by ``custom_handle_not_found()``, because ``custom_handle_404()`` was registered more recently. Note: By default, the framework installs three handlers, one for :class:`~.HTTPError`, one for :class:`~.HTTPStatus`, and one for the standard ``Exception`` type, which prevents passing uncaught exceptions to the WSGI server. These can be overridden by adding a custom error handler method for the exception type in question. When a generic unhandled exception is raised while handling a :ref:`WebSocket <ws>` connection, the default handler will close the connection with the standard close code ``1011`` (Internal Error). If your ASGI server does not support this code, the framework will use code ``3011`` instead; or you can customize it via the :attr:`~falcon.asgi.WebSocketOptions.error_close_code` property of :attr:`~.ws_options`. On the other hand, if an ``on_websocket()`` responder raises an instance of :class:`~falcon.HTTPError`, the default error handler will close the :ref:`WebSocket <ws>` connection with a framework close code derived by adding ``3000`` to the HTTP status code (e.g., ``3404``) Args: exception (type or iterable of types): When handling a request, whenever an error occurs that is an instance of the specified type(s), the associated handler will be called. Either a single type or an iterable of types may be specified. Keyword Args: handler (callable): A coroutine function taking the form:: async def func(req, resp, ex, params, ws=None): pass In the case of a WebSocket connection, the `resp` argument will be ``None``, while the `ws` keyword argument will receive the :class:`~falcon.asgi.WebSocket` object representing the connection. If the `handler` keyword argument is not provided to :meth:`~.add_error_handler`, the handler will default to ``exception.handle``, where ``exception`` is the error type specified above, and ``handle`` is a static method (i.e., decorated with ``@staticmethod``) that accepts the params just described. For example:: class CustomException(CustomBaseException): @staticmethod async def handle(req, resp, ex, params): # TODO: Log the error # Convert to an instance of falcon.HTTPError raise falcon.HTTPError(falcon.HTTP_792) Note, however, that if an iterable of exception types is specified instead of a single type, the handler must be explicitly specified using the `handler` keyword argument. """ if handler is None: try: handler = exception.handle except AttributeError: raise AttributeError('handler must either be specified ' 'explicitly or defined as a static' 'method named "handle" that is a ' 'member of the given exception class.') # NOTE(vytas): Do not shoot ourselves in the foot in case error # handlers are our own cythonized code. if handler not in ( self._http_status_handler, self._http_error_handler, self._python_error_handler, ): handler = _wrap_non_coroutine_unsafe(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.') try: exception_tuple = tuple(exception) except TypeError: exception_tuple = (exception, ) for exc in exception_tuple: if not issubclass(exc, BaseException): raise TypeError('"exception" must be an exception type.') self._error_handlers[exc] = handler
def prepare_middleware(middleware, independent_middleware=False, asgi=False): """Check middleware interfaces and prepare the methods for request handling. Arguments: middleware (iterable): An iterable of middleware objects. Keyword Args: independent_middleware (bool): ``True`` if the request and response middleware methods should be treated independently (default ``False``) asgi (bool): ``True`` if an ASGI app, ``False`` otherwise (default ``False``) Returns: tuple: A tuple of prepared middleware method tuples """ # PERF(kgriffs): do getattr calls once, in advance, so we don't # have to do them every time in the request path. request_mw = [] resource_mw = [] response_mw = [] for component in middleware: # NOTE(kgriffs): Middleware that uses parts of the Request and Response # interfaces that are the same between ASGI and WSGI (most of it is, # and we should probably define this via ABC) can just implement # the method names without the *_async postfix. If a middleware # component wants to provide an alternative implementation that # does some work that requires async def, or something specific about # the ASGI Request/Response classes, the component can implement the # *_async method in that case. # # Middleware that is WSGI-only or ASGI-only can simply implement all # methods without the *_async postfix. Regardless, components should # clearly document their compatibility with WSGI vs. ASGI. if asgi: process_request = ( util.get_bound_method(component, 'process_request_async') or _wrap_non_coroutine_unsafe( util.get_bound_method(component, 'process_request') ) ) process_resource = ( util.get_bound_method(component, 'process_resource_async') or _wrap_non_coroutine_unsafe( util.get_bound_method(component, 'process_resource') ) ) process_response = ( util.get_bound_method(component, 'process_response_async') or _wrap_non_coroutine_unsafe( util.get_bound_method(component, 'process_response') ) ) for m in (process_request, process_resource, process_response): if m and not iscoroutinefunction(m): msg = ( '{} must be implemented as an awaitable coroutine. If ' 'you would like to retain compatibility ' 'with WSGI apps, the coroutine versions of the ' 'middleware methods may be implemented side-by-side ' 'by applying an *_async postfix to the method names. ' ) raise CompatibilityError(msg.format(m)) else: process_request = util.get_bound_method(component, 'process_request') process_resource = util.get_bound_method(component, 'process_resource') process_response = util.get_bound_method(component, 'process_response') for m in (process_request, process_resource, process_response): if m and iscoroutinefunction(m): msg = ( '{} may not implement coroutine methods and ' 'remain compatible with WSGI apps without ' 'using the *_async postfix to explicitly identify ' 'the coroutine version of a given middleware ' 'method.' ) raise CompatibilityError(msg.format(component)) if not (process_request or process_resource or process_response): if asgi and ( hasattr(component, 'process_startup') or hasattr(component, 'process_shutdown') ): # NOTE(kgriffs): This middleware only has ASGI lifespan # event handlers continue msg = '{0} must implement at least one middleware method' raise TypeError(msg.format(component)) # NOTE: depending on whether we want to execute middleware # independently, we group response and request middleware either # together or separately. if independent_middleware: if process_request: request_mw.append(process_request) if process_response: response_mw.insert(0, process_response) else: if process_request or process_response: request_mw.append((process_request, process_response)) if process_resource: resource_mw.append(process_resource) return (tuple(request_mw), tuple(resource_mw), tuple(response_mw))
def prepare_middleware(middleware, independent_middleware=False, asgi=False): """Check middleware interfaces and prepare the methods for request handling. Arguments: middleware (iterable): An iterable of middleware objects. Keyword Args: independent_middleware (bool): ``True`` if the request and response middleware methods should be treated independently (default ``False``) asgi (bool): ``True`` if an ASGI app, ``False`` otherwise (default ``False``) Returns: tuple: A tuple of prepared middleware method tuples """ # PERF(kgriffs): do getattr calls once, in advance, so we don't # have to do them every time in the request path. request_mw = [] resource_mw = [] response_mw = [] for component in middleware: # NOTE(kgriffs): Middleware that supports both WSGI and ASGI can # append an *_async postfix to the ASGI version of the method # to distinguish the two. Otherwise, the prefix is unnecessary. if asgi: process_request = ( util.get_bound_method(component, 'process_request_async') or _wrap_non_coroutine_unsafe( util.get_bound_method(component, 'process_request'))) process_resource = ( util.get_bound_method(component, 'process_resource_async') or _wrap_non_coroutine_unsafe( util.get_bound_method(component, 'process_resource'))) process_response = ( util.get_bound_method(component, 'process_response_async') or _wrap_non_coroutine_unsafe( util.get_bound_method(component, 'process_response'))) for m in (process_request, process_resource, process_response): # 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 ' 'with WSGI apps, the coroutine versions of the ' 'middleware methods may be implemented side-by-side ' 'by applying an *_async postfix to the method names. ') raise CompatibilityError(msg.format(m)) else: process_request = util.get_bound_method(component, 'process_request') process_resource = util.get_bound_method(component, 'process_resource') process_response = util.get_bound_method(component, 'process_response') for m in (process_request, process_resource, process_response): if m and iscoroutinefunction(m): msg = ('{} may not implement coroutine methods and ' 'remain compatible with WSGI apps without ' 'using the *_async postfix to explicitly identify ' 'the coroutine version of a given middleware ' 'method.') raise CompatibilityError(msg.format(component)) if not (process_request or process_resource or process_response): if asgi and (hasattr(component, 'process_startup') or hasattr(component, 'process_shutdown')): # NOTE(kgriffs): This middleware only has ASGI lifespan # event handlers continue msg = '{0} must implement at least one middleware method' raise TypeError(msg.format(component)) # NOTE: depending on whether we want to execute middleware # independently, we group response and request middleware either # together or separately. if independent_middleware: if process_request: request_mw.append(process_request) if process_response: response_mw.insert(0, process_response) else: if process_request or process_response: request_mw.append((process_request, process_response)) if process_resource: resource_mw.append(process_resource) return (tuple(request_mw), tuple(resource_mw), tuple(response_mw))