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()、