Merge pull request #1449 from chenjr0719/add_amending_request_object_example

Add example of amending request object

docs/sanic/examples.rst

@@ -156,4 +156,12 @@ execution support provided by the ``pytest-xdist`` plugin.
 
 .. literalinclude:: ../../examples/pytest_xdist.py
 
+
+Amending Request Object
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``request`` object in ``Sanic`` is a kind of ``dict`` object, this means that ``reqeust`` object can be manipulated as a regular ``dict`` object.
+
+.. literalinclude:: ../../examples/amending_request_object.py
+
 For more examples and useful samples please visit the `Huge-Sanic's GitHub Page <https://github.com/huge-success/sanic/tree/master/examples>`_

docs/sanic/extensions.md

@@ -41,7 +41,7 @@ A list of Sanic extensions created by the community.
 
 ## Project Creation Template
 
-- [cookiecutter-sanic](https://github.com/harshanarayana/cookiecutter-sanic) Get your sanic application up and running in a matter of second in a well defined project structure.
+- [cookiecutter-sanic](https://github.com/harshanarayana/cookiecutter-sanic): Get your sanic application up and running in a matter of second in a well defined project structure.
     Batteries included for deployment, unit testing, automated release management and changelog generation.
 
 ## Templating

docs/sanic/middleware.md

@@ -36,20 +36,31 @@ this.
 ```
 app = Sanic(__name__)
 
+
+@app.middleware('request')
+async def add_key(request):
+    # Add a key to request object like dict object
+    request['foo'] = 'bar'
+
+
 @app.middleware('response')
 async def custom_banner(request, response):
 	response.headers["Server"] = "Fake-Server"
 
+
 @app.middleware('response')
 async def prevent_xss(request, response):
 	response.headers["x-xss-protection"] = "1; mode=block"
 
+
 app.run(host="0.0.0.0", port=8000)
 ```
 
-The above code will apply the two middleware in order. First, the middleware
+The above code will apply the three middleware in order. The first middleware
+**add_key** will add a new key `foo` into `request` object. This worked because
+`request` object can be manipulated like `dict` object. Then, the second middleware
 **custom_banner** will change the HTTP response header *Server* to
-*Fake-Server*, and the second middleware **prevent_xss** will add the HTTP
+*Fake-Server*, and the last middleware **prevent_xss** will add the HTTP
 header for preventing Cross-Site-Scripting (XSS) attacks. These two functions
 are invoked *after* a user function returns a response.
 

examples/amending_request_object.py

@@ -0,0 +1,30 @@
+from sanic import Sanic
+from sanic.response import text
+from random import randint
+
+app = Sanic()
+
+
+@app.middleware('request')
+def append_request(request):
+    # Add new key with random value
+    request['num'] = randint(0, 100)
+
+
+@app.get('/pop')
+def pop_handler(request):
+    # Pop key from request object
+    num = request.pop('num')
+    return text(num)
+
+
+@app.get('/key_exist')
+def key_exist_handler(request):
+    # Check the key is exist or not
+    if 'num' in request:
+        return text('num exist in request')
+
+    return text('num does not exist in reqeust')
+
+
+app.run(host="0.0.0.0", port=8000, debug=True)