CookieJar 和 FileCookieJar 對象?

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

CookieJar 有以下方法：

CookieJar.add_cookie_header(request)?

在 request 中添加正確的 Cookie 頭。

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

如 urllib.request 所記載的， request 對象（通常是一個(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 對象需要 origin_req_host 屬性。對已廢棄的方法 get_origin_req_host() 的依賴(lài)已被移除。

CookieJar.extract_cookies(response, request)?

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

CookieJar 將 在*response* 參數中尋找允許的 Set-Cookie 和 Set-Cookie2 頭信息，并適當地存儲cookies（須經(jīng) CookiePolicy.set_ok() 方法批準）。

response 對象（通常是調用 urllib.request.urlopen() 或類(lèi)似方法的結果）應該支持 info() 方法，它返回 email.message.Message 實(shí)例。

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

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

CookieJar.set_policy(policy)?

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

CookieJar.make_cookies(response, request)?

返回從 response 對象中提取的 Cookie 對象的序列。

關(guān)于 response 和 request 參數所需的接口，請參見(jiàn) extract_cookies() 的文檔。

CookieJar.set_cookie_if_ok(cookie, request)?

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

CookieJar.set_cookie(cookie)?

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

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

清除一些cookie。

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

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

CookieJar.clear_session_cookies()?

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

丟棄所有 discard 屬性為真值的已包含 cookie（通常是因為它們沒(méi)有 max-age 或 expires cookie 屬性，或者顯式的 discard cookie 屬性）。 對于交互式瀏覽器，會(huì )話(huà)的結束通常對應于關(guān)閉瀏覽器窗口。

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

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

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

將 cookie 保存到文件。

基類(lèi)會(huì )引發(fā) NotImplementedError。 子類(lèi)可以繼續不實(shí)現該方法。

filename 為要用來(lái)保存 cookie 的文件名稱(chēng)。 如果未指定 filename，則會(huì )使用 self.filename (該屬性默認為傳給構造器的值，如果有傳入的話(huà))；如果 self.filename 為 None，則會(huì )引發(fā) ValueError。

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

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

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

從文件加載 cookie。

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

其參數與 save() 的相同。

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

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

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

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

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

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

FileCookieJar.filename?

默認的保存 cookie 的文件的文件名。 該屬性可以被賦值。

FileCookieJar.delayload?

如為真值，則惰性地從磁盤(pán)加載 cookie。 該屬性不應當被賦值。 這只是一個(gè)提示，因為它只會(huì )影響性能，而不會(huì )影響行為（除非磁盤(pán)中的 cookie 被改變了）。 CookieJar 對象可能會(huì )忽略它。 任何包括在標準庫中的 FileCookieJar 類(lèi)都不會(huì )惰性地加載 cookie。

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

提供了以下 CookieJar 子類(lèi)用于讀取和寫(xiě)入。

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

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

備注

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

警告

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

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

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

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

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

CookiePolicy 對象?

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

CookiePolicy.set_ok(cookie, request)?

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

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

CookiePolicy.return_ok(cookie, request)?

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

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

CookiePolicy.domain_return_ok(domain, request)?

對于給定的 cookie 域如果不應當返回 cookie 則返回 False。

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

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

請注意 domain_return_ok() 會(huì )針對每個(gè) cookie 域被調用，而非只針對 request 域。 例如，該函數會(huì )針對 ".example.com" 和 "www.example.com" 被調用，如果 request 域為 "www.example.com" 的話(huà)。 對于 path_return_ok() 也是如此。

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

CookiePolicy.path_return_ok(path, request)?

對于給定的 cookie 路徑如果不應當返回 cookie 返回 False。

請參閱 domain_return_ok() 的文檔。

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

CookiePolicy.netscape?

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

CookiePolicy.rfc2965?

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

CookiePolicy.hide_cookie2?

不要向請求添加 Cookie2 標頭（此標頭是提示服務(wù)器請求方能識別 RFC 2965 cookie）。

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

DefaultCookiePolicy 對象?

實(shí)現接收和返回 cookie 的標準規則。

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

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

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í)現 CookiePolicy 接口所要求的特性之外，該類(lèi)還允許你阻止和允許特定的域設置和接收 cookie。 還有一些嚴格性開(kāi)關(guān)允許你將相當寬松的 Netscape 協(xié)議規則收緊一點(diǎn)（代價(jià)是可能會(huì )阻止某些無(wú)害的 cookie）。

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

