http.cookiejar --- HTTP 用戶端的 Cookie 處理

原始碼：Lib/http/cookiejar.py

http.cookiejar 模組定義了自動處理 HTTP cookie 的類別。當需要存取小量資料 —— cookies —— 的網站時會非常有用。這些資料會依據網頁伺服器的 HTTP 回應來設置於用戶端機器，並在之後的請求中被回傳到伺服器。

一般的 Netscape cookie 協定和 RFC 2965 定義的 cookie 協定都會被處理。RFC 2965 的處理預設是關閉的。RFC 2109 cookie 會被剖析為 Netscape cookie，然後根據有生效的「策略」來被看作為 Netscape 或 RFC 2965 cookie。http.cookiejar 會嘗試遵循實際上的 Netscape cookie 協定（與原始的 Netscape 規格中的協定有很大的不同），包括 RFC 2965 所引進的 max-age 和 port cookie 屬性。

備註

在 Set-Cookie 和 Set-Cookie2 標頭中出現的各種命名參數（例如 domain 和 expires）通常被稱為 attributes。為了與 Python 的屬性分別開，這個模組的說明檔案改用 cookie-attribute 來稱呼。

模組定義了以下例外：

exception http.cookiejar.LoadError

當從檔案載入 cookies 失敗時，FileCookieJar 的實例會引發這個例外。LoadError 是 OSError 的子類別。

在 3.3 版的變更: LoadError 以前是 IOError 的子型別，現在是 OSError 的別名。

這個模組提供了以下類別：

class http.cookiejar.CookieJar(policy=None)

policy 是實作了 CookiePolicy 介面的一個物件。

CookieJar 類別會儲存 HTTP cookies。它會從 HTTP 請求中抽取出 cookies，並在 HTTP 回應中將它們回傳。CookieJar 實例會在必要時自動使包含的 cookies 過期。它的子類別也負責從檔案或資料庫中儲存和擷取 cookies。

class http.cookiejar.FileCookieJar(filename=None, delayload=None, policy=None)

policy 是實作了 CookiePolicy 介面的一個物件。至於其他引數，請參閱對應屬性的說明文件。

一個可以從磁碟上的檔案載入 Cookie，也可以儲存 Cookie 到磁碟上檔案的 CookieJar。在 load() 或 revert() 方法被呼叫之前，Cookie 並不會從指定的檔案載入。這個類別的子類別有記載於 FileCookieJar 子類別及與網頁瀏覽器的合作 章節。

這個類別不應該直接初始化 - 請使用下面的子類別代替。

在 3.8 版的變更: filename 參數支援傳入一個 path-like object。

class http.cookiejar.CookiePolicy

此類別負責決定是否應從伺服器接受 / 回傳每個 cookie。

class http.cookiejar.DefaultCookiePolicy(blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False, secure_protocols=('https', 'wss'))

建構函式引數只能以關鍵字引數的形式傳送。blocked_domains 是我們從不接受 cookies 或回傳 cookies 的網域名稱序列。allowed_domains 如果不是 None，這是我們接受並回傳 cookies 的唯一網域名稱序列。 secure_protocols 是可以加入安全 cookies 的通訊協定序列。預設情況下，https 和 wss（安全 websocket）會被視為安全通訊協定。所有其他引數請參閱 CookiePolicy 及 DefaultCookiePolicy 物件的說明文件。

DefaultCookiePolicy 實作了 Netscape 和 RFC 2965 cookies 的標準接受/拒絕規則。預設情況下，RFC 2109 cookies（即在 Set-Cookie 標頭中接收到的版本 cookie-attribute 為 1 的 cookies）會根據 RFC 2965 規則處理。 但是，如果 RFC 2965 處理被關閉，或者 rfc2109_as_netscape 是 True，RFC 2109 cookie 會被 CookieJar 實例「降級 」為 Netscape cookie，方法是將 Cookie 實例的 version 屬性設為 0。DefaultCookiePolicy 也提供了一些參數來允許對策略進行一些微調。

class http.cookiejar.Cookie

這個類別代表 Netscape、RFC 2109 和 RFC 2965 cookies。 我們不希望 http.cookiejar 的使用者建立自己的 Cookie 實例。 如有必要，請在 CookieJar 實例上呼叫 make_cookies()。

也參考

urllib.request 模組

URL 打開時會自動處理 cookie。

http.cookies 模組

HTTP cookie 類別，主要用於伺服器端程式碼。 http.cookiejar 和 http.cookies 模組不互相依賴。

https://curl.se/rfc/cookie_spec.html

原始 Netscape cookie 協定的規範。雖然這仍是主流協定，但所有主要瀏覽器（以及 http.cookiejar）實作的「Netscape cookie 協定」與 cookie_spec.html 中實作的協定只有一點相似之處。

RFC 2109 - HTTP 狀態管理機制

被 RFC 2965 所取代，會使用 Set-Cookie 設定 version=1。

RFC 2965 - HTTP 狀態管理機制

有錯誤修正的 Netscape 通訊協定。使用 Set-Cookie2 取代 Set-Cookie。未被廣泛使用。

https://kristol.org/cookie/errata.html

未完成的 RFC 2965 勘誤表。

RFC 2964 - HTTP 狀態管理使用方法

