diff --git a/docs/sanic/cookies.md b/docs/sanic/cookies.md deleted file mode 100644 index e71bcc47..00000000 --- a/docs/sanic/cookies.md +++ /dev/null @@ -1,75 +0,0 @@ -# Cookies - -Cookies are pieces of data which persist inside a user's browser. Sanic can -both read and write cookies, which are stored as key-value pairs. - -## Reading cookies - -A user's cookies can be accessed via the `Request` object's `cookies` dictionary. - -```python -from sanic.response import text - -@app.route("/cookie") -async def test(request): - test_cookie = request.cookies.get('test') - return text("Test cookie set to: {}".format(test_cookie)) -``` - -## Writing cookies - -When returning a response, cookies can be set on the `Response` object. - -```python -from sanic.response import text - -@app.route("/cookie") -async def test(request): - response = text("There's a cookie up in this response") - response.cookies['test'] = 'It worked!' - response.cookies['test']['domain'] = '.gotta-go-fast.com' - response.cookies['test']['httponly'] = True - return response -``` - -## Deleting cookies - -Cookies can be removed semantically or explicitly. - -```python -from sanic.response import text - -@app.route("/cookie") -async def test(request): - response = text("Time to eat some cookies muahaha") - - # This cookie will be set to expire in 0 seconds - del response.cookies['kill_me'] - - # This cookie will self destruct in 5 seconds - response.cookies['short_life'] = 'Glad to be here' - response.cookies['short_life']['max-age'] = 5 - del response.cookies['favorite_color'] - - # This cookie will remain unchanged - response.cookies['favorite_color'] = 'blue' - response.cookies['favorite_color'] = 'pink' - del response.cookies['favorite_color'] - - return response -``` - -Response cookies can be set like dictionary values and have the following -parameters available: - -- `expires` (datetime): The time for the cookie to expire on the - client's browser. -- `path` (string): The subset of URLs to which this cookie applies. Defaults to /. -- `comment` (string): A comment (metadata). -- `domain` (string): Specifies the domain for which the cookie is valid. An - explicitly specified domain must always start with a dot. -- `max-age` (number): Number of seconds the cookie should live for. -- `secure` (boolean): Specifies whether the cookie will only be sent via - HTTPS. -- `httponly` (boolean): Specifies whether the cookie cannot be read by - Javascript. diff --git a/docs/sanic/cookies.rst b/docs/sanic/cookies.rst new file mode 100644 index 00000000..c4e0c0a1 --- /dev/null +++ b/docs/sanic/cookies.rst @@ -0,0 +1,87 @@ +Cookies +======= + +Cookies are pieces of data which persist inside a user's browser. Sanic can +both read and write cookies, which are stored as key-value pairs. + +.. warning:: + + Cookies can be freely altered by the client. Therefore you cannot just store + data such as login information in cookies as-is, as they can be freely altered + by the client. To ensure data you store in cookies is not forged or tampered + with by the client, use something like `itsdangerous`_ to cryptographically + sign the data. + + +Reading cookies +--------------- + +A user's cookies can be accessed via the ``Request`` object's ``cookies`` dictionary. + +.. code-block:: python + + from sanic.response import text + + @app.route("/cookie") + async def test(request): + test_cookie = request.cookies.get('test') + return text("Test cookie set to: {}".format(test_cookie)) + +Writing cookies +--------------- + +When returning a response, cookies can be set on the ``Response`` object. + +.. code-block:: python + + from sanic.response import text + + @app.route("/cookie") + async def test(request): + response = text("There's a cookie up in this response") + response.cookies['test'] = 'It worked!' + response.cookies['test']['domain'] = '.gotta-go-fast.com' + response.cookies['test']['httponly'] = True + return response + +Deleting cookies +---------------- + +Cookies can be removed semantically or explicitly. + +.. code-block:: python + + from sanic.response import text + + @app.route("/cookie") + async def test(request): + response = text("Time to eat some cookies muahaha") + + # This cookie will be set to expire in 0 seconds + del response.cookies['kill_me'] + + # This cookie will self destruct in 5 seconds + response.cookies['short_life'] = 'Glad to be here' + response.cookies['short_life']['max-age'] = 5 + del response.cookies['favorite_color'] + + # This cookie will remain unchanged + response.cookies['favorite_color'] = 'blue' + response.cookies['favorite_color'] = 'pink' + del response.cookies['favorite_color'] + + return response + +Response cookies can be set like dictionary values and have the following +parameters available: + +- ``expires`` (datetime): The time for the cookie to expire on the client's browser. +- ``path`` (string): The subset of URLs to which this cookie applies. Defaults to /. +- ``comment`` (string): A comment (metadata). +- ``domain`` (string): Specifies the domain for which the cookie is valid. An + explicitly specified domain must always start with a dot. +- ``max-age`` (number): Number of seconds the cookie should live for. +- ``secure`` (boolean): Specifies whether the cookie will only be sent via HTTPS. +- ``httponly`` (boolean): Specifies whether the cookie cannot be read by Javascript. + +.. _itsdangerous: https://pythonhosted.org/itsdangerous/ \ No newline at end of file