http.cookiejar —— HTTP 客戶端的 Cookie 處理?

CookieJar 和 FileCookieJar 對(duì)象?

CookieJar 對(duì)象支持 iterator 協(xié)議，用于迭代包含的 Cookie 對(duì)象。

CookieJar 有以下方法：

CookieJar.add_cookie_header(request)?

在 request 中添加正確的 Cookie 頭。

如果策略允許（即 rfc2965 和 hide_cookie2 屬性在 CookieJar 的 CookiePolicy 實(shí)例中分別為 True 和 False ）， Cookie2 標(biāo)頭也會(huì)在適當(dāng)時(shí)候添加。

如 urllib.request 所記載的， request 對(duì)象（通常是一個(gè) urllib.request.Request 實(shí)例）必須支持 get_full_url() , get_host(), get_type(), unverifiable(), has_header(), get_header(), header_items(), add_unredirected_header() 和 origin_req_host 屬性。

在 3.3 版更改: request 對(duì)象需要 origin_req_host 屬性。對(duì)已廢棄的方法 get_origin_req_host() 的依賴已被移除。

CookieJar.extract_cookies(response, request)?

從HTTP response 中提取 cookie，并在政策允許的情況下，將它們存儲(chǔ)在 CookieJar 中。

CookieJar 將 在*response* 參數(shù)中尋找允許的 Set-Cookie 和 Set-Cookie2 頭信息，并適當(dāng)?shù)卮鎯?chǔ)cookies（須經(jīng) CookiePolicy.set_ok() 方法批準(zhǔn)）。

response 對(duì)象（通常是調(diào)用 urllib.request.urlopen() 或類似方法的結(jié)果）應(yīng)該支持 info() 方法，它返回 email.message.Message 實(shí)例。

如 urllib.request 的文檔所說，request 對(duì)象（通常是一個(gè) urllib.request.Request 實(shí)例）必須支持 get_full_url(), get_host(), unverifiable() 和 origin_req_host 屬性。 該請(qǐng)求用于設(shè)置 cookie-attributes 的默認(rèn)值，以及檢查 cookie 是否允許被設(shè)置。

在 3.3 版更改: request 對(duì)象需要 origin_req_host 屬性。對(duì)已廢棄的方法 get_origin_req_host() 的依賴已被移除。

CookieJar.set_policy(policy)?

設(shè)置要使用的 CookiePolicy 實(shí)例。

CookieJar.make_cookies(response, request)?

返回從 response 對(duì)象中提取的 Cookie 對(duì)象的序列。

關(guān)于 response 和 request 參數(shù)所需的接口，請(qǐng)參見 extract_cookies() 的文檔。

CookieJar.set_cookie_if_ok(cookie, request)?

如果策略規(guī)定可以這樣做，就設(shè)置一個(gè) Cookie 。

CookieJar.set_cookie(cookie)?

設(shè)置一個(gè) Cookie，不需要檢查策略是否應(yīng)該被設(shè)置。

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

清除一些cookie。

如果調(diào)用時(shí)沒有參數(shù)，則清除所有的cookie。 如果給定一個(gè)參數(shù)，只有屬于該 domain 的cookies將被刪除。如果給定兩個(gè)參數(shù)，那么屬于指定的 domain 和 URL path 的cookie將被刪除。 如果給定三個(gè)參數(shù)，那么屬于指定的 domain 、path 和 name 的cookie將被刪除

如果不存在匹配的 cookie，則會(huì)引發(fā) KeyError。

CookieJar.clear_session_cookies()?

丟棄所有的會(huì)話 cookie。

丟棄所有 discard 屬性為真值的已包含 cookie（通常是因?yàn)樗鼈儧]有 max-age 或 expires cookie 屬性，或者顯式的 discard cookie 屬性）。 對(duì)于交互式瀏覽器，會(huì)話的結(jié)束通常對(duì)應(yīng)于關(guān)閉瀏覽器窗口。