CookieJar 與 FileCookieJar 物件

CookieJar 物件支援 iterator 協定來遍歷包含的 Cookie 物件。

CookieJar 擁有以下方法：

將正確的 Cookie 標頭加入 request。

如果策略允許（即 CookieJar 的 CookiePolicy 實例的 rfc2965 和 hide_cookie2 屬性分別為 true 和 false），Cookie2 標頭也會在適當的時候加入。

如 urllib.request 文件所述，request 物件（通常是 urllib.request.Request 的實例）必須支援 get_full_url()、has_header()、get_header()、header_items()、add_unredirected_header() 方法與 host、type、unverifiable、origin_req_host 屬性。

在 3.3 版的變更: request 物件需要 origin_req_host 屬性。已移除對已廢棄方法 get_origin_req_host() 的依賴。

CookieJar.extract_cookies(response, request)

在策略允許的情況下，從 HTTP response 抽取出 cookies 並儲存到 CookieJar 中。

CookieJar 會在 response 引數中尋找允許的 Set-Cookie 和 Set-Cookie2 標頭，並視情況儲存 cookies（需經 CookiePolicy.set_ok() 方法的檢測）。

response 物件（通常是呼叫 urllib.request.urlopen() 的結果或類似的東西）應該支援 info() 方法，它會回傳一個 email.message.Message 的實例。

如 urllib.request 的檔案所說，request 物件（通常是 urllib.request.Request 的實例）必須支援 get_full_url() 方法以及 host、unverifiable 和 origin_req_host 等屬性，該請求被用於設置 cookie-attributes 的預設值並檢查 cookie 是否允許被設置。

在 3.3 版的變更: request 物件需要 origin_req_host 屬性。已移除對已廢棄方法 get_origin_req_host() 的依賴。

CookieJar.set_policy(policy)

設定要使用的 CookiePolicy 實例。

CookieJar.make_cookies(response, request)

回傳從 response 物件抽取出的 Cookie 物件序列。

有關 response 和 request 引數所需的介面，請參閱 extract_cookies() 的說明檔案。

如果策略允許這麼做，設定 Cookie。

設定一個 Cookie，不經過策略檢查。

CookieJar.clear([domain[, path[, name]]])

清除一些 cookies。

如果不帶引數地叫用，則清除所有 cookies。如果給定單一引數，則只移除屬於該 domain 的 cookies。如果給定兩個引數，則會移除屬於指定 domain 和 URL path 的 cookie。 如果給定三個引數，則會移除指定 domain、path 和 name 的 cookie。

如果沒有符合的 cookie 存在，則引發 KeyError。

CookieJar.clear_session_cookies()

刪除所有 session cookies。

刪除所有包含有 true discard 屬性的 cookie (通常是因為它們沒有 max-age 或 expires cookie 屬性，或有明確的 discard cookie 屬性)。 對於互動式瀏覽器，工作階段的結束通常對應於關閉瀏覽器視窗。

請注意 save() 方法無論如何都不會儲存 session cookies，除非你透過傳入 true ignore_discard 引數來要求。

FileCookieJar 實例有下列附加方法：

FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False)

將 cookies 儲存到檔案中。

這個基底類別會產生 NotImplementedError。子類別可以不實作此方法。

filename 是儲存 cookies 的檔案名稱。 如果 filename 未指定，則會使用 self.filename (其預設值是傳給建構函式的值（如果有）)；如果 self.filename 是 None，則會產生 ValueError。

ignore_discard: 即使設定為捨棄的 cookies 也會儲存。ignore_expires: 保存過期的 cookie

如果檔案已經存在，則會被覆寫，因此會抹除其中包含的所有 cookies。 儲存的 cookies 可以稍後使用 load() 或 revert() 方法還原。

FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)

從檔案中載入 cookies。

舊的 cookies 會被保留，除非被新載入的 cookies 覆蓋。

引數與 save() 相同。

被命名的檔案必須是類別所能正確剖析的格式，否則會產生 LoadError。此外，OSError 可能會被引發，例如檔案不存在時。

在 3.3 版的變更: 以前會引發 IOError，現在它是 OSError 的別名。

FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)

清除所有 cookies， 並從儲存的檔案重新載入 cookies。

revert() 可以產生與 load() 相同的例外。如果失敗，物件的狀態不會被改變。

FileCookieJar 實例擁有以下公開屬性：

FileCookieJar.filename

保存 cookie 的預設檔案的檔案名稱。 此屬性可以被指定。

FileCookieJar.delayload

若為 true，則從硬盤惰性地載入 cookies。 此屬性不應被指定。 這只是一個提示，因為這只會影響效能，不會影響行為 (除非磁碟上的 cookies 正在改變)。一個 CookieJar 物件可以忽略它。 沒有一個包含在標準函式庫中的 FileCookieJar 類別會惰性地載入 cookies。

FileCookieJar 子類別及與網頁瀏覽器的合作

以下 CookieJar 子類別提供用於讀取和寫入。

class http.cookiejar.MozillaCookieJar(filename=None, delayload=None, policy=None)

一個能夠以 Mozilla cookies.txt 檔案格式（該格式也被 curl 和 Lynx 以及 Netscape 瀏覽器所使用）從磁碟載入和儲存 cookie 的