webob.cookies
– Cookies¶
Cookies¶
A helper class that helps bring some sanity to the insanity that is cookie handling.
The helper is capable of generating multiple cookies if necessary to support subdomains and parent domains.
cookie_name
- The name of the cookie used for sessioning. Default:
'session'
. max_age
- The maximum age of the cookie used for sessioning (in seconds).
Default:
None
(browser scope). secure
- The ‘secure’ flag of the session cookie. Default:
False
. httponly
- Hide the cookie from Javascript by setting the ‘HttpOnly’ flag of the
session cookie. Default:
False
. path
- The path used for the session cookie. Default:
'/'
. domains
- The domain(s) used for the session cookie. Default:
None
(no domain). Can be passed an iterable containing multiple domains, this will set multiple cookies one for each domain. serializer
- An object with two methods:
loads
anddumps
. Theloads
method should accept a bytestring and return a Python object. Thedumps
method should accept a Python object and return bytes. AValueError
should be raised for malformed inputs. Default:None
, which will use a derivation ofjson.dumps()
andjson.loads()
.
Bind a request to a copy of this instance and return it
Retrieve raw headers for setting cookies.
Returns a list of headers that should be set for the cookies to be correctly tracked.
Looks for a cookie by name in the currently bound request, and returns its value. If the cookie profile is not bound to a request, this method will raise a
ValueError
.Looks for the cookie in the cookies jar, and if it can find it it will attempt to deserialize it. Returns
None
if there is no cookie or if the value in the cookie cannot be successfully deserialized.
Set the cookies on a response.
A helper for generating cookies that are signed to prevent tampering.
By default this will create a single cookie, given a value it will serialize it, then use HMAC to cryptographically sign the data. Finally the result is base64-encoded for transport. This way a remote user can not tamper with the value without uncovering the secret/salt used.
secret
- A string which is used to sign the cookie. The secret should be at
least as long as the block size of the selected hash algorithm. For
sha512
this would mean a 128 bit (64 character) secret. salt
- A namespace to avoid collisions between different uses of a shared secret.
hashalg
- The HMAC digest algorithm to use for signing. The algorithm must be
supported by the
hashlib
library. Default:'sha512'
. cookie_name
- The name of the cookie used for sessioning. Default:
'session'
. max_age
- The maximum age of the cookie used for sessioning (in seconds).
Default:
None
(browser scope). secure
- The ‘secure’ flag of the session cookie. Default:
False
. httponly
- Hide the cookie from Javascript by setting the ‘HttpOnly’ flag of the
session cookie. Default:
False
. path
- The path used for the session cookie. Default:
'/'
. domains
- The domain(s) used for the session cookie. Default:
None
(no domain). Can be passed an iterable containing multiple domains, this will set multiple cookies one for each domain. serializer
- An object with two methods: loads` and
dumps
. Theloads
method should accept bytes and return a Python object. Thedumps
method should accept a Python object and return bytes. AValueError
should be raised for malformed inputs. Default:None`, which will use a derivation of :func:`json.dumps` and ``json.loads
.
Bind a request to a copy of this instance and return it
A helper to cryptographically sign arbitrary content using HMAC.
The serializer accepts arbitrary functions for performing the actual serialization and deserialization.
secret
- A string which is used to sign the cookie. The secret should be at
least as long as the block size of the selected hash algorithm. For
sha512
this would mean a 128 bit (64 character) secret. salt
- A namespace to avoid collisions between different uses of a shared secret.
hashalg
- The HMAC digest algorithm to use for signing. The algorithm must be
supported by the
hashlib
library. Default:'sha512'
. serializer
- An object with two methods: loads` and
dumps
. Theloads
method should accept bytes and return a Python object. Thedumps
method should accept a Python object and return bytes. AValueError
should be raised for malformed inputs. Default:None`, which will use a derivation of :func:`json.dumps` and ``json.loads
.
Given an
appstruct
, serialize and sign the data.Returns a bytestring.
Given a
bstruct
(a bytestring), verify the signature and then deserialize and return the deserialized value.A
ValueError
will be raised if the signature fails to validate.
A serializer which uses json.dumps` and
json.loads
Generate a cookie value. If
value
is None, generate a cookie value with an expiration date in the past