http.cookies — HTTP state management

Source code:Lib/http/cookies.py

Thehttp.cookies module defines classes for abstracting the concept ofcookies, an HTTP state management mechanism. It supports both simple string-onlycookies, and provides an abstraction for having any serializable data-type ascookie value.

The module formerly strictly applied the parsing rules described in theRFC 2109 andRFC 2068 specifications. It has since been discovered thatMSIE 3.0x doesn’t follow the character rules outlined in those specs and alsomany current day browsers and servers have relaxed parsing rules when comes toCookie handling. As a result, the parsing rules used are a bit less strict.

The character set,string.ascii_letters,string.digits and!#$%&'*+-.^_`|~: denote the set of valid characters allowed by this modulein Cookie name (askey).

Changed in version 3.3:Allowed ‘:’ as a valid Cookie name character.

Note

On encountering an invalid cookie,CookieError is raised, so if yourcookie data comes from a browser you should always prepare for invalid dataand catchCookieError on parsing.

exceptionhttp.cookies.CookieError

Exception failing because ofRFC 2109 invalidity: incorrect attributes,incorrectSet-Cookie header, etc.

classhttp.cookies.BaseCookie([input])

This class is a dictionary-like object whose keys are strings and whose valuesareMorsel instances. Note that upon setting a key to a value, thevalue is first converted to aMorsel containing the key and the value.

Ifinput is given, it is passed to theload() method.

classhttp.cookies.SimpleCookie([input])

This class derives fromBaseCookie and overridesvalue_decode()andvalue_encode(). SimpleCookie supports strings as cookie values.When setting the value, SimpleCookie calls the builtinstr() to convertthe value to a string. Values received from HTTP are kept as strings.

See also

Modulehttp.cookiejar

HTTP cookie handling for webclients. Thehttp.cookiejar andhttp.cookies modules do not depend on each other.

RFC 2109 - HTTP State Management Mechanism

This is the state management specification implemented by this module.

Cookie Objects

BaseCookie.value_decode(val)

Return a tuple(real_value,coded_value) from a string representation.real_value can be any type. This method does no decoding inBaseCookie — it exists so it can be overridden.

BaseCookie.value_encode(val)

Return a tuple(real_value,coded_value).val can be any type, butcoded_value will always be converted to a string.This method does no encoding inBaseCookie — it exists so it canbe overridden.

In general, it should be the case thatvalue_encode() andvalue_decode() are inverses on the range ofvalue_decode.

BaseCookie.output(attrs=None,header='Set-Cookie:',sep='\r\n')

Return a string representation suitable to be sent as HTTP headers.attrs andheader are sent to eachMorsel’soutput() method.sep is usedto join the headers together, and is by default the combination'\r\n'(CRLF).

BaseCookie.js_output(attrs=None)

Return an embeddable JavaScript snippet, which, if run on a browser whichsupports JavaScript, will act the same as if the HTTP headers was sent.

The meaning forattrs is the same as inoutput().

BaseCookie.load(rawdata)

Ifrawdata is a string, parse it as anHTTP_COOKIE and add the valuesfound there asMorsels. If it is a dictionary, it is equivalent to:

fork,vinrawdata.items():cookie[k]=v

Morsel Objects

classhttp.cookies.Morsel

Abstract a key/value pair, which has someRFC 2109 attributes.

Morsels are dictionary-like objects, whose set of keys is constant — the validRFC 2109 attributes, which are

  • expires

  • path

  • comment

  • domain

  • max-age

  • secure

  • version

  • httponly

  • samesite

The attributehttponly specifies that the cookie is only transferredin HTTP requests, and is not accessible through JavaScript. This is intendedto mitigate some forms of cross-site scripting.

The attributesamesite specifies that the browser is not allowed tosend the cookie along with cross-site requests. This helps to mitigate CSRFattacks. Valid values for this attribute are “Strict” and “Lax”.

The keys are case-insensitive and their default value is''.

Changed in version 3.5:__eq__() now takeskey andvalueinto account.

Changed in version 3.7:Attributeskey,value andcoded_value are read-only. Useset() forsetting them.

Changed in version 3.8:Added support for thesamesite attribute.

Morsel.value

The value of the cookie.

Morsel.coded_value

The encoded value of the cookie — this is what should be sent.

Morsel.key

The name of the cookie.

Morsel.set(key,value,coded_value)

Set thekey,value andcoded_value attributes.

Morsel.isReservedKey(K)

WhetherK is a member of the set of keys of aMorsel.

Morsel.output(attrs=None,header='Set-Cookie:')

Return a string representation of the Morsel, suitable to be sent as an HTTPheader. By default, all the attributes are included, unlessattrs is given, inwhich case it should be a list of attributes to use.header is by default"Set-Cookie:".

Morsel.js_output(attrs=None)

Return an embeddable JavaScript snippet, which, if run on a browser whichsupports JavaScript, will act the same as if the HTTP header was sent.

The meaning forattrs is the same as inoutput().

Morsel.OutputString(attrs=None)

Return a string representing the Morsel, without any surrounding HTTP orJavaScript.

The meaning forattrs is the same as inoutput().

Morsel.update(values)

Update the values in the Morsel dictionary with the values in the dictionaryvalues. Raise an error if any of the keys in thevalues dict is not avalidRFC 2109 attribute.

Changed in version 3.5:an error is raised for invalid keys.

Morsel.copy(value)

Return a shallow copy of the Morsel object.

Changed in version 3.5:return a Morsel object instead of a dict.

Morsel.setdefault(key,value=None)

Raise an error if key is not a validRFC 2109 attribute, otherwisebehave the same asdict.setdefault().

Example

The following example demonstrates how to use thehttp.cookies module.

>>>fromhttpimportcookies>>>C=cookies.SimpleCookie()>>>C["fig"]="newton">>>C["sugar"]="wafer">>>print(C)# generate HTTP headersSet-Cookie: fig=newtonSet-Cookie: sugar=wafer>>>print(C.output())# same thingSet-Cookie: fig=newtonSet-Cookie: sugar=wafer>>>C=cookies.SimpleCookie()>>>C["rocky"]="road">>>C["rocky"]["path"]="/cookie">>>print(C.output(header="Cookie:"))Cookie: rocky=road; Path=/cookie>>>print(C.output(attrs=[],header="Cookie:"))Cookie: rocky=road>>>C=cookies.SimpleCookie()>>>C.load("chips=ahoy; vienna=finger")# load from a string (HTTP header)>>>print(C)Set-Cookie: chips=ahoySet-Cookie: vienna=finger>>>C=cookies.SimpleCookie()>>>C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')>>>print(C)Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;">>>C=cookies.SimpleCookie()>>>C["oreo"]="doublestuff">>>C["oreo"]["path"]="/">>>print(C)Set-Cookie: oreo=doublestuff; Path=/>>>C=cookies.SimpleCookie()>>>C["twix"]="none for you">>>C["twix"].value'none for you'>>>C=cookies.SimpleCookie()>>>C["number"]=7# equivalent to C["number"] = str(7)>>>C["string"]="seven">>>C["number"].value'7'>>>C["string"].value'seven'>>>print(C)Set-Cookie: number=7Set-Cookie: string=seven