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

源代码： :source:`Lib/http/cookiejar.py`

http.cookiejar 模块定义了自动处理 HTTP cookie 的类。这对于访问需要小块数据（cookies）的网站非常有用，这些数据通过来自 Web 服务器的 HTTP 响应在客户端计算机上设置，然后在以后的 HTTP 请求中返回到服务器。

常规的 Netscape cookie 协议和由 RFC 2965 定义的协议都被处理。 RFC 2965 处理默认关闭。 RFC 2109 cookie 被解析为 Netscape cookie，随后根据有效的“策略”被视为 Netscape 或 RFC 2965 cookie。请注意，Internet 上的绝大多数 cookie 都是 Netscape cookie。 http.cookiejar 试图遵循事实上的 Netscape cookie 协议（与原始 Netscape 规范中规定的有很大不同），包括注意 max-age 和 [ X216X] 与 RFC 2965 一起引入的 cookie 属性。

笔记

Set-Cookie 和 Set-Cookie2 标头中的各种命名参数（例如 domain 和 expires) 通常被称为属性。为了将它们与 Python 属性区分开来，该模块的文档使用术语 cookie-attribute 代替。

该模块定义了以下异常：

exception http.cookiejar.LoadError: FileCookieJar 的实例在无法从文件加载 cookie 时引发此异常。 LoadError 是 OSError 的子类。

3.3 版更改：LoadError 成为 OSError 的子类，而不是 IOError。

提供以下类：

class http.cookiejar.CookieJar(policy=None)

policy 是一个实现 CookiePolicy 接口的对象。

CookieJar 类存储 HTTP cookie。它从 HTTP 请求中提取 cookie，并在 HTTP 响应中返回它们。 CookieJar 实例在必要时自动使包含的 cookie 过期。子类还负责从文件或数据库中存储和检索 cookie。

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

policy 是一个实现 CookiePolicy 接口的对象。对于其他参数，请参阅相应属性的文档。

一个 CookieJar，它可以从磁盘上的文件加载 cookie，也可以将 cookie 保存到磁盘文件。在调用 load() 或 revert() 方法之前，不会从命名文件中加载 Cookie。此类的子类记录在 FileCookieJar 子类和与 Web 浏览器的合作部分。

在 3.8 版更改：文件名参数支持类路径对象。

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 是一个域名序列，我们从不接受来自的 cookie，也不向其返回 cookie。 allowed_domains 如果不是 None，这是我们接受和返回 cookie 的唯一域的序列。 secure_protocols 是一系列协议，可以为其添加安全 cookie。默认情况下，https 和 wss（安全 websocket）被认为是安全协议。对于所有其他参数，请参阅 CookiePolicy 和 DefaultCookiePolicy 对象的文档。

DefaultCookiePolicy 实现了 Netscape 和 RFC 2965 cookie 的标准接受/拒绝规则。默认情况下，RFC 2109 cookie（即根据 RFC 2965 规则处理在 Set-Cookie 标头中收到的版本 cookie-attribute 为 1) 的 cookie。但是，如果 RFC 2965 处理被关闭或 rfc2109_as_netscape 是 True，RFC 2109 cookie 会被 CookieJar 实例“降级”为 Netscape cookie，方法是将 Cookie 实例的 X195X] 属性设置为 0。 DefaultCookiePolicy 还提供了一些参数以允许对策略进行一些微调。

class http.cookiejar.Cookie: 此类代表 Netscape、RFC 2109 和 RFC 2965 cookie。预计 http.cookiejar 的用户不会构建自己的 Cookie 实例。相反，如有必要，请在 CookieJar 实例上调用 make_cookies()。

也可以看看

模块 urllib.request: 使用自动 cookie 处理打开 URL。
模块 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 版本=1。
RFC 2965 - HTTP 状态管理机制: 修复了错误的 Netscape 协议。使用 Set-Cookie2 代替 Set-Cookie。使用不广泛。
http://kristol.org/cookie/errata.html: RFC 2965 的未完成勘误。

RFC 2964 - 使用 HTTP 状态管理

CookieJar 和 FileCookieJar 对象

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

CookieJar 有以下方法：

CookieJar.add_cookie_header(request)

将正确的 Cookie 标头添加到 request。

如果政策允许（即。 CookieJar 的 CookiePolicy 实例的 rfc2965 和 hide_cookie2 属性分别为真和假），Cookie2 标头适当的时候也会加入。

request 对象（通常是 urllib.request.Request 实例）必须支持方法 get_full_url()、get_host()、get_type()、 unverifiable()、has_header()、get_header()、header_items()、add_unredirected_header() 和 origin_req_host 属性由 [Xurllib23] 记录。请求。

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 标头，并适当地存储 cookie（主题到 CookiePolicy.set_ok() 方法的批准）。

response 对象（通常是调用 urllib.request.urlopen() 或类似的结果）应该支持一个 info() 方法，它返回一个 ]email.message.Message 实例。

request 对象（通常是 urllib.request.Request 实例）必须支持方法 get_full_url()、get_host()、unverifiable()、和 origin_req_host 属性，如 urllib.request 所述。该请求用于设置 cookie 属性的默认值以及检查是否允许设置 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。如果给出单个参数，则只会删除属于该域的 cookie。如果给定两个参数，则删除属于指定 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。稍后可以使用 load() 或 revert() 方法恢复保存的 cookie。

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: 如果为 true，则从磁盘延迟加载 cookie。不应分配此属性。这只是一个提示，因为这只会影响性能，不会影响行为（除非磁盘上的 cookie 发生变化）。 CookieJar 对象可能会忽略它。标准库中包含的 FileCookieJar 类都不会延迟加载 cookie。

FileCookieJar 子类以及与 Web 浏览器的合作