請(qǐng)注意 save() 方法并不會(huì)保存會(huì)話的 cookie，除非你通過傳入一個(gè)真值給 ignore_discard 參數(shù)來提出明確的要求。

FileCookieJar 實(shí)現(xiàn)了下列附加方法:

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

將 cookie 保存到文件。

基類會(huì)引發(fā) NotImplementedError。 子類可以繼續(xù)不實(shí)現(xiàn)該方法。

filename 為要用來保存 cookie 的文件名稱。 如果未指定 filename，則會(huì)使用 self.filename (該屬性默認(rèn)為傳給構(gòu)造器的值，如果有傳入的話)；如果 self.filename 為 None，則會(huì)引發(fā) ValueError。

ignore_discard: 即使設(shè)定了丟棄 cookie 仍然保存它們。 ignore_expires: 即使 cookie 已超期仍然保存它們

文件如果已存在則會(huì)被覆蓋，這將清除其所包含的全部 cookie。 已保存的 cookie 可以使用 load() 或 revert() 方法來恢復(fù)。

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

從文件加載 cookie。

舊的 cookie 將被保留，除非是被新加載的 cookie 所覆蓋。

其參數(shù)與 save() 的相同。

指定的文件必須為該類所能理解的格式，否則將引發(fā) LoadError。 也可能會(huì)引發(fā) OSError，例如當(dāng)文件不存在的時(shí)候。

在 3.3 版更改: 過去觸發(fā)的 IOError，現(xiàn)在是 OSError 的別名。

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

清除所有 cookie 并從保存的文件重新加載 cookie。

revert() 可以引發(fā)與 load() 相同的異常。 如果執(zhí)行失敗，對(duì)象的狀態(tài)將不會(huì)被改變。

FileCookieJar 實(shí)例具有下列公有屬性:

FileCookieJar.filename?

默認(rèn)的保存 cookie 的文件的文件名。 該屬性可以被賦值。

FileCookieJar.delayload?

如為真值，則惰性地從磁盤加載 cookie。 該屬性不應(yīng)當(dāng)被賦值。 這只是一個(gè)提示，因?yàn)樗粫?huì)影響性能，而不會(huì)影響行為（除非磁盤中的 cookie 被改變了）。 CookieJar 對(duì)象可能會(huì)忽略它。 任何包括在標(biāo)準(zhǔn)庫中的 FileCookieJar 類都不會(huì)惰性地加載 cookie。

FileCookieJar 的子類及其與 Web 瀏覽器的協(xié)同?

提供了以下 CookieJar 子類用于讀取和寫入。

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

一個(gè)能夠以 Mozilla cookies.txt 文件格式（該格式也被 Lynx 和 Netscape 瀏覽器所使用）從磁盤加載和存儲(chǔ) cookie 的 FileCookieJar。

備注

這會(huì)丟失有關(guān) RFC 2965 cookie 的信息，以及有關(guān)較新或非標(biāo)準(zhǔn)的 cookie 屬性例如 port。

警告

在存儲(chǔ)之前備份你的 cookie，如果你的 cookie 丟失/損壞會(huì)造成麻煩的話（有一些微妙的因素可能導(dǎo)致文件在加載/保存的往返過程中發(fā)生細(xì)微的變化）。

還要注意在 Mozilla 運(yùn)行期間保存的 cookie 將可能被 Mozilla 清除。

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

一個(gè)能夠以 libwww-perl 庫的 Set-Cookie3 文件格式從磁盤加載和存儲(chǔ) cookie 的 FileCookieJar。 這適用于當(dāng)你想以人類可讀的文件來保存 cookie 的情況。

在 3.8 版更改: 文件名形參支持 path-like object。

CookiePolicy 對(duì)象?

實(shí)現(xiàn)了 CookiePolicy 接口的對(duì)象具有下列方法:

CookiePolicy.set_ok(cookie, request)?

