From f9d0ef65d2652907758afbe934f558fbee2cb849 Mon Sep 17 00:00:00 2001 From: Kurt Griffiths Date: Tue, 17 Feb 2015 11:33:20 -0600 Subject: [PATCH] doc(Middleware): Correct and clarify a few passages of text The middleware components page includes a tip that talks about modifying req.uri. That is a read-only property. Instead, the tip should refer to req.path. Also clarify that middleware is executed based on the order of the list that was passed to falcon.API via the middleware kwarg. --- doc/api/middleware.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/api/middleware.rst b/doc/api/middleware.rst index abdc64c..0773902 100644 --- a/doc/api/middleware.rst +++ b/doc/api/middleware.rst @@ -6,8 +6,8 @@ Middleware Components Middleware components provide a way to execute logic before the framework routes each request, after each request is routed but before the target responder is called, or just before the response is returned -for each request. Components are registered with the `middleware` kwarg when instantiating -Falcon's :ref:`API class `. +for each request. Components are registered with the `middleware` kwarg +when instantiating Falcon's :ref:`API class `. .. Note:: Unlike hooks, middleware methods apply globally to the entire API. @@ -53,13 +53,14 @@ Falcon's middleware interface is defined as follows: .. Tip:: Because *process_request* executes before routing has occurred, if a - component modifies ``req.uri`` in its *process_request* method, + component modifies ``req.path`` in its *process_request* method, the framework will use the modified value to route the request. Each component's *process_request*, *process_resource*, and -*process_response* methods are executed hierarchically, as a stack. -For example, if a list of middleware objects are passed as -``[mob1, mob2, mob3]``, the order of execution is as follows:: +*process_response* methods are executed hierarchically, as a stack, following +the ordering of the list passed via the `middleware` kwarg of +:ref:`falcon.API`. For example, if a list of middleware objects are +passed as ``[mob1, mob2, mob3]``, the order of execution is as follows:: mob1.process_request mob2.process_request @@ -72,7 +73,7 @@ For example, if a list of middleware objects are passed as mob2.process_response mob1.process_response -Note that each component need not implement all process_* +Note that each component need not implement all `process_*` methods; in the case that one of the three methods is missing, it is treated as a noop in the stack. For example, if ``mob2`` did not implement *process_request* and ``mob3`` did not implement