http.cookiejar —— HTTP 客户端的 Cookie 处理¶

CookieJar 和 FileCookieJar 对象¶

CookieJar 对象支持 iterator 协议，用于迭代包含的 Cookie 对象。

CookieJar 有以下方法：

CookieJar.add_cookie_header(request)¶

在 request 中添加正确的 Cookie 头。

如果策略允许（即 rfc2965 和 hide_cookie2 属性在 CookieJar 的 CookiePolicy 实例中分别为 True 和 False ）， Cookie2 标头也会在适当时候添加。

如 urllib.request 所记载的， request 对象（通常是一个 urllib.request.Request 实例）必须支持 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() 的依赖已被移除。

CookieJar.extract_cookies(response, request)¶

从HTTP response 中提取 cookie，并在政策允许的情况下，将它们存储在 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(), get_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() 的文档。

CookieJar.set_cookie_if_ok(cookie, request)¶

如果策略规定可以这样做，就设置一个 Cookie 。

CookieJar.set_cookie(cookie)¶

设置一个 Cookie，不需要检查策略是否应该被设置。

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

清除一些cookie。

如果调用时没有参数，则清除所有的cookie。 如果给定一个参数，只有属于该 domain 的cookies将被删除。如果给定两个参数，那么属于指定的 domain 和 URL path 的cookie将被删除。 如果给定三个参数，那么属于指定的 domain 、path 和 name 的cookie将被删除

如果不存在匹配的 cookie，则会引发 KeyError。

CookieJar.clear_session_cookies()¶

丢弃所有的会话 cookie。

丢弃所有 discard 属性为真值的已包含 cookie（通常是因为它们没有 max-age 或 expires cookie 属性，或者显式的 discard cookie 属性）。 对于交互式浏览器，会话的结束通常对应于关闭浏览器窗口。

请注意 save() 方法并不会保存会话的 cookie，除非你通过传入一个真值给 ignore_discard 参数来提出明确的要求。

FileCookieJar 实现了下列附加方法:

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

将 cookie 保存到文件。

基类会引发 NotImplementedError。 子类可以继续不实现该方法。

filename 为要用来保存 cookie 的文件名称。 如果未指定 filename，则会使用 self.filename (该属性默认为传给构造器的值，如果有传入的话)；如果 self.filename 为 None，则会引发 ValueError。

ignore_discard: 即使设定了丢弃 cookie 仍然保存它们。 ignore_expires: 即使 cookie 已超期仍然保存它们

文件如果已存在则会被覆盖，这将清除其所包含的全部 cookie。 已保存的 cookie 可以使用 load() 或 revert() 方法来恢复。

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

从文件加载 cookie。

旧的 cookie 将被保留，除非是被新加载的 cookie 所覆盖。

其参数与 save() 的相同。

指定的文件必须为该类所能理解的格式，否则将引发 LoadError。 也可能会引发 OSError，例如当文件不存在的时候。

在 3.3 版更改: 过去触发的 IOError，现在是 OSError 的别名。

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

清除所有 cookie 并从保存的文件重新加载 cookie。

revert() 可以引发与 load() 相同的异常。 如果执行失败，对象的状态将不会被改变。

FileCookieJar 实例具有下列公有属性:

FileCookieJar.filename¶

默认的保存 cookie 的文件的文件名。 该属性可以被赋值。

FileCookieJar.delayload¶

如为真值，则惰性地从磁盘加载 cookie。 该属性不应当被赋值。 这只是一个提示，因为它只会影响性能，而不会影响行为（除非磁盘中的 cookie 被改变了）。 CookieJar 对象可能会忽略它。 任何包括在标准库中的 FileCookieJar 类都不会惰性地加载 cookie。

FileCookieJar 的子类及其与 Web 浏览器的协同¶

提供了以下 CookieJar 子类用于读取和写入。

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

