webob.cookies — Cookies

Cookies

class webob.cookies.CookieProfile(cookie_name, secure=False, max_age=None, httponly=None, samesite=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.

    samesite

    The ‘SameSite’ attribute of the cookie, can be either b"strict", b"lax", b"none", or None.

    For more information please see the samesite documentation in webob.cookies.make_cookie()

    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_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>, samesite=<object object>)

    Set the cookies on a response.

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

    Retrieve raw headers for setting cookies.

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

class webob.cookies.SignedCookieProfile(secret, salt, cookie_name, secure=False, max_age=None, httponly=False, samesite=None, 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 512 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.

    samesite

    The ‘SameSite’ attribute of the cookie, can be either b"strict", b"lax", b"none", or None.

    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 512 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, samesite=None)

Generate a cookie value.

  • name

    The name of the cookie.

    value

    The value of the cookie. If it is None, it will generate a cookie value with an expiration date in the past.

    max_age

    The maximum age of the cookie used for sessioning (in seconds). Default: None (browser scope).

    path

    The path used for the session cookie. Default: /.

    domain

    The domain used for the session cookie. Default: None (no domain).

    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.

    comment

    Set a comment on the cookie. Default: None

    samesite

    The ‘SameSite’ attribute of the cookie, can be either "strict", "lax", "none", or None. By default, WebOb will validate the value to ensure it conforms to the allowable options in the various draft RFC’s that exist.

    To disable this check and send headers that are experimental or introduced in a future RFC, set the module flag SAMESITE_VALIDATION to a false value like:

    1. import webob.cookies
    2. webob.cookies.SAMESITE_VALIDATION = False
    4. ck = webob.cookies.make_cookie(cookie_name, value, samesite='future')

    Danger

    This feature has known compatibility issues with various user agents, and is not yet an accepted RFC. It is therefore considered experimental and subject to change.

    For more information please see Experimental: SameSite Cookies