cookielib

cookielib — Cookie handling for HTTP clients

注意

该cookielib模块已被重命名为http.cookiejarPython 3. 当将源代码转换为Python 3时，2to3工具将自动适应导入。

2.4版本中的新功能。

源代码： Lib / cookielib.py

该cookielib模块定义了用于自动处理HTTP Cookie的类。对于访问需要小型数据片断的网站（cookie），它可以通过来自Web服务器的HTTP响应在客户端机器上设置，然后在稍后的HTTP请求中返回到服务器。

常规的Netscape cookie协议和RFC 2965定义的协议都被处理。RFC 2965处理默认关闭。根据实际的“策略”，RFC 2109 cookie被解析为Netscape cookies，随后被视为Netscape或RFC 2965 cookie。请注意，互联网上绝大多数的cookies都是Netscape cookies。cookielib试图遵循的事实上的Netscape cookie协议（其从载于原始的Netscape规范基本上不同），包括采取注意到的max-age和port与RFC 2965引入cookie的属性。

注意

在Set-Cookie和Set-Cookie2头文件（例如。domain和expires）中找到的各种命名参数通常称为属性。为了区分它们与Python属性，本模块的文档使用术语cookie-attribute代替。

该模块定义了以下例外情况：

exception cookielib.LoadError

FileCookieJar在未能从文件加载cookie 时引发此异常的实例。

注意

为了向后兼容Python 2.4（提出了一个IOError），它LoadError是一个子类IOError。

提供以下课程：

class cookielib.CookieJar(policy=None)

策略是实现CookiePolicy接口的对象。

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

class cookielib.FileCookieJar(filename, delayload=None, policy=None)

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

CookieJar可以从磁盘上的文件加载Cookie，也可以将Cookie保存到磁盘上的文件。在调用or 方法之前，不会从指定的文件加载Cookies 。该类的子类在FileCookieJar子类和与Web浏览器的合作中进行了介绍。load()revert()

class cookielib.CookiePolicy

这个类负责决定每个cookie是否被接受/返回到服务器。

class cookielib.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)

构造函数参数只能作为关键字参数传递。blocked_domains是一系列域名，我们从不接受cookies，也不返回cookie。如果不是，则为allowed_domainsNone，这是我们接受和返回cookie的唯一域的序列。对于所有其他参数，请参阅文档CookiePolicy和DefaultCookiePolicy对象。

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

class cookielib.Cookie

这个类代表Netscape，RFC 2109和RFC 2965 cookies。预计用户不会cookielib构建自己的Cookie实例。相反，如果必要的话，叫make_cookies()上一个CookieJar实例。

1. CookieJar和FileCookieJar对象

CookieJar对象支持用于遍历包含对象的迭代器协议Cookie。

CookieJar 有以下方法：

CookieJar.add_cookie_header(request)

添加正确的Cookie标头以请求。

如果策略允许（即在rfc2965与hide_cookie2所述属性CookieJar的CookiePolicy实例分别是真和假），则COOKIE2头也被添加在适当的时候。

所述请求对象（通常是一个urllib2.Request实例）必须支持方法get_full_url()，get_host()，get_type()，unverifiable()，get_origin_req_host()，has_header()，get_header()，header_items()，和add_unredirected_header()，由作为记录的urllib2。

CookieJar.extract_cookies(response, request)

从HTTP 响应中提取cookie 并将其存储在CookieJar策略允许的地方。

该CookieJar会寻找容许的Set-Cookie和设置，COOKIE2在头响应参数，存储cookies适当（受CookiePolicy.set_ok()方法的批准）。

该响应对象（到一个呼叫的通常的结果urllib2.urlopen()，或类似的）应支持的info()方法，该方法用一个返回对象getallmatchingheaders()的方法（通常是一个mimetools.Message实例）。

所述请求对象（通常是一个urllib2.Request实例）必须支持方法get_full_url()，get_host()，unverifiable()，和get_origin_req_host()，由作为记录的urllib2。该请求用于设置cookie属性的默认值，并用于检查是否允许设置cookie。

CookieJar.set_policy(policy)

设置CookiePolicy要使用的实例。

CookieJar.make_cookies(response, request)

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

请参阅文档以extract_cookies()获取响应和请求参数所需的接口。

CookieJar.set_cookie_if_ok(cookie, request)

设置一个Cookie如果政策说可以这样做。

CookieJar.set_cookie(cookie)

设置一个Cookie，不用检查政策，看看是否应该设置。

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

清除一些cookies。

如果没有参数调用，请清除所有的cookie。如果只有一个参数，则只有属于该域的 cookie 才会被删除。如果给出两个参数，则删除属于指定域和URL 路径的 Cookie 。如果有三个参数，那么具有指定域，路径和名称的cookie将被删除。

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

CookieJar.clear_session_cookies()

丢弃所有会话cookie。

放弃所有包含的具有真实discard属性的cookie （通常是因为它们具有no max-age或expirescookie属性或明确的discardcookie属性）。对于交互式浏览器，会话结束通常对应于关闭浏览器窗口。

请注意，该save()方法无论如何不会保存会话cookie，除非您通过传递true_default_discard参数来另外提问。

FileCookieJar 实现以下附加方法：

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

将Cookie保存到文件。

这个基类引发了NotImplementedError。子类可能会使此方法未实现。

文件名是保存cookie的文件的名称。如果没有指定filename，self.filename则使用（默认值是传递给构造函数的值，如果有的话）; 如果self.filename是None，ValueError被提出。

