http.cookies — HTTP State Management

Quellcode: Lib/http/cookies.py

Das Modul http.cookies definiert Klassen zur Abstraktion des Konzepts von Cookies, einem Mechanismus zur Verwaltung des HTTP-Status. Es unterstützt sowohl einfache Cookies, die nur aus Strings bestehen, als auch eine Abstraktion für beliebige serialisierbare Datentypen als Cookie-Wert.

Das Modul wendete früher strikt die Parsing-Regeln an, die in den RFC 2109 und RFC 2068 Spezifikationen beschrieben sind. Es wurde inzwischen entdeckt, dass MSIE 3.0x die in diesen Spezifikationen genannten Zeichenregeln nicht befolgte; viele aktuelle Browser und Server haben die Parsing-Regeln im Umgang mit Cookies ebenfalls gelockert. Infolgedessen verwendet dieses Modul jetzt Parsing-Regeln, die etwas weniger streng sind als früher.

Der Zeichensatz, string.ascii_letters, string.digits und !#$%&'*+-.^_`|~: bezeichnen die Menge der gültigen Zeichen, die dieses Modul in einem Cookie-Namen (als key) zulässt.

Geändert in Version 3.3: ‘:’ als gültiges Cookie-Namenszeichen zugelassen.

Hinweis

Beim Auftreten eines ungültigen Cookies wird CookieError ausgelöst. Wenn Ihre Cookie-Daten von einem Browser stammen, sollten Sie daher immer auf ungültige Daten vorbereitet sein und CookieError beim Parsen abfangen.

Ausnahme http.cookies.CookieError

Ausnahme, die aufgrund von RFC 2109-Ungültigkeit fehlschlägt: falsche Attribute, falscher Set-Cookie Header usw.

Klasse http.cookies.BaseCookie([input])

Diese Klasse ist ein wörterbuchähnliches Objekt, dessen Schlüssel Strings und dessen Werte Morsel-Instanzen sind. Beachten Sie, dass beim Zuweisen eines Schlüssels zu einem Wert dieser zuerst in ein Morsel konvertiert wird, das den Schlüssel und den Wert enthält.

Wenn input angegeben ist, wird es an die Methode load() übergeben.

Klasse http.cookies.SimpleCookie([input])

Diese Klasse leitet sich von BaseCookie ab und überschreibt value_decode() und value_encode(). SimpleCookie unterstützt Strings als Cookie-Werte. Beim Setzen des Wertes ruft SimpleCookie die eingebaute Funktion str() auf, um den Wert in einen String zu konvertieren. Von HTTP empfangene Werte werden als Strings beibehalten.

Siehe auch

Modul http.cookiejar

HTTP-Cookie-Handling für Web-Clients. Die Module http.cookiejar und http.cookies hängen nicht voneinander ab.

RFC 2109 - HTTP State Management Mechanism

Dies ist die Zustandsverwaltungspezifikation, die von diesem Modul implementiert wird.

Morsel-Objekte

Klasse http.cookies.Morsel

Abstrahiert ein Schlüssel/Wert-Paar, das einige RFC 2109-Attribute hat.

Morsels sind wörterbuchähnliche Objekte, deren Schlüsselmenge konstant ist – die gültigen RFC 2109-Attribute, die sind

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

Das Attribut httponly gibt an, dass das Cookie nur in HTTP-Anfragen übertragen wird und nicht über JavaScript zugänglich ist. Dies soll einige Formen von Cross-Site Scripting abmildern.

Das Attribut samesite steuert, wann der Browser das Cookie bei Cross-Site-Anfragen sendet. Dies hilft bei der Abmilderung von CSRF-Angriffen. Gültige Werte sind „Strict“ (nur bei Same-Site-Anfragen gesendet), „Lax“ (bei Same-Site-Anfragen und Top-Level-Navigationen gesendet) und „None“ (bei Same-Site- und Cross-Site-Anfragen gesendet). Bei Verwendung von „None“ muss auch das Attribut „secure“ gesetzt sein, wie es von modernen Browsern gefordert wird.

Das Attribut partitioned zeigt den User Agents an, dass diese Cross-Site-Cookies nur im selben Top-Level-Kontext verfügbar sein *sollen*, in dem das Cookie ursprünglich gesetzt wurde. Damit dies vom User Agent akzeptiert wird, **müssen** Sie auch Secure setzen.

Zusätzlich wird empfohlen, das Präfix __Host zu verwenden, wenn partitionierte Cookies gesetzt werden, um sie an den Hostnamen und nicht an die registrierbare Domain zu binden. Lesen Sie CHIPS (Cookies Having Independent Partitioned State) für vollständige Details und Beispiele.

Die Schlüssel sind nicht case-sensitiv und ihr Standardwert ist ''.

Geändert in Version 3.5: __eq__() berücksichtigt jetzt key und value.

Geändert in Version 3.7: Attribute key, value und coded_value sind schreibgeschützt. Verwenden Sie set(), um sie zu setzen.

Geändert in Version 3.8: Unterstützung für das Attribut samesite hinzugefügt.

Geändert in Version 3.14: Unterstützung für das Attribut partitioned hinzugefügt.

Morsel.value

Der Wert des Cookies.

Morsel.coded_value

Der kodierte Wert des Cookies – dies ist, was gesendet werden sollte.

Morsel.key

Der Name des Cookies.

Morsel.set(key, value, coded_value)

Setzt die Attribute key, value und coded_value.

Morsel.isReservedKey(K)

Ob K ein Element der Schlüsselmenge eines Morsel ist.

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

Gibt eine String-Darstellung des Morsels zurück, die zum Senden als HTTP-Header geeignet ist. Standardmäßig sind alle Attribute enthalten, es sei denn, attrs wird angegeben, in diesem Fall sollte es eine Liste von zu verwendenden Attributen sein. header ist standardmäßig "Set-Cookie:".

Morsel.js_output(attrs=None)

Gibt einen einbettbaren JavaScript-Snippet zurück, der, wenn er in einem Browser ausgeführt wird, der JavaScript unterstützt, dasselbe bewirkt, als ob der HTTP-Header gesendet worden wäre.

Die Bedeutung von attrs ist dieselbe wie in output().

Morsel.OutputString(attrs=None)

Gibt einen String zurück, der den Morsel darstellt, ohne umgebende HTTP- oder JavaScript-Elemente.

Die Bedeutung von attrs ist dieselbe wie in output().

Morsel.update(values)

Aktualisiert die Werte im Morsel-Wörterbuch mit den Werten aus dem Wörterbuch values. Löst einen Fehler aus, wenn einer der Schlüssel im values-Wörterbuch kein gültiges RFC 2109-Attribut ist.

Geändert in Version 3.5: ein Fehler wird für ungültige Schlüssel ausgelöst.

Morsel.copy(value)

Gibt eine flache Kopie des Morsel-Objekts zurück.

Geändert in Version 3.5: gibt ein Morsel-Objekt anstelle eines Wörterbuchs zurück.

Morsel.setdefault(key, value=None)

Löst einen Fehler aus, wenn key kein gültiges RFC 2109-Attribut ist, andernfalls verhält es sich wie dict.setdefault().

Beispiel

Das folgende Beispiel zeigt die Verwendung des Moduls 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