阻止名單或允許名單中不以點(diǎn)號開(kāi)頭的域名必須與要匹配的 cookie 域完全相等。 例如， "example.com" 將匹配阻止名單條目 "example.com"，但不匹配 "www.example.com"。 以點(diǎn)號開(kāi)頭的域名也能與更明確的域相匹配。 例如，"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í)現了下列附加方法:

DefaultCookiePolicy.blocked_domains()?

返回被阻止域的序列（元組類(lèi)型）。

DefaultCookiePolicy.set_blocked_domains(blocked_domains)?

設置被阻止域的序列。

DefaultCookiePolicy.is_blocked(domain)?

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

DefaultCookiePolicy.allowed_domains()?

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

DefaultCookiePolicy.set_allowed_domains(allowed_domains)?

設置被允許域的序列，或者為 None。

DefaultCookiePolicy.is_not_allowed(domain)?

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

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

DefaultCookiePolicy.rfc2109_as_netscape?

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

通用嚴格性開(kāi)關(guān):

DefaultCookiePolicy.strict_domain?

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

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

DefaultCookiePolicy.strict_rfc2965_unverifiable?

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

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

DefaultCookiePolicy.strict_ns_unverifiable?

即便是對 Netscape cookie 也要應用 RFC 2965 規則。

DefaultCookiePolicy.strict_ns_domain?

指明針對 Netscape cookie 的域匹配規則的嚴格程度。 可接受的值見(jiàn)下文。

DefaultCookiePolicy.strict_ns_set_initial_dollar?

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

DefaultCookiePolicy.strict_ns_set_path?

不允許設置路徑與請求 URL 路徑不匹配的 cookie。

strict_ns_domain 是一組旗標。 其值是通過(guò)或運算來(lái)構造的（例如，DomainStrictNoDots|DomainStrictNonDomain 表示同時(shí)設置兩個(gè)旗標）。

DefaultCookiePolicy.DomainStrictNoDots?

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

DefaultCookiePolicy.DomainStrictNonDomain?

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

DefaultCookiePolicy.DomainRFC2965Match?

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

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

DefaultCookiePolicy.DomainLiberal?

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

DefaultCookiePolicy.DomainStrict?

等價(jià)于 DomainStrictNoDots|DomainStrictNonDomain。

Cookie 對象?

Cookie 實(shí)例具有與各種 cookie 標準中定義的標準 cookie 屬性大致對應的 Python 屬性。 這并非一一對應，因為存在復雜的賦默認值的規則，因為 max-age 和 expires cookie 屬性包含相同信息，也因為 RFC 2109 cookie 可以被 http.cookiejar 從第 1 版 '降級為' 第 0 版 (Netscape) cookie。

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

Cookie.version?

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

Cookie.name?

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

Cookie.value?

Cookie 值（一個(gè)字符串），或為 None。

Cookie.port?

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

Cookie.path?

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

Cookie.secure?

如果 cookie 應當只能通過(guò)安全連接返回則為 True。

Cookie.expires?

整數類(lèi)型的過(guò)期時(shí)間，以距離 Unix 紀元的秒數表示，或者為 None。 另請參閱 is_expired() 方法。

Cookie.discard?

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

Cookie.comment?

來(lái)自服務(wù)器的解釋此 cookie 功能的字符串形式的注釋?zhuān)蛘邽?None。

Cookie.comment_url?

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

Cookie.rfc2109?

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

Cookie.port_specified?

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

Cookie.domain_specified?

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

Cookie.domain_initial_dot?

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

Cookie 可能還有額外的非標準 cookie 屬性。 這些屬性可以通過(guò)下列方法來(lái)訪(fǎng)問(wèn):

Cookie.has_nonstandard_attr(name)?

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

Cookie.get_nonstandard_attr(name, default=None)?

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

Cookie.set_nonstandard_attr(name, value)?

設置指定名稱(chēng)的 cookie 屬性的值。

Cookie 類(lèi)還定義了下列方法:

Cookie.is_expired(now=None)?

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

例子?

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

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 打開(kāi)一個(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，在設置和返回 Netscape cookie 時(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/")