一个能够以 Mozilla cookies.txt 文件格式（该格式也被 Lynx 和 Netscape 浏览器所使用）从磁盘加载和存储 cookie 的 FileCookieJar。

备注

这会丢失有关 RFC 2965 cookie 的信息，以及有关较新或非标准的 cookie 属性例如 port。

警告

在存储之前备份你的 cookie，如果你的 cookie 丢失/损坏会造成麻烦的话（有一些微妙的因素可能导致文件在加载/保存的往返过程中发生细微的变化）。

还要注意在 Mozilla 运行期间保存的 cookie 将可能被 Mozilla 清除。

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

一个能够以 libwww-perl 库的 Set-Cookie3 文件格式从磁盘加载和存储 cookie 的 FileCookieJar。 这适用于当你想以人类可读的文件来保存 cookie 的情况。

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

CookiePolicy 对象¶

实现了 CookiePolicy 接口的对象具有下列方法:

CookiePolicy.set_ok(cookie, request)¶

返回指明是否应当从服务器接受 cookie 的布尔值。

cookie 是一个 Cookie 实例。 request 是一个实现了由 CookieJar.extract_cookies() 的文档所定义的接口的对象。

CookiePolicy.return_ok(cookie, request)¶

返回指明是否应当将 cookie 返回给服务器的布尔值。

cookie 是一个 Cookie 实例。 request 是一个实现了 CookieJar.add_cookie_header() 的文档所定义的接口的对象。

CookiePolicy.domain_return_ok(domain, request)¶

对于给定的 cookie 域如果不应当返回 cookie 则返回 False。

此方法是一种优化操作。 它消除了检查每个具有特定域的 cookie 的必要性（这可能会涉及读取许多文件）。 从 domain_return_ok() 和 path_return_ok() 返回真值并将所有工作留给 return_ok()。

如果 domain_return_ok() 为 cookie 域返回真值，则会为 cookie 路径调用 path_return_ok()。 在其他情况下，则不会为该 cookie 域调用 path_return_ok() 和 return_ok()。 如果 path_return_ok() 返回真值，则会调用 return_ok() 并附带 Cookie 对象本身以进行全面检查。 在其他情况下，都永远不会为该 cookie 路径调用 return_ok()。

请注意 domain_return_ok() 会针对每个 cookie 域被调用，而非只针对 request 域。 例如，该函数会针对 ".example.com" 和 "www.example.com" 被调用，如果 request 域为 "www.example.com" 的话。 对于 path_return_ok() 也是如此。

request 参数与 return_ok() 的文档所说明的一致。

CookiePolicy.path_return_ok(path, request)¶

对于给定的 cookie 路径如果不应当返回 cookie 返回 False。

请参阅 domain_return_ok() 的文档。

除了实现上述方法，CookiePolicy 接口的实现还必须提供下列属性，指明应当使用哪种协议以及如何使用。 所有这些属性都可以被赋值。

CookiePolicy.netscape¶

实现 Netscape 协议。

CookiePolicy.rfc2965¶

实现 RFC 2965 协议。

CookiePolicy.hide_cookie2¶

不要向请求添加 Cookie2 标头（此标头是提示服务器请求方能识别 RFC 2965 cookie）。

定义 CookiePolicy 类的最适用方式是通过子类化 DefaultCookiePolicy 并重载部分或全部上述的方法。 CookiePolicy 本身可被用作 '空策略' 以允许设置和接收所有的 cookie（但这没有什么用处）。

DefaultCookiePolicy 对象¶

实现接收和返回 cookie 的标准规则。

RFC 2965 和 Netscape cookie 均被涵盖。 RFC 2965 处理默认关闭。

提供自定义策略的最容易方式是重载此类并在你重载的实现中添加你自己的额外检查之前调用其方法:

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

在实现 CookiePolicy 接口所要求的特性之外，该类还允许你阻止和允许特定的域设置和接收 cookie。 还有一些严格性开关允许你将相当宽松的 Netscape 协议规则收紧一点（代价是可能会阻止某些无害的 cookie）。