返回指明是否應(yīng)當(dāng)從服務(wù)器接受 cookie 的布爾值。

cookie 是一個(gè) Cookie 實(shí)例。 request 是一個(gè)實(shí)現(xiàn)了由 CookieJar.extract_cookies() 的文檔所定義的接口的對(duì)象。

CookiePolicy.return_ok(cookie, request)?

返回指明是否應(yīng)當(dāng)將 cookie 返回給服務(wù)器的布爾值。

cookie 是一個(gè) Cookie 實(shí)例。 request 是一個(gè)實(shí)現(xiàn)了 CookieJar.add_cookie_header() 的文檔所定義的接口的對(duì)象。

CookiePolicy.domain_return_ok(domain, request)?

對(duì)于給定的 cookie 域如果不應(yīng)當(dāng)返回 cookie 則返回 False。

此方法是一種優(yōu)化操作。 它消除了檢查每個(gè)具有特定域的 cookie 的必要性（這可能會(huì)涉及讀取許多文件）。 從 domain_return_ok() 和 path_return_ok() 返回真值并將所有工作留給 return_ok()。

如果 domain_return_ok() 為 cookie 域返回真值，則會(huì)為 cookie 路徑調(diào)用 path_return_ok()。 在其他情況下，則不會(huì)為該 cookie 域調(diào)用 path_return_ok() 和 return_ok()。 如果 path_return_ok() 返回真值，則會(huì)調(diào)用 return_ok() 并附帶 Cookie 對(duì)象本身以進(jìn)行全面檢查。 在其他情況下，都永遠(yuǎn)不會(huì)為該 cookie 路徑調(diào)用 return_ok()。

請(qǐng)注意 domain_return_ok() 會(huì)針對(duì)每個(gè) cookie 域被調(diào)用，而非只針對(duì) request 域。 例如，該函數(shù)會(huì)針對(duì) ".example.com" 和 "www.example.com" 被調(diào)用，如果 request 域?yàn)?"www.example.com" 的話。 對(duì)于 path_return_ok() 也是如此。

request 參數(shù)與 return_ok() 的文檔所說明的一致。

CookiePolicy.path_return_ok(path, request)?

對(duì)于給定的 cookie 路徑如果不應(yīng)當(dāng)返回 cookie 返回 False。

請(qǐng)參閱 domain_return_ok() 的文檔。

除了實(shí)現(xiàn)上述方法，CookiePolicy 接口的實(shí)現(xiàn)還必須提供下列屬性，指明應(yīng)當(dāng)使用哪種協(xié)議以及如何使用。 所有這些屬性都可以被賦值。

CookiePolicy.netscape?

實(shí)現(xiàn) Netscape 協(xié)議。

CookiePolicy.rfc2965?

實(shí)現(xiàn) RFC 2965 協(xié)議。

CookiePolicy.hide_cookie2?

不要向請(qǐng)求添加 Cookie2 標(biāo)頭（此標(biāo)頭是提示服務(wù)器請(qǐng)求方能識(shí)別 RFC 2965 cookie）。

定義 CookiePolicy 類的最適用方式是通過子類化 DefaultCookiePolicy 并重載部分或全部上述的方法。 CookiePolicy 本身可被用作 '空策略' 以允許設(shè)置和接收所有的 cookie（但這沒有什么用處）。

DefaultCookiePolicy 對(duì)象?

實(shí)現(xiàn)接收和返回 cookie 的標(biāo)準(zhǔn)規(guī)則。

RFC 2965 和 Netscape cookie 均被涵蓋。 RFC 2965 處理默認(rèn)關(guān)閉。

提供自定義策略的最容易方式是重載此類并在你重載的實(shí)現(xiàn)中添加你自己的額外檢查之前調(diào)用其方法:

