webob.cookies – Cookies — WebOb 1.6.0 documentation

# `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