http.cookies — HTTP 狀態管理

原始碼： Lib/http/cookies.py

---

http.cookies 模組定義了多個類，用於對 cookie 這一 HTTP 狀態管理機制進行抽象。它支援純字串 cookie，並提供了一種抽象，允許將任何可序列化的資料型別用作 cookie 值。

該模組最初嚴格遵循 RFC 2109 和 RFC 2068 規範中描述的解析規則。後來發現 MSIE 3.0x 並未遵循這些規範中列出的字元規則；如今許多瀏覽器和伺服器在處理 cookie 時也放寬了解析規則。因此，該模組現在使用的解析規則比以前稍寬鬆一些。

字元集 string.ascii_letters、string.digits 和 !#$%&'*+-.^_`|~: 表示本模組允許在 cookie 名稱（作為 key）中使用的有效字元集合。

在 3.3 版更改: 允許 ':' 作為有效的 cookie 名稱字元。

備註

遇到無效 cookie 時，會引發 CookieError，所以如果你的 cookie 資料來自瀏覽器，應始終做好應對無效資料的準備，並在解析時捕獲 CookieError。

exception http.cookies.CookieError

因違反 RFC 2109 而失敗時引發的異常：例如屬性不正確、Set-Cookie 標頭不正確等。

class http.cookies.BaseCookie([input])

此類是一個類似字典的物件，其鍵是字串，值是 Morsel 例項。請注意，在為鍵設定值時，值會首先被轉換為一個包含該鍵和值的 Morsel。

如果提供了 input，它將被傳遞給 load() 方法。

class http.cookies.SimpleCookie([input])

該類派生自 BaseCookie 並重寫了 value_decode() 和 value_encode()。SimpleCookie 支援將字串作為 cookie 值。設定值時，SimpleCookie 會呼叫內建的 str() 將值轉換為字串。從 HTTP 接收到的值將保持為字串。

參見

http.cookiejar 模組

用於 Web 客戶端 的 HTTP cookie 處理。http.cookiejar 和 http.cookies 模組彼此獨立。

RFC 2109 - HTTP State Management Mechanism

這是本模組所實現的狀態管理規範。

Cookie 物件

BaseCookie.value_decode(val)

從字串表示形式返回一個元組 (real_value, coded_value)。real_value 可以是任何型別。此方法在 BaseCookie 中不執行任何解碼操作——它的存在是為了被重寫。

BaseCookie.value_encode(val)

返回一個元組 (real_value, coded_value)。val 可以是任何型別，但 coded_value 將始終被轉換為字串。此方法在 BaseCookie 中不執行任何編碼操作——它的存在是為了被重寫。

通常情況下，在 value_decode 的值域上，value_encode() 和 value_decode() 應該是互逆的。

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

返回一個適合作為 HTTP 標頭髮送的字串表示形式。attrs 和 header 會被髮送到每個 Morsel 的 output() 方法。sep 用於連線各個標頭，預設為 '\r\n' (CRLF) 組合。

BaseCookie.js_output(attrs=None)

返回一個可嵌入的 JavaScript 程式碼片段，如果在支援 JavaScript 的瀏覽器上執行，其效果與傳送 HTTP 標頭相同。

attrs 的含義與在 output() 中的含義相同。

BaseCookie.load(rawdata)

如果 rawdata 是一個字串，則將其作為 HTTP_COOKIE 解析，並將找到的值作為 Morsel 新增進去。如果它是一個字典，則等同於

for k, v in rawdata.items():
    cookie[k] = v

Morsel 物件

class http.cookies.Morsel

抽象了一個鍵/值對，它具有一些 RFC 2109 屬性。

Morsel 是類似字典的物件，其鍵集是固定的——即有效的 RFC 2109 屬性，它們是

expires

path

comment

domain

max-age

secure

version

httponly

samesite

partitioned

httponly 屬性指定 cookie 僅在 HTTP 請求中傳輸，並且不能透過 JavaScript 訪問。這旨在減輕某些形式的跨站指令碼攻擊。

samesite 屬性控制瀏覽器何時隨跨站請求傳送 cookie。這有助於緩解 CSRF 攻擊。有效值為 "Strict"（僅隨同站請求傳送）、"Lax"（隨同站請求和頂級導航傳送）和 "None"（隨同站和跨站請求傳送）。使用 "None" 時，還必須設定 "secure" 屬性，這是現代瀏覽器的要求。

partitioned 屬性向使用者代理表明，這些跨站 cookie 應該只在首次設定 cookie 的同一頂級上下文中可用。為了讓使用者代理接受此設定，你必須同時設定 Secure。

此外，建議在設定分割槽 cookie 時使用 __Host 字首，使其繫結到主機名而不是可註冊域。請閱讀 CHIPS (Cookies Having Independent Partitioned State) 以獲取完整細節和示例。

鍵名不區分大小寫，其預設值為 ''。

在 3.5 版更改: __eq__() 現在會考慮 key 和 value。

在 3.7 版更改: 屬性 key、value 和 coded_value 是隻讀的。請使用 set() 來設定它們。

在 3.8 版更改: 添加了對 samesite 屬性的支援。

在 3.14 版更改: 添加了對 partitioned 屬性的支援。

Morsel.value

cookie 的值。

Morsel.coded_value

cookie 的編碼值——這是應該被髮送的內容。

Morsel.key

cookie 的名稱。

Morsel.set(key, value, coded_value)

設定 key、value 和 coded_value 屬性。

Morsel.isReservedKey(K)

K 是否為 Morsel 鍵集合中的成員。

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

返回 Morsel 的字串表示形式，適合作為 HTTP 標頭髮送。預設情況下，包含所有屬性，除非提供了 attrs，此時它應該是一個要使用的屬性列表。header 預設為 "Set-Cookie:"。

Morsel.js_output(attrs=None)

返回一個可嵌入的 JavaScript 程式碼片段，如果在支援 JavaScript 的瀏覽器上執行，其效果與傳送 HTTP 標頭相同。

attrs 的含義與在 output() 中的含義相同。

Morsel.OutputString(attrs=None)

返回表示 Morsel 的字串，不帶任何周圍的 HTTP 或 JavaScript 程式碼。

attrs 的含義與在 output() 中的含義相同。

Morsel.update(values)

使用字典 values 中的值更新 Morsel 字典中的值。如果 values 字典中的任何鍵不是有效的 RFC 2109 屬性，則引發錯誤。

在 3.5 版更改: 對無效鍵會引發錯誤。

Morsel.copy(value)

返回 Morsel 物件的淺複製。

在 3.5 版更改: 返回一個 Morsel 物件而不是一個字典。

Morsel.setdefault(key, value=None)

如果 key 不是有效的 RFC 2109 屬性，則引發錯誤，否則其行為與 dict.setdefault() 相同。

示例

以下示例演示瞭如何使用 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