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 - samesitedocumentation 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: - loadsand- dumps. The- loadsmethod should accept a bytestring and return a Python object. The- dumpsmethod should accept a Python object and return bytes. A- ValueErrorshould 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 - Noneif 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 - sha512this 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 - hashliblibrary. 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- loadsmethod should accept bytes and return a Python object. The- dumpsmethod should accept a Python object and return bytes. A- ValueErrorshould 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 - sha512this 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 - hashliblibrary. Default:- 'sha512'.
- serializer
- An object with two methods: loads` and - dumps. The- loadsmethod should accept bytes and return a Python object. The- dumpsmethod should accept a Python object and return bytes. A- ValueErrorshould 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 - ValueErrorwill 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 - valueof 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_VALIDATIONto 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