import http.cookiejar
class MyCookiePolicy(http.cookiejar.DefaultCookiePolicy):
    def set_ok(self, cookie, request):
        if not http.cookiejar.DefaultCookiePolicy.set_ok(self, cookie, request):
            return False
        if i_dont_want_to_store_this_cookie(cookie):
            return False
        return True

在實(shí)現(xiàn) CookiePolicy 接口所要求的特性之外，該類還允許你阻止和允許特定的域設(shè)置和接收 cookie。 還有一些嚴(yán)格性開關(guān)允許你將相當(dāng)寬松的 Netscape 協(xié)議規(guī)則收緊一點(diǎn)（代價(jià)是可能會(huì)阻止某些無害的 cookie）。

提供了域阻止名單和允許名單（默認(rèn)都是關(guān)閉的）。 只有不存在于阻止列表且存在于允許列表（如果允許名單被啟用）的域才能參與 cookie 的設(shè)置與返回。 請(qǐng)使用 blocked_domains 構(gòu)造器參數(shù)，以及 blocked_domains() 和 set_blocked_domains() 方法（以及and the corresponding argument and methods for allowed_domains 的相應(yīng)參數(shù)和方法）。 如果你設(shè)置了允許名單，你可以通過將其設(shè)為 None 來關(guān)閉它。

阻止名單或允許名單中不以點(diǎn)號(hào)開頭的域名必須與要匹配的 cookie 域完全相等。 例如， "example.com" 將匹配阻止名單條目 "example.com"，但不匹配 "www.example.com"。 以點(diǎn)號(hào)開頭的域名也能與更明確的域相匹配。 例如，"www.example.com" 和 "www.coyote.example.com" 將匹配 ".example.com" (但不匹配 "example.com" 本身)。 IP 地址不在此例，而是必須完全匹配。 例如，如果 blocked_domains 包含 "192.168.1.2" 和 ".168.1.2"，則會(huì)阻止 192.168.1.2，但不會(huì)阻止 193.168.1.2。

DefaultCookiePolicy 實(shí)現(xiàn)了下列附加方法:

DefaultCookiePolicy.blocked_domains()?

返回被阻止域的序列（元組類型）。

DefaultCookiePolicy.set_blocked_domains(blocked_domains)?

設(shè)置被阻止域的序列。

DefaultCookiePolicy.is_blocked(domain)?

Return True if domain is on the blocklist for setting or receiving cookies.

DefaultCookiePolicy.allowed_domains()?

返回 None，或者被允許域的序列（元組類型）。

DefaultCookiePolicy.set_allowed_domains(allowed_domains)?

設(shè)置被允許域的序列，或者為 None。

DefaultCookiePolicy.is_not_allowed(domain)?

Return True if domain is not on the allowlist for setting or receiving cookies.

DefaultCookiePolicy 實(shí)例具有下列屬性，它們都是基于同名的構(gòu)造器參數(shù)來初始化的，并且都可以被賦值。

DefaultCookiePolicy.rfc2109_as_netscape?

如為真值，則請(qǐng)求 CookieJar 實(shí)例將 RFC 2109 cookie (即在帶有 version 值為 1 的 cookie 屬性的 Set-Cookie 標(biāo)頭中接收到的 cookie) 降級(jí)為 Netscape cookie: 即將 Cookie 實(shí)例的 version 屬性設(shè)為 0。 默認(rèn)值為 None，在此情況下 RFC 2109 cookie 僅在s are downgraded if and only if RFC 2965 處理被關(guān)閉時(shí)才會(huì)被降級(jí)。 因此，RFC 2109 cookie 默認(rèn)會(huì)被降級(jí)。

通用嚴(yán)格性開關(guān):

DefaultCookiePolicy.strict_domain?

不允許網(wǎng)站設(shè)置帶國家碼頂級(jí)域的包含兩部分的域名例如 .co.uk, .gov.uk, .co.nz 等。 此開關(guān)尚未十分完善，并不保證有效！

RFC 2965 協(xié)議嚴(yán)格性開關(guān):

