openstack/deb-python-falcon
Code Issues Proposed changes

doc(Middleware): Correct and clarify a few passages of text

Browse Source 
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.
This commit is contained in:
Kurt Griffiths
2015-02-17 11:33:20 -06:00
parent 326cc2f534
commit f9d0ef65d2
1 changed files with 8 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
doc/api/middleware.rst
View File

@@ -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 <api>`.
for each request. Components are registered with the `middleware` kwarg
when instantiating Falcon's :ref:`API class <api>`.
.. 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<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