http.cookiejar ---HTTP客户端的cookie处理

源代码： Lib/http/cookiejar.py

这个 http.cookiejar 模块定义用于自动处理HTTP cookie的类。它对于访问需要小数据块的网站很有用-- cookies --由Web服务器的HTTP响应在客户机上设置，然后在以后的HTTP请求中返回到服务器。

常规Netscape cookie协议和 RFC 2965 被处理。默认情况下，RFC 2965处理被关闭。 RFC 2109 cookies被解析为netscape cookies，然后根据有效的“策略”被视为netscape或rfc 2965 cookies。请注意，Internet上绝大多数cookie都是Netscape cookie。 http.cookiejar 尝试遵循事实上的Netscape cookie协议（与原始Netscape规范中规定的协议大不相同），包括注意 max-age 和 port 使用RFC2965引入的cookie属性。

注解

在中找到的各种命名参数 Set-Cookie 和 Set-Cookie2 报头（例如） domain 和 expires ）通常被称为 attributes . 为了区别于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 接口。有关其他参数，请参阅相应属性的文档。

A CookieJar 它可以从磁盘上的文件加载cookie，也可以将cookie保存到磁盘上的文件。饼干是 NOT 从命名文件加载，直到 load() 或 revert() 方法被调用。该类的子类记录在第节中。 filecookiejar子类和与Web浏览器的合作 .

在 3.8 版更改: 文件名参数支持 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 是一个域名序列，我们从不接受来自或返回cookie。 allowed_domains 如果没有 None ，这是我们接受并返回cookie的唯一域的序列。 secure_protocols 是可以为其添加安全cookie的协议序列。默认情况下 HTTPS 和 wss （安全WebSocket）被认为是安全协议。有关所有其他参数，请参阅 CookiePolicy 和 DefaultCookiePolicy 物体。

DefaultCookiePolicy 为Netscape和 RFC 2965 饼干。默认情况下， RFC 2109 cookies（即在 Set-Cookie 版本cookie属性为1）的头按照RFC2965规则处理。但是，如果关闭了RFC 2965处理，或者 rfc2109_as_netscape 是 True ，RFC 2109 cookies被 CookieJar 通过设置 version 的属性 Cookie 实例为0。 DefaultCookiePolicy 还提供一些参数以允许对策略进行一些微调。

class http.cookiejar.Cookie

此类表示Netscape， RFC 2109 和 RFC 2965 饼干。预计的用户 http.cookiejar 构建自己的 Cookie 实例。如有必要，请致电 make_cookies() 在一 CookieJar 实例。

参见

模块 urllib.request

使用自动cookie处理打开URL。

模块 http.cookies

HTTP cookie类，主要用于服务器端代码。这个 http.cookiejar 和 http.cookies 模块之间不相互依赖。

https://curl.haxx.se/rfc/cookie_spec.html

原始Netscape cookie协议的规范。尽管这仍然是主要的协议，但所有主要浏览器实现的“Netscape cookie协议”（和 http.cookiejar ）只是有一个过眼云烟的相似之处 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 对象支持 iterator 迭代包含的协议 Cookie 物体。

CookieJar 有以下方法：

添加正确 Cookie 报头到 请求 .

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

这个 请求 对象（通常为 urllib.request.Request 实例）必须支持这些方法 get_full_url() ， get_host() ， get_type() ， unverifiable() ， has_header() ， get_header() ， header_items() ， add_unredirected_header() 和 origin_req_host 属性记录人 urllib.request .

在 3.3 版更改: 请求 对象需要 origin_req_host 属性。依赖于已弃用的方法 get_origin_req_host() 已删除。

CookieJar.extract_cookies(response, request)

从HTTP提取cookies 响应 把它们储存在 CookieJar ，在政策允许的情况下。

这个 CookieJar 会寻找允许的 Set-Cookie 和 Set-Cookie2 标题在 响应 参数，并根据需要存储cookie（取决于 CookiePolicy.set_ok() 方法的批准）。

这个 响应 对象（通常是调用 urllib.request.urlopen() 或类似）应支持 info() 方法，它返回 email.message.Message 实例。

这个 请求 对象（通常为 urllib.request.Request 实例）必须支持这些方法 get_full_url() ， get_host() ， unverifiable() 和 origin_req_host 属性，如文档所示 urllib.request . 该请求用于设置cookie属性的默认值以及检查是否允许设置cookie。

在 3.3 版更改: 请求 对象需要 origin_req_host 属性。依赖于已弃用的方法 get_origin_req_host() 已删除。

CookieJar.set_policy(policy)

设置 CookiePolicy 要使用的实例。

CookieJar.make_cookies(response, request)

返回顺序 Cookie 从中提取的对象 响应 对象。

参见文档 extract_cookies() 对于所需的接口 响应 和 请求 参数。

设置一个 Cookie 如果政策规定可以的话。

设置一个 Cookie ，而不检查是否应设置策略。

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

清除一些饼干。

如果调用时没有参数，请清除所有cookie。如果只给出一个参数，那么只有属于该参数的cookie 域 将被删除。如果给定两个参数，则属于指定的 域 和网址 path 被移除。如果给定三个参数，则使用指定的 域 ， path 和 name 被移除。

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

CookieJar.clear_session_cookies()

放弃所有会话cookie。

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

请注意 save() 方法不会保存会话cookie，除非您通过传递一个true来询问其他情况。 ignore_discard 参数。

FileCookieJar 实现以下附加方法：

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

将cookies保存到文件中。

这个基类引发 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)

A FileCookieJar 可以从Mozilla中加载cookie并将其保存到磁盘 cookies.txt 文件格式（lynx和netscape浏览器也使用该格式）。

