From 4dedf7ce96db6afeeb598f3b2a78b471e4a8ccca Mon Sep 17 00:00:00 2001 From: Alexander Botello Date: Wed, 17 Oct 2018 05:15:32 -0500 Subject: [PATCH] Add documentation for cookies (#116) * Add cookies to request docs * Add cookies to response docs * Reformat the postion of methods --- docs/requests.md | 10 ++++++++++ docs/responses.md | 21 +++++++++++++++++++++ 2 files changed, 31 insertions(+) diff --git a/docs/requests.md b/docs/requests.md index 7fa40834..18676dd8 100644 --- a/docs/requests.md +++ b/docs/requests.md @@ -55,6 +55,16 @@ Headers are exposed as an immutable multi-dict. For example: `request.query_params['abc']` +#### Cookies + +Cookies are exposed as an immutable dict. + +**Note**: Exception `KeyError` will be raised if nonexistant key is accessed as `request.cookies['key']`. +Instead cookies should be accessed with the `.get` method. + +For example: `request.cookies.get('mycookie')` + + #### Body There are a few different interfaces for returning the body of the request: diff --git a/docs/responses.md b/docs/responses.md index 73fe8e81..ff87d430 100644 --- a/docs/responses.md +++ b/docs/responses.md @@ -30,6 +30,27 @@ class App: response = Response('Hello, world!', media_type='text/plain') await response(receive, send) ``` +#### Set Cookie + +Starlette provides a `set_cookie` method to allow you to set cookies on the response object. + +Signature: `Response.set_cookie(key, value, max_age=None, expires=None, path="/", domain=None, secure=False, httponly=False)` + +* `key` - A string that will be the cookie's key. +* `value` - A string that will be the cookie's value. +* `max_age` - An integer that defines the lifetime of the cookie in seconds. A negative integer or a value of `0` will discard the cookie immediately. `Optional` +* `expires` - An integer that defines the number of seconds until the cookie expires. `Optional` +* `path` - A string that specifies the subset of routes to which the cookie will apply. `Optional` +* `domain` - A string that specifies the domain for which the cookie is valid. `Optional` +* `secure` - A bool indicating that the cookie will only be sent to the server if request is made using SSL and the HTTPS protocol. `Optional` +* `httponly` - A bool indicating that the cookie cannot be accessed via Javascript through `Document.cookie` property, the `XMLHttpRequest` or `Request` APIs. `Optional` + +#### Delete Cookie + +Conversly, Starlette also provides a `delete_cookie` method to manually expire a set cookie. + +Signature: `Response.delete_cookie(key, path='/', domain=None)` + ### HTMLResponse