DefaultCookiePolicy.strict_rfc2965_unverifiable?

遵循針對(duì)不可驗(yàn)證事務(wù)的 RFC 2965 規(guī)則（不可驗(yàn)證事務(wù)通常是由重定向或請(qǐng)求發(fā)布在其它網(wǎng)站的圖片導(dǎo)致的）。 如果該屬性為假值，則 永遠(yuǎn)不會(huì) 基于可驗(yàn)證性而阻止 cookie。

Netscape 協(xié)議嚴(yán)格性開關(guān):

DefaultCookiePolicy.strict_ns_unverifiable?

即便是對(duì) Netscape cookie 也要應(yīng)用 RFC 2965 規(guī)則。

DefaultCookiePolicy.strict_ns_domain?

指明針對(duì) Netscape cookie 的域匹配規(guī)則的嚴(yán)格程度。 可接受的值見下文。

DefaultCookiePolicy.strict_ns_set_initial_dollar?

忽略 Set-Cookie 中的 cookie: 即名稱前綴為 '{TX-PL-LABEL}#x27; 的標(biāo)頭。

DefaultCookiePolicy.strict_ns_set_path?

不允許設(shè)置路徑與請(qǐng)求 URL 路徑不匹配的 cookie。

strict_ns_domain 是一組旗標(biāo)。 其值是通過或運(yùn)算來構(gòu)造的（例如，DomainStrictNoDots|DomainStrictNonDomain 表示同時(shí)設(shè)置兩個(gè)旗標(biāo)）。

DefaultCookiePolicy.DomainStrictNoDots?

當(dāng)設(shè)置 cookie 是，'host prefix' 不可包含點(diǎn)號(hào)（例如 www.foo.bar.com 不能為 .bar.com 設(shè)置 cookie，因?yàn)?www.foo 包含了一個(gè)點(diǎn)號(hào)）。

DefaultCookiePolicy.DomainStrictNonDomain?

沒有顯式指明Cookies that did not explicitly specify a domain cookie 屬性的 cookie 只能被返回給與設(shè)置 cookie 的域相同的域（例如 spam.example.com 不會(huì)是來自 example.com 的返回 cookie，如果該域名沒有 domain cookie 屬性的話）。

DefaultCookiePolicy.DomainRFC2965Match?

當(dāng)設(shè)置 cookie 時(shí)，要求完整的 RFC 2965 域匹配。

下列屬性是為方便使用而提供的，是上述旗標(biāo)的幾種最常用組合:

DefaultCookiePolicy.DomainLiberal?

等價(jià)于 0 (即所有上述 Netscape 域嚴(yán)格性旗標(biāo)均停用)。

DefaultCookiePolicy.DomainStrict?

等價(jià)于 DomainStrictNoDots|DomainStrictNonDomain。

Cookie 對(duì)象?

Cookie 實(shí)例具有與各種 cookie 標(biāo)準(zhǔn)中定義的標(biāo)準(zhǔn) cookie 屬性大致對(duì)應(yīng)的 Python 屬性。 這并非一一對(duì)應(yīng)，因?yàn)榇嬖趶?fù)雜的賦默認(rèn)值的規(guī)則，因?yàn)?max-age 和 expires cookie 屬性包含相同信息，也因?yàn)?RFC 2109 cookie 可以被 http.cookiejar 從第 1 版 '降級(jí)為' 第 0 版 (Netscape) cookie。

對(duì)這些屬性的賦值在 CookiePolicy 方法的極少數(shù)情況以外應(yīng)該都是不必要的。 該類不會(huì)強(qiáng)制內(nèi)部一致性，因此如果這樣做則你應(yīng)當(dāng)清楚自己在做什么。

Cookie.version?

整數(shù)或 None。 Netscape cookie 的 version 值為 0。 RFC 2965 和 RFC 2109 cookie 的 version cookie 屬性值為 1。 但是，請(qǐng)注意 http.cookiejar 可以將 RFC 2109 cookie '降級(jí)' 為 Netscape cookie，在此情況下 version 值也為 0。

