webob.cookies — Cookies

Cookies

class webob.cookies.CookieProfile(cookie_name, secure=False, max_age=None, httponly=None, path=’/‘, domains=None, serializer=None)

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 and dumps. The loads method should accept a bytestring and return a Python object. The dumps method should accept a Python object and return bytes. A ValueError should be raised for malformed inputs. Default: None, which will use a derivation of json.dumps() and json.loads().

• bind(request)

  Bind a request to a copy of this instance and return it

• get_headers(value, domains=<object object>, max_age=<object object>, path=<object object>, secure=<object object>, httponly=<object object>)

  Retrieve raw headers for setting cookies.

  Returns a list of headers that should be set for the cookies to be correctly tracked.

• get_value()

  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_cookies(response, value, domains=<object object>, max_age=<object object>, path=<object object>, secure=<object object>, httponly=<object object>)

  Set the cookies on a response.

class webob.cookies.SignedCookieProfile(secret, salt, cookie_name, secure=False, max_age=None, httponly=False, path=’/‘, domains=None, hashalg=’sha512’, serializer=None)

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. The loads method should accept bytes and return a Python object. The dumps method should accept a Python object and return bytes. A ValueError should be raised for malformed inputs. Default: None`, which will use a derivation of :func:`json.dumps` and ``json.loads.

• bind(request)

  Bind a request to a copy of this instance and return it

class webob.cookies.SignedSerializer(secret, salt, hashalg=’sha512’, serializer=None)

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. The loads method should accept bytes and return a Python object. The dumps method should accept a Python object and return bytes. A ValueError should be raised for malformed inputs. Default: None`, which will use a derivation of :func:`json.dumps` and ``json.loads.

• dumps(appstruct)

  Given an appstruct, serialize and sign the data.

  Returns a bytestring.

• loads(bstruct)

  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.

class webob.cookies.JSONSerializer

A serializer which uses json.dumps` and json.loads

webob.cookies.make_cookie(name, value, max_age=None, path=’/‘, domain=None, secure=False, httponly=False, comment=None)

Generate a cookie value. If value is None, generate a cookie value with an expiration date in the past