http.cookies — Hantering av HTTP-tillstånd

Källkod: Lib/http/cookies.py

Modulen http.cookies definierar klasser för abstraktion av begreppet cookies, en HTTP-mekanism för tillståndshantering. Den stöder både enkla cookies med enbart strängar och ger en abstraktion för att ha vilken serialiserbar datatyp som helst som cookie-värde.

Modulen tillämpade tidigare strikt de parsing-regler som beskrivs i specifikationerna RFC 2109 och RFC 2068. Det har sedan dess upptäckts att MSIE 3.0x inte följde de teckenregler som beskrivs i dessa specifikationer; många av dagens webbläsare och servrar har också lättat på tolkningsreglerna när det gäller hantering av cookies. Som ett resultat av detta använder den här modulen nu parsingregler som är lite mindre strikta än de en gång var.

Teckenuppsättningen, string.ascii_letters, string.digits och !#$%&'*+-.^_`|~: betecknar den uppsättning giltiga tecken som tillåts av denna modul i ett cookie-namn (som key).

Ändrad i version 3.3: Tillåtet ’:’ som giltigt tecken för cookie-namn.

Anteckning

Om en ogiltig cookie påträffas uppstår CookieError, så om dina cookie-data kommer från en webbläsare bör du alltid förbereda dig för ogiltiga data och fånga CookieError vid parsning.

exception http.cookies.CookieError

Undantaget misslyckas på grund av RFC 2109 invaliditet: felaktiga attribut, felaktig Set-Cookie header, etc.

class http.cookies.BaseCookie([input])

Denna klass är ett ordboksliknande objekt vars nycklar är strängar och vars värden är Morsel-instanser. Observera att när en nyckel sätts till ett värde konverteras värdet först till en Morsel som innehåller nyckeln och värdet.

Om input anges skickas den till metoden load().

class http.cookies.SimpleCookie([input])

Denna klass härstammar från BaseCookie och åsidosätter value_decode() och value_encode(). SimpleCookie stöder strängar som cookie-värden. När värdet ställs in anropar SimpleCookie den inbyggda str() för att konvertera värdet till en sträng. Värden som tas emot från HTTP behålls som strängar.

Se även

Modul http.cookiejar

Hantering av HTTP-cookies för webbklienter. Modulerna http.cookiejar och http.cookies är inte beroende av varandra.

RFC 2109 - HTTP:s mekanism för tillståndshantering

Detta är den specifikation för tillståndshantering som implementeras av denna modul.

Morselobjekt

class http.cookies.Morsel

Abstract ett nyckel/värde-par, som har vissa RFC 2109 attribut.

Morsels är ordboksliknande objekt, vars uppsättning nycklar är konstant — de giltiga RFC 2109-attributen, som är:

expires
path
comment
domain
max-age
secure
version
httponly
samesite
partitioned

Attributet httponly anger att cookien endast överförs i HTTP-förfrågningar och inte är tillgänglig via JavaScript. Detta är avsett att mildra vissa former av cross-site scripting.

Attributet samesite styr när webbläsaren skickar cookien med cross-site-förfrågningar. Detta bidrar till att mildra CSRF-attacker. Giltiga värden är ”Strict” (skickas endast med förfrågningar på samma webbplats), ”Lax” (skickas med förfrågningar på samma webbplats och navigering på toppnivå) och ”None” (skickas med förfrågningar på samma webbplats och mellan olika webbplatser). När ”None” används måste även attributet ”secure” anges, vilket krävs av moderna webbläsare.

Attributet partitioned anger för användaragenter att dessa cross-site cookies bör endast vara tillgängliga i samma sammanhang på högsta nivå som cookien först sattes i. För att detta ska accepteras av användaragenten måste du även ange Secure.

Dessutom rekommenderas det att använda prefixet __Host när du ställer in partitionerade cookies för att göra dem bundna till värdnamnet och inte den registrerbara domänen. Läs CHIPS (Cookies Having Independent Partitioned State) för fullständiga detaljer och exempel.

Nycklarna är skiftlägesokänsliga och deras standardvärde är ''.

Ändrad i version 3.5: __eq__() tar nu hänsyn till key och value.

Ändrad i version 3.7: Attributen key, value och coded_value är skrivskyddade. Använd set() för att ställa in dem.

Ändrad i version 3.8: Lagt till stöd för attributet samesite.

Ändrad i version 3.14: Lagt till stöd för attributet partitioned.

Morsel.value

Värdet på cookien.

Morsel.coded_value

Det kodade värdet av cookien — det är detta som ska skickas.

Morsel.key

Namnet på cookien.

Morsel.set(key, value, coded_value)

Ange attributen key, value och coded_value.

Morsel.isReservedKey(K)

Om K ingår i uppsättningen nycklar i en Morsel.

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

Returnerar en strängrepresentation av Morsel, lämplig att skicka som en HTTP-header. Som standard ingår alla attribut, såvida inte attrs anges, i vilket fall det ska vara en lista över attribut som ska användas. header är som standard "Set-Cookie:".

Morsel.js_output(attrs=None)

Returnerar en inbäddningsbar JavaScript-snutt som, om den körs i en webbläsare som stöder JavaScript, kommer att fungera på samma sätt som om HTTP-headern skickades.

Betydelsen för attrs är densamma som i output().

Morsel.OutputString(attrs=None)

Returnera en sträng som representerar Morsel, utan någon omgivande HTTP eller JavaScript.

Betydelsen för attrs är densamma som i output().

Morsel.update(values)

Uppdatera värdena i Morsel-ordlistan med värdena i ordlistan values. Utlös ett fel om någon av nycklarna i values inte är ett giltigt RFC 2109-attribut.

Ändrad i version 3.5: ett fel uppstår om nyckeln är ogiltig.

Morsel.copy(value)

Returnerar en ytlig kopia av Morsel-objektet.

Ändrad i version 3.5: returnera ett Morsel-objekt istället för en dict.

Morsel.setdefault(key, value=None)

Utlöser ett fel om key inte är ett giltigt RFC 2109-attribut, annars samma beteende som dict.setdefault().

Exempel

I följande exempel visas hur du använder modulen http.cookies.

>>> from http import cookies
>>> C = cookies.SimpleCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print(C) # generate HTTP headers
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> print(C.output()) # same thing
Set-Cookie: fig=newton
Set-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=ahoy
Set-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=7
Set-Cookie: string=seven