ignore_discard：保存即使被设置为丢弃的Cookie。ignore_expires：保存即使过期的cookies

如果文件已经存在，则该文件被覆盖，从而清除它包含的所有cookie。保存的cookie可以在以后使用load()or revert()方法恢复。

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

从文件加载cookie。

旧cookies保留，除非被新加载的饼干覆盖。

参数是至于save()。

指定的文件必须采用该类LoadError可以理解的格式，否则会被引发。另外，IOError可能会提出，例如，如果该文件不存在。

注意

为了向后兼容Python 2.4（提出了一个IOError），它LoadError是一个子类IOError。

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。

2. FileCookieJar子类和与Web浏览器的合作

CookieJar提供以下子类用于阅读和写作。

class cookielib.MozillaCookieJar(filename, delayload=None, policy=None)

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

注意

Firefox网络浏览器的第3版不再以cookies.txt文件格式写入cookie 。

注意

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

警告

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

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

class cookielib.LWPCookieJar(filename, delayload=None, policy=None)

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

3. CookiePolicy对象

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

CookiePolicy.set_ok(cookie, request)

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

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

CookiePolicy.return_ok(cookie, request)

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

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

CookiePolicy.domain_return_ok(domain, request)

如果cookie不应该返回，则返回false。

这种方法是一种优化。它不需要检查每个具有特定域的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)

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

请参阅文档domain_return_ok()。

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

CookiePolicy.netscape

实施Netscape协议。

CookiePolicy.rfc2965

实施RFC 2965协议。

CookiePolicy.hide_cookie2

不要将Cookie2头添加到请求中（该头的存在向服务器表明我们理解RFC 2965 Cookie）。

定义一个CookiePolicy类最有用的方法是通过子类化DefaultCookiePolicy并覆盖上面的一些或全部方法。CookiePolicy本身可能被用作'空白策略'来允许设置和接收任何和所有的cookies（这不太可能有用）。

4. DefaultCookiePolicy对象

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

覆盖了RFC 2965和Netscape cookies。RFC 2965处理默认关闭。

提供自己策略的最简单方法是在添加自己的附加检查之前，重写此类并在重写的实现中调用其方法：

import cookielib
class MyCookiePolicy(cookielib.DefaultCookiePolicy):
    def set_ok(self, cookie, request):
        if not cookielib.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的相应参数和方法）。如果您设置了白名单，则可以将其设置为关闭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"and ".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)

返回域名是否在黑名单上，用于设置或接收Cookie。

DefaultCookiePolicy.allowed_domains()

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

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

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

DefaultCookiePolicy.is_not_allowed(domain)

返回域名是否不在白名单上，用于设置或接收cookie。

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

DefaultCookiePolicy.rfc2109_as_netscape

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

2.5版本中的新功能。

一般严格开关：

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不能设置cookie ）。.bar.comwww.foo

DefaultCookiePolicy.DomainStrictNonDomain

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

DefaultCookiePolicy.DomainRFC2965Match

设置cookie时，需要完整的RFC 2965域名匹配。

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

DefaultCookiePolicy.DomainLiberal

相当于0（即所有上述Netscape域严格标志关闭）。

DefaultCookiePolicy.DomainStrict

相当于DomainStrictNoDots|DomainStrictNonDomain。

5. Cookie对象

Cookie实例的Python属性大致对应于各种Cookie标准中指定的标准Cookie属性。通信不是一一对应的，因为复杂的默认值分配规则很复杂，因为max-age和expirescookie属性包含等效信息，并且由于RFC 2109 cookie可能会cookielib从版本1 “降级” 到版本0（Netscape）饼干。

对于这些属性的分配不应该是必要的，除非在极少数情况下CookiePolicy。班级不强制内部一致性，所以如果你这样做，你应该知道你在做什么。

Cookie.version

整数或None。Netscape cookies有version0. RFC 2965和RFC 2109 cookie的versioncookie属性为1.但是，请注意，cookielib可能会将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

e 如果cookie只能通过安全连接返回Tru。

Cookie.expires

自epoch开始，整数失效日期或以秒为单位None。另见该is_expired()方法。

Cookie.discard

返回True 如果这是一个会话cookie。

Cookie.comment

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

Cookie.comment_url

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

Cookie.rfc2109

True如果此cookie是作为RFC 2109 cookie收到的（即cookie到达Set-Cookie标头，并且该标头中的Version cookie属性值为1）。提供此属性是因为cookielib可能会将RFC 2109 cookie降级为Netscape cookie，在这种情况下version为0。

2.5版本中的新功能。

Cookie.port_specified

True如果一个端口或一组端口被服务器明确指定（在Set-Cookie / Set-Cookie2头文件中）。

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属性，则返回其值。否则，返回默认值。

Cookie.set_nonstandard_attr(name, value)

设置指定的cookie属性的值。

的Cookie类也定义了下面的方法：

Cookie.is_expired([now=None])

True如果cookie已超过服务器请求的时间，则应该过期。如果现在给出（从纪元开始以秒计），返回cookie是否在指定时间到期。

6.例子

第一个例子显示了最常用的用法cookielib：

import cookielib, urllib2
cj = cookielib.CookieJar()
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

这个例子说明了如何使用你的Netscape，Mozilla或者Lynx cookies（假定用于定位cookies文件的Unix / Netscape约定）来打开一个URL：

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

下一个例子说明了使用DefaultCookiePolicy。打开RFC 2965 cookie，在设置和返回Netscape cookies时对域进行更严格的限制，并阻止某些域设置cookie或让它们返回：

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