提供了域阻止名单和允许名单（默认都是关闭的）。 只有不存在于阻止列表且存在于允许列表（如果允许名单被启用）的域才能参与 cookie 的设置与返回。 请使用 blocked_domains 构造器参数，以及 blocked_domains() 和 set_blocked_domains() 方法（以及and the corresponding argument and methods for allowed_domains 的相应参数和方法）。 如果你设置了允许名单，你可以通过将其设为 None 来关闭它。

阻止名单或允许名单中不以点号开头的域名必须与要匹配的 cookie 域完全相等。 例如， "example.com" 将匹配阻止名单条目 "example.com"，但不匹配 "www.example.com"。 以点号开头的域名也能与更明确的域相匹配。 例如，"www.example.com" 和 "www.coyote.example.com" 将匹配 ".example.com" (但不匹配 "example.com" 本身)。 IP 地址不在此例，而是必须完全匹配。 例如，如果 blocked_domains 包含 "192.168.1.2" 和 ".168.1.2"，则会阻止 192.168.1.2，但不会阻止 193.168.1.2。

DefaultCookiePolicy 实现了下列附加方法:

DefaultCookiePolicy.blocked_domains()¶

返回被阻止域的序列（元组类型）。

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，或者被允许域的序列（元组类型）。

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 实例具有下列属性，它们都是基于同名的构造器参数来初始化的，并且都可以被赋值。

DefaultCookiePolicy.rfc2109_as_netscape¶

如为真值，则请求 CookieJar 实例将 RFC 2109 cookie (即在带有 version 值为 1 的 cookie 属性的 Set-Cookie 标头中接收到的 cookie) 降级为 Netscape cookie: 即将 Cookie 实例的 version 属性设为 0。 默认值为 None，在此情况下 RFC 2109 cookie 仅在s are downgraded if and only if RFC 2965 处理被关闭时才会被降级。 因此，RFC 2109 cookie 默认会被降级。

通用严格性开关:

DefaultCookiePolicy.strict_domain¶

不允许网站设置带国家码顶级域的包含两部分的域名例如 .co.uk, .gov.uk, .co.nz 等。 此开关尚未十分完善，并不保证有效！

RFC 2965 协议严格性开关:

DefaultCookiePolicy.strict_rfc2965_unverifiable¶

遵循针对不可验证事务的 RFC 2965 规则（不可验证事务通常是由重定向或请求发布在其它网站的图片导致的）。 如果该属性为假值，则 永远不会 基于可验证性而阻止 cookie。

Netscape 协议严格性开关:

DefaultCookiePolicy.strict_ns_unverifiable¶

即便是对 Netscape cookie 也要应用 RFC 2965 规则。

DefaultCookiePolicy.strict_ns_domain¶

指明针对 Netscape cookie 的域匹配规则的严格程度。 可接受的值见下文。

DefaultCookiePolicy.strict_ns_set_initial_dollar¶

忽略 Set-Cookie 中的 cookie: 即名称前缀为 '{TX-PL-LABEL}#x27; 的标头。

DefaultCookiePolicy.strict_ns_set_path¶

不允许设置路径与请求 URL 路径不匹配的 cookie。

strict_ns_domain 是一组旗标。 其值是通过或运算来构造的（例如，DomainStrictNoDots|DomainStrictNonDomain 表示同时设置两个旗标）。

DefaultCookiePolicy.DomainStrictNoDots¶

当设置 cookie 是，'host prefix' 不可包含点号（例如 www.foo.bar.com 不能为 .bar.com 设置 cookie，因为 www.foo 包含了一个点号）。

DefaultCookiePolicy.DomainStrictNonDomain¶