Cookie.name?

Cookie 名稱（一個(gè)字符串）。

Cookie.value?

Cookie 值（一個(gè)字符串），或?yàn)?None。

Cookie.port?

代表一個(gè)端口或一組端口（例如 '80' 或 '80,8080'）的字符串，或?yàn)?None。

Cookie.path?

Cookie 路徑 (字符串類型，例如 '/acme/rocket_launchers')。

Cookie.secure?

如果 cookie 應(yīng)當(dāng)只能通過安全連接返回則為 True。

Cookie.expires?

整數(shù)類型的過期時(shí)間，以距離 Unix 紀(jì)元的秒數(shù)表示，或者為 None。 另請(qǐng)參閱 is_expired() 方法。

Cookie.discard?

如果是會(huì)話 cookie 則為 True。

Cookie.comment?

來自服務(wù)器的解釋此 cookie 功能的字符串形式的注釋，或者為 None。

Cookie.comment_url?

鏈接到來自服務(wù)器的解釋此 cookie 功能的注釋的 URL，或者為 None。

Cookie.rfc2109?

如果 cookie 是作為 RFC 2109 cookie 被接收（即該 cookie 是在 Set-Cookie 標(biāo)頭中送達(dá)，且該標(biāo)頭的 Version cookie 屬性的值為 1）則為 True。 之所以要提供該屬性是因?yàn)?http.cookiejar 可能會(huì)從 RFC 2109 cookies '降級(jí)' 為 Netscape cookie，在此情況下 version 值為 0。

Cookie.port_specified?

如果服務(wù)器顯式地指定了一個(gè)端口或一組端口（在 Set-Cookie / Set-Cookie2 標(biāo)頭中）則為 True。

Cookie.domain_specified?

如果服務(wù)器顯式地指定了一個(gè)域則為 True。

Cookie.domain_initial_dot?

該屬性為 True 表示服務(wù)器顯式地指定了以一個(gè)點(diǎn)號(hào) ('.') 打頭的域。

Cookie 可能還有額外的非標(biāo)準(zhǔn) cookie 屬性。 這些屬性可以通過下列方法來訪問:

Cookie.has_nonstandard_attr(name)?

如果 cookie 具有相應(yīng)名稱的 cookie 屬性則返回 True。

Cookie.get_nonstandard_attr(name, default=None)?

如果 cookie 具有相應(yīng)名稱的 cookie 屬性，則返回其值。 否則，返回 default。

Cookie.set_nonstandard_attr(name, value)?

設(shè)置指定名稱的 cookie 屬性的值。

Cookie 類還定義了下列方法:

Cookie.is_expired(now=None)?

如果 cookie 傳入了服務(wù)器請(qǐng)求其所應(yīng)過期的時(shí)間則為 True。 如果給出 now 值（距離 Unix 紀(jì)元的秒數(shù)），則返回在指定的時(shí)間 cookie 是否已過期。

例子?

第一個(gè)例子顯示了 http.cookiejar 的最常見用法:

import http.cookiejar, urllib.request
cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

這個(gè)例子演示了如何使用你的 Netscape, Mozilla 或 Lynx cookie 打開一個(gè) URL (假定 cookie 文件位置采用 Unix/Netscape 慣例):

import os, http.cookiejar, urllib.request
cj = http.cookiejar.MozillaCookieJar()
cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

下一個(gè)例子演示了 DefaultCookiePolicy 的使用。 啟用 RFC 2965 cookie，在設(shè)置和返回 Netscape cookie 時(shí)更嚴(yán)格地限制域，以及阻止某些域設(shè)置 cookie 或返回它們:

import urllib.request
from http.cookiejar import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
    rfc2965=True, strict_ns_domain=Policy.DomainStrict,
    blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")