以下 CookieJar 子类用于读写。

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

一个 FileCookieJar，可以以 Mozilla cookies.txt 文件格式（Lynx 和 Netscape 浏览器也使用这种格式）加载和保存 cookie 到磁盘。

笔记

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

警告

如果您的 cookie 丢失/损坏会带来不便，请在保存之前备份您的 cookie（有一些细微之处可能会导致文件在加载/保存往返过程中发生轻微变化）。

另请注意，Mozilla 运行时保存的 cookie 将被 Mozilla 破坏。

class http.cookiejar.LWPCookieJar(filename, delayload=None, policy=None): FileCookieJar 可以从与 libwww-perl 库的 Set-Cookie3 文件格式兼容的格式加载和保存 cookie 到磁盘。如果您想将 cookie 存储在人类可读的文件中，这会很方便。

在 3.8 版更改：文件名参数支持类路径对象。

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，则返回 False，给定 cookie 域。

这种方法是一种优化。它不需要检查具有特定域的每个 cookie（这可能涉及读取许多文件）。从 domain_return_ok() 和 path_return_ok() 返回 true 将所有工作留给 return_ok()。

如果 domain_return_ok() 为 cookie 域返回 true，则为 cookie 路径调用 path_return_ok()。否则，永远不会为该 cookie 域调用 path_return_ok() 和 return_ok()。如果 path_return_ok() 返回 true，则使用 Cookie 对象本身调用 return_ok() 以进行全面检查。否则，永远不会为该 cookie 路径调用 return_ok()。

请注意，每个 cookie 域都会调用 domain_return_ok()，而不仅仅是 request 域。例如，如果请求域为 "www.example.com"，则该函数可能会同时使用 ".example.com" 和 "www.example.com" 调用。 path_return_ok() 也是如此。

request 参数与 return_ok() 的文档相同。

CookiePolicy.path_return_ok(path, request)

如果不应该返回 cookie，则返回 False，给定 cookie 路径。

请参阅 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() 方法（以及 allowed_domains 的相应参数和方法）。如果您设置了白名单，您可以通过将其设置为无再次将其关闭。

阻止或允许列表中不以点开头的域必须等于要匹配的 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): 返回 domain 是否在设置或接收 cookie 的黑名单中。

DefaultCookiePolicy.allowed_domains(): 返回 None，或允许域的序列（作为元组）。

DefaultCookiePolicy.set_allowed_domains(allowed_domains): 设置允许域的顺序，或 None。

DefaultCookiePolicy.is_not_allowed(domain): 返回 domain 是否不在设置或接收 cookie 的白名单中。

DefaultCookiePolicy 实例具有以下属性，它们都从同名的构造函数参数初始化，并且可以全部分配给。

DefaultCookiePolicy.rfc2109_as_netscape: 如果为 true，则请求 CookieJar 实例降级 RFC 2109 cookie（即通过将 Cookie 实例的版本属性设置为 0，将在 Set-Cookie 标头中收到的具有 1) 版本 cookie 属性的 cookie 发送到 Netscape cookie。默认值为 None，在这种情况下，当且仅当 RFC 2965 处理关闭时，RFC 2109 cookie 才会降级。因此，RFC 2109 cookie 默认被降级。

一般严格开关：

DefaultCookiePolicy.strict_domain: 不允许网站使用国家代码顶级域（如 .co.uk、.gov.uk、.co.nz.etc）设置两部分域。这远非完美，不能保证工作！

RFC 2965 协议严格性开关：

DefaultCookiePolicy.strict_rfc2965_unverifiable: 遵循关于不可验证交易的 RFC 2965 规则（通常，不可验证交易是由重定向或请求托管在另一个站点上的图像引起的）。如果这是错误的，cookies 从不根据可验证性被阻止

Netscape 协议严格性开关：

DefaultCookiePolicy.strict_ns_unverifiable: 将 RFC 2965 规则应用于无法验证的交易，甚至适用于 Netscape cookie。

DefaultCookiePolicy.strict_ns_domain: 指示 Netscape cookie 的域匹配规则的严格程度的标志。有关可接受的值，请参见下文。

DefaultCookiePolicy.strict_ns_set_initial_dollar: 忽略 Set-Cookie 中的 cookie：名称以 '$' 开头的标题。

DefaultCookiePolicy.strict_ns_set_path: 不允许设置路径与请求 URI 路径不匹配的 cookie。

strict_ns_domain 是标志的集合。它的值是由或一起构造的（例如，DomainStrictNoDots|DomainStrictNonDomain 表示两个标志都被设置）。

DefaultCookiePolicy.DomainStrictNoDots: 设置 cookie 时，“主机前缀”不得包含点（例如。 www.foo.bar.com 无法为 .bar.com 设置 cookie，因为 www.foo 包含一个点）。

DefaultCookiePolicy.DomainStrictNonDomain: 未明确指定 domain cookie 属性的 cookie 只能返回到与设置 cookie 的域相同的域（例如 spam.example.com 不会从 example.com 返回没有 domain cookie 属性的 cookie）。

DefaultCookiePolicy.DomainRFC2965Match: 设置 cookie 时，需要完整的 RFC 2965 域匹配。

为方便起见，提供了以下属性，并且是上述标志的最有用的组合：

DefaultCookiePolicy.DomainLiberal: 相当于 0（即。所有上述 Netscape 域严格标志都已关闭）。

DefaultCookiePolicy.DomainStrict: 相当于 DomainStrictNoDots|DomainStrictNonDomain。

例子

第一个例子展示了 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（假设 Unix/Netscape 约定用于 cookie 文件的位置）：

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/")

http.cookiejar — HTTP 客户端的 Cookie 处理 — Python 文档

目录