webob.cookies -- Cookies — WebOb 1.8.7 documentation

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

        import webob.cookies
        webob.cookies.SAMESITE_VALIDATION = False

        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