没有显式指明Cookies that did not explicitly specify a domain cookie 属性的 cookie 只能被返回给与设置 cookie 的域相同的域（例如 spam.example.com 不会是来自 example.com 的返回 cookie，如果该域名没有 domain cookie 属性的话）。

DefaultCookiePolicy.DomainRFC2965Match¶

当设置 cookie 时，要求完整的 RFC 2965 域匹配。

下列属性是为方便使用而提供的，是上述旗标的几种最常用组合:

DefaultCookiePolicy.DomainLiberal¶

等价于 0 (即所有上述 Netscape 域严格性旗标均停用)。

DefaultCookiePolicy.DomainStrict¶

等价于 DomainStrictNoDots|DomainStrictNonDomain。

Cookie 对象¶

Cookie 实例具有与各种 cookie 标准中定义的标准 cookie 属性大致对应的 Python 属性。 这并非一一对应，因为存在复杂的赋默认值的规则，因为 max-age 和 expires cookie 属性包含相同信息，也因为 RFC 2109 cookie 可以被 http.cookiejar 从第 1 版 '降级为' 第 0 版 (Netscape) cookie。

对这些属性的赋值在 CookiePolicy 方法的极少数情况以外应该都是不必要的。 该类不会强制内部一致性，因此如果这样做则你应当清楚自己在做什么。

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 名称（一个字符串）。

Cookie.value¶

Cookie 值（一个字符串），或为 None。

Cookie.port¶

代表一个端口或一组端口（例如 '80' 或 '80,8080'）的字符串，或为 None。

Cookie.path¶

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

Cookie.secure¶

如果 cookie 应当只能通过安全连接返回则为 True。

Cookie.expires¶

整数类型的过期时间，以距离 Unix 纪元的秒数表示，或者为 None。 另请参阅 is_expired() 方法。

Cookie.discard¶

如果是会话 cookie 则为 True。

Cookie.comment¶

来自服务器的解释此 cookie 功能的字符串形式的注释，或者为 None。

Cookie.comment_url¶

链接到来自服务器的解释此 cookie 功能的注释的 URL，或者为 None。

Cookie.rfc2109¶

如果 cookie 是作为 RFC 2109 cookie 被接收（即该 cookie 是在 Set-Cookie 标头中送达，且该标头的 Version cookie 属性的值为 1）则为 True。 之所以要提供该属性是因为 http.cookiejar 可能会从 RFC 2109 cookies '降级' 为 Netscape cookie，在此情况下 version 值为 0。

Cookie.port_specified¶

如果服务器显式地指定了一个端口或一组端口（在 Set-Cookie / Set-Cookie2 标头中）则为 True。

Cookie.domain_specified¶

如果服务器显式地指定了一个域则为 True。

Cookie.domain_initial_dot¶

该属性为 True 表示服务器显式地指定了以一个点号 ('.') 打头的域。

Cookie 可能还有额外的非标准 cookie 属性。 这些属性可以通过下列方法来访问:

Cookie.has_nonstandard_attr(name)¶

如果 cookie 具有相应名称的 cookie 属性则返回 True。

Cookie.get_nonstandard_attr(name, default=None)¶

如果 cookie 具有相应名称的 cookie 属性，则返回其值。 否则，返回 default。

Cookie.set_nonstandard_attr(name, value)¶

设置指定名称的 cookie 属性的值。

Cookie 类还定义了下列方法:

Cookie.is_expired(now=None)¶

如果 cookie 传入了服务器请求其所应过期的时间则为 True。 如果给出 now 值（距离 Unix 纪元的秒数），则返回在指定的时间 cookie 是否已过期。

例子¶

第一个例子显示了 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/")

这个例子演示了如何使用你的 Netscape, Mozilla 或 Lynx cookie 打开一个 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/")

下一个例子演示了 DefaultCookiePolicy 的使用。 启用 RFC 2965 cookie，在设置和返回 Netscape cookie 时更严格地限制域，以及阻止某些域设置 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/")