注解

这会丢失有关 RFC 2965 cookie，以及更新或非标准cookie属性，如 port .

警告

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

另外请注意，运行Mozilla时保存的cookie会被Mozilla击倒。

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

A FileCookieJar 它可以以与libwww perl库兼容的格式从cookie加载并保存到磁盘 Set-Cookie3 文件格式。如果您想将cookie存储在一个可读的文件中，这很方便。

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

CookiePolicy对象

对象实现 CookiePolicy 接口有以下方法：

CookiePolicy.set_ok(cookie, request)

返回一个布尔值，指示是否应从服务器接受cookie。

cookie 是一个 Cookie 实例。 请求 是实现文档为定义的接口的对象 CookieJar.extract_cookies() .

CookiePolicy.return_ok(cookie, request)

返回指示是否应将cookie返回到服务器的布尔值。

cookie 是一个 Cookie 实例。 请求 是实现文档为定义的接口的对象 CookieJar.add_cookie_header() .

CookiePolicy.domain_return_ok(domain, request)

返回 False 如果不应返回cookie，请指定cookie域。

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

如果 domain_return_ok() 对于cookie域返回true， path_return_ok() 为cookie路径调用。否则， path_return_ok() 和 return_ok() 从未为该cookie域调用。如果 path_return_ok() 返回true， return_ok() 是用 Cookie 对象本身进行完整检查。否则， return_ok() 从未为该cookie路径调用。

注意 domain_return_ok() 为每一个 cookie 域，不只是为了 请求 领域。例如，可以用两种方法调用函数 ".example.com" 和 "www.example.com" 如果请求域是 "www.example.com" . 同样的道理 path_return_ok() .

这个 请求 证明文件如下： return_ok() .

CookiePolicy.path_return_ok(path, request)

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

参见文档 domain_return_ok() .

除了实现上述方法外，还实现 CookiePolicy 接口还必须提供以下属性，指示应使用哪些协议以及如何使用。所有这些属性都可以分配给。

CookiePolicy.netscape

实现Netscape协议。

CookiePolicy.rfc2965

实施 RFC 2965 协议。

CookiePolicy.hide_cookie2

不要加 Cookie2 请求头（此头的存在表示我们了解的服务器 RFC 2965 饼干）。

定义 CookiePolicy 类是通过从 DefaultCookiePolicy 并重写上面的部分或全部方法。 CookiePolicy 本身可以用作“空策略”，以允许设置和接收任何和所有cookie（这不太可能有用）。

默认cookiepolicy对象

执行接受和返回cookie的标准规则。

两个 RFC 2965 包括Netscape cookies。默认情况下，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）。

提供了域阻止列表和allowlist（默认情况下都关闭）。只有不在阻止列表中且存在于allowlist中的域（如果allowlist是活动的）才参与cookie设置和返回。使用 blocked_domains 构造函数参数，和 blocked_domains() 和 set_blocked_domains() 方法（以及相应的参数和方法 allowed_domains ). 如果设置了allowlist，则可以通过将其设置为来再次将其关闭 None .

块或允许列表中不以点开头的域必须等于要匹配的cookie域。例如， "example.com" 匹配的阻止列表条目 "example.com" ，但是 "www.example.com" 没有。以点开头的域也与更具体的域匹配。例如，两者 "www.example.com" 和 "www.coyote.example.com" 比赛 ".example.com" （但是 "example.com" 但事实并非如此）。IP地址是一个例外，必须完全匹配。例如，如果被阻止的域包含 "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)

返回是否 域 在设置或接收cookies的阻止列表中。

DefaultCookiePolicy.allowed_domains()

返回 None 或允许域的序列（作为元组）。

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

设置允许域的序列，或 None .

DefaultCookiePolicy.is_not_allowed(domain)

返回是否 域 不在用于设置或接收cookies的allowlist中。

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

DefaultCookiePolicy.rfc2109_as_netscape

如果为真，请 CookieJar 实例降级 RFC 2109 cookies（即在 Set-Cookie 通过设置 Cookie 0的实例。默认值为 None ，在这种情况下，如果且仅当 RFC 2965 处理已关闭。因此，默认情况下，RFC2109 cookie会被降级。

一般严格开关：

DefaultCookiePolicy.strict_domain

不允许站点使用国家代码顶级域设置两个组件域，如 .co.uk ， .gov.uk ， .co.nz 等等，这远不是完美的，也不能保证有效！

RFC 2965 协议严格性开关：

DefaultCookiePolicy.strict_rfc2965_unverifiable

跟随 RFC 2965 关于不可验证事务的规则（通常，不可验证事务是由于重定向或对托管在另一个站点上的图像的请求而产生的事务）。如果这是错误的，那么cookies是 从未 基于可验证性而阻塞

Netscape协议严格性交换机：

DefaultCookiePolicy.strict_ns_unverifiable

应用 RFC 2965 关于无法验证的事务的规则，即使是对Netscape cookies也是如此。

DefaultCookiePolicy.strict_ns_domain

指示对Netscape cookies的域匹配规则有多严格的标志。可接受值见下文。

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 无法为设置cookie .bar.com ，因为 www.foo 包含一个点）。

DefaultCookiePolicy.DomainStrictNonDomain

没有明确指定 domain cookie属性只能返回到与设置cookie的域相同的域（例如 spam.example.com 不会被退回饼干 example.com 那没有 domain 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 cookies打开URL（假定cookies文件位置采用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 cookies，在设置和返回Netscape cookies时对域更严格，并阻止某些域设置cookies或让它们返回：

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