Python 20.21. cookielib模块翻译

Python 20.21.用于http客户端的处理的模块

By 白熊花田(http://blog.csdn.net/whiterbear) 转载请注明出处，谢谢。

原文链接：https://docs.python.org/2/library/cookielib.html

标注：

cookielib模块已经在python3中改名为http.cookiejar了。2to3这个工具能够自动地在你将代码由python2.x转为python3.x帮你更正源码。

简介：

cookielib模块中定义了几个处理Http cookie的类。cookie是由web服务器返回给在客户端机器并保存在客户端机器的数据文件，并能在之后通过http请求发送给服务器。cookielib模块处理cookie文件很有用，支持网景协议和RFC 2965标准的cookie。通常默认是不处理RFC2965标准的cookie的。实际运行时，RFC2109标准的cookie一般按网景协议来解析继而将其转换成网景协议或者RFC2965标准的cookie。注意到，网上大部分的cookie都是网景协议。cookielib试图采用事实上的网景协议的cookie（当然，这个原本的网景协议差别还是挺大的），从RFC2965标准中引入了如max-age和port这样的cookie属性。

注意：这些命名参数可以在Set-Cookie和Set-Cookie2的头部可以找到，它们是cookie的属性。为了和python中的属性相区分，我们使用术语cookie-attribute来代替。

cookielib中定义了下列的异常类：

cookielib.LoadError

FileCookieJar会在加载cookie失败时抛出这个异常。

       注意：为了向后兼容性，python2.4版本会抛出IOError异常，LoadError是IOError的子类。

cookielib还提供下列的类（简介其用途）：

cookielib.CookieJar(policy=None)

       policy是用来实现CookiePolicy接口的对象。

CookieJar类是用来存储HTTP cookie的。它能从HTTP请求中提取出cookie，然后在HTTP响应中返回cookie。CookieJar类的实例能适时的自动地使cookie过期。它的子类同样能够从文件或数据库中存取cookie。

cookie.FileCookieJar(filename,delayload=None, policy)

       policy是用来实现CookiePolicy接口的对象。其他的参数，可以参考下面详细的文档。

CookieJar类能够从磁盘中加载或者保存cookie文件。cookie只能通过load()或者revert()函数来加载指定文件。它的子类介绍可以参照下面的文档。

cookielib.CookiePolicy

       这个类是负责决定每一个cookie是否应该返回给服务器或者是从服务器接受它们。

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是域名的元组，代表这一组被阻塞的域名元组（被阻塞意味着该域名的cookie将不被接收或者返回给服务器）。allowed_domains如果不为空（None）的话，代表一组能够被接受和返回的域名元组，当然设定了这组域名后，其他域名将不会被处理。其他的参数，请参看CookiePolicy和DefaultCookiePolicy类的中参数介绍。

DefaultCookiePolicy类实现了接收网景协议及RFC2965标准cookie的标准。在默认情况下，RFC2109类型的cookie（即cookie的Set-Cookie头部的cookie属性版本为1）会被按照处理RFC2965cookie的方式来处理。然而，在被设置成不处理RFC2965类型的cookie或者rfc_2109_as_netscape属性为True时，RFC2109类型的cookie会被CookieJar的实例转变成（通过设置cookie版本号为0）网景类型的cookie。DefaultCookiePolicy类同样提供了通过设置一些参数来进行cookie协议类型的转换。

cookielib.Cookie

这个类可以代表网景类型，RFC 2109或者RFC2965类型的cookie。我们并不期待用户会使用cookielib模块来创建自定义类型的cookie，但是，如果需要的话，可以使用make_cookies()来创建一个CookieJar的实例。

20.21.1. CookieJar和FileCookieJar 类

CookieJar类支持迭代器，可以通过迭代的方法获得cookie。

CookieJar有如下的方法：

CookieJar.add_cookie_header(request)

       给request（请求）添加正确的cookie头部。

如果cookie类型符合的话（即CookieJar的CookiePolicy实例的属性满足rfc2965为True且hide_cookie2为False的话），Cookie2的头部仍然会在恰当的时候添加上去。

这个请求对象（通常是urllib2.Request的实例）必须支持urllib2中的get_full_url()，get_host()，get_type()，unverifiable()，get_origin_req_host()，has_header()，get_header()，header_items()和 add_unredirected_header()方法。

CookieJar.extract_cookies(response,request)

       从HTTP响应中提取cookie并将其保存到相应的CookieJar中。

CookieJar能够在响应参数中找到Set-Cookie和Set-Cookie2的头部，并依此合理的储存这些cookie（当CookiePolicy.set_ok()返回True时）。

响应对象（通常是urllib2.urlopen()的返回值）应该支持info()方法，并且返回一个具有getallmatchingheaders()方法的对象（通常是mimetools.Message实例）。

请求对象（通常是urllib2.Request实例）必须支持urrlib2中的get_full_url()，get_host(), unverifiable()和get_origin_req_host()这四个方法。这个请求通常会将cookie属性设为默认值以便于检测该cookie是否可以被设置。

CookieJar.set_policy(policy)

       将CookiePolicy实例设为可用。

CookieJar.make_cookies(response,request)

       返回从响应对象中提取出的cookie列表。

请参阅extract_cookies()函数文档（上文有介绍）来了解必要的response（响应）和request（请求）的参数。

CookieJar.set_cookie_if_ok(cookie,request)

       在cookie类型允许的条件下设置cookie

CookieJar.set_cookie(cookie)

       在不检查cookie类型的条件下设置cookie    

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

       清理cookie。

如果调用时没有给定参数，那么将删除所有cookie。如果给定了一个参数，那么只有属于给定的域名的cookie才会被删除。如果给定两个参数，那么只有属于给定域名和url地址的cookie才会被删除。如果给定了三个参数，那么满足给定的域名，url和name的cookie会被删除。

       如果找不到匹配的cookie的话抛出KeyError异常。

CookieJar.clear_session_cookies()

       删除所有会话的cookie。

删除所有discard属性为True的cookie（通常是一些既没有max-age也没有expires属性（注：两者都是设定cookie的生存周期的）或者cookie中discard属性明确为True的那些cookie）。对于交互式浏览器，会话的结束通常对应着浏览器的关闭。

       注意：save()函数并不能保留这些cookie除非你设置ignore_discard为True。

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被设置为丢弃也保存cookie文件。ignore_expires：即使它们已经过期了也保存cookie。

文件如果存在的话会被重写（即原文件会被覆盖），会擦除原先存在所有cookie。保存在文件中的cookie可以使用load()和revert()函数来调用它。

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

       从一个文件中加载cookie。

       旧的cookie文件会一直存在直到被新的cookie文件重写。

       参数与save()函数一致。

给定的文件中的存储格式必须能够被cookie类兼容，否则会抛出LoadError异常。同样的，也可能会抛出IOError异常如果指定的文件不存在的话。

       注意：为了向后兼容性，python2.4版本会抛出IOError异常，LoadError是IOError的子类。

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

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

       revert()会抛出load()函数一样异常。如果这个过程失败了，原先对象会保持原状态不变。

FileCookieJar的对象有以下的公共属性：

FileCookieJar.filename

       默认的用来存储cookie文件的文件名，可以被指定。

FileCookieJar.delayload

如果值为True，那么将延迟读取硬盘上的cookie文件。这个属性最好不要去指定它。它的作用只是一个提示，尽管这样做只会影响性能，不影响操作（behaviour）（除非这个cookie在磁盘中正在改变的情况下可以采取这种延迟读取）。

       没有任何一个FileCookieJar类包含了延迟读取cookie文件的操作。

20.21.2. FileCookieJar的子类和对相关web浏览器的操作

下面这几个的CookieJar的子类是提供了读写Cookie功能。

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

FileCookieJar对象能够读取具有Mozilla cookies.txt格式的文件（FileCookieJar同样适合读取Lynx（一种文本浏览器）和Netscape（网景浏览器）的）。

       注意：火狐浏览器在版本3中已经不再支持cookies.txt格式的cookie文件了。

注意：这个类会丢失RFC2965的cookie的信息，同样会丢失一些新版本或者非标准格式的cookie属性比如丢失端口信息。

警告：在你保存你的cookie之前请先对cookie进行备份。因为你cookie可能会在加载或者保存的过程中出现轻微的改变从而造成损伤或者毁坏。

       另外需要注意的是在使用网景协议时保存cookie会被网景协议修改。

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

这是一个能够从磁盘中存取与Set-Cookie3（libwww-perl库中的）文件格式兼容的cookie文件。它适合你以一种人类可读的方式存储cookie文件。

20.21.3. CookiePolicy对象

CookiePolicy接口里有以下几个方法：

CookiePolicy.set_ok(cookie, request)

       返回布尔值，该值表示cookie是否应该被服务器接受。

       参数cookie是cookielib.Cookie对象的实例。参数request是一个实现了CookieJar.extract_cookies()中定义的接口的对象。

CookiePolicy.return_ok(cookie, request)

       返回一个布尔值，该值表示cookie是否应该返回给服务器。

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

CookiePolicy.domain_return_ok(domain,request)

       给定cookie的域名，如果cookie不应该被返回的话函数返回False。

这是一个优化的函数。它消除了需要检测每一个特定domain的cookie的必要（这样可能需要查阅很多文件）。如果函数domain_return_ok()和path_return_ok()都返回为True的话，return_ok()才返回为True。

另外，只有在domain_return_ok()返回为True的情况下，path_return_ok()和return_ok()函数才会去访问这个域名下的cookie进行相应的处理。只有在path_return_ok()返回为True的情况下，return_ok()函数才会去该path下的cookie进行相应的处理。

注意：domain_return_ok()函数会判断每一个cookie的域名，而不是只判断给定的request中的域名。比如，在给定request参数为www.example.com时，该函数会处理”.example.com”和”www.example.com”这两个域中的cookie。另外，path_return_ok()函数也是这样判断的。

       在return_ok()函数中也描述了这个请求参数。

CookiePolicy.path_return_ok(path,request)

       给定cookie的路径，如果cookie不应该被返回的话，返回False。

       函数说明请参照上面的domain_return_ok()函数。

另外，CookiePolicy接口还提供以下几个属性用来表示Cookie协议应该使用哪个，怎么使用等等。所有这些属性都可以重新赋值。

CookiePolicy.netscape

实现了Netscape协议。

CookiePolicy.rfc2965

实现了RFC2965协议。

CookiePolicy.hide_cookie2

       不给请求添加Cookie2的头部（这个头部的存在即表明我们使用RFC2965协议的cookie）。

定义一个CookiePolicy类最有效的方法就是子类化DefaultCookiePolicy并且重写上面的全部或部分方法。CookiePolicy本身也可以当作基类（它没有设定任何cookie类型）来处理任何cookie文件（一般不这样做）。

20.21.4.DefaultCookiePolicy 类

实现了标准方法来接受和返回cookie文件。

可以处理RFC2965和Netscape类型的cookie文件。通常默认是不处理RFC2965类型的cookie的（可以设置）。

最简单的方式来处理你想要的cookie类型的文件就是继承这个类，重写它的方法，并且加上一些类型检查。

如：

importcookielib

classMyCookiePolicy(cookielib.DefaultCookiePolicy):

    def set_ok(self, cookie, request):

        if notcookielib.DefaultCookiePolicy.set_ok(self, cookie, request):

            return False

        if i_dont_want_to_store_this_cookie(cookie):

            return False

        return True

除了要求实现的CookiePolicy的接口，这个类还允许你设置一组域名来阻止或者允许是否接收cookie文件。也可以设置地很严格，这样能够加强网景协议（但是要以某些好的cookie被屏蔽为代价）。

一个域的黑名单和白名单都是默认不提供的。只有域名不在黑名单中，并且在白名单中（如果白名单设定了的话）时，才能设置与接收此域名中的cookie文件。使用blocked_domains构造参数，和blocked_domains()和set_blocked_domains()方法（和其对应的参数和方法）。如果你设置了白名单，你也可以关掉它们并设置它们为None。

域名在屏蔽或者允许列表中但是并没有以点号开头的必须和cookie的域名相同才能匹配。例如example.com能够匹配黑名单中的example.com但是www.example.com就不能匹配example.com了。域名以点号开头的能够匹配更多特定的域名。例如，www.example.com和www.coyte.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)

       返回该域名是否在黑名单中。

DefaultCookiePolicy.allowed_domains()

       返回允许的域名元组，如果没有，则返回None

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

       设置允许的域名组，参数可以为空（None）

DefaultCookiePolicy.is_not_allowed(domain)

       返回该域名是否在白名单中。

DefaultCookiePolicy 实例有如下的属性。这些属性都会在构造函数中被初始化，但是也可以在之后重新对它们赋值。

DefaultCookiePolicy.rfc2109_as_netscape

值为True表示CookieJar的实例会将RFC2109类型的cookie转变成网景协议的cookie（将cookie头部版本号设为0，本来是1的）。默认值是None，在这种情况下，RFC2109协议的cookie只会在RFC2965协议处理方法关闭的情况下才会被转变。因此，默认情况下，RFC2109协议的cookie会被转变成其他类型的cookie。

通用的限制的属性：

DefaultCookiePolicy.strict_domain

       不允许一些有着多分域的国家级顶级域名站点，比如.co.uk，.gov.u，.co.nz.etc。

       这并不能保证一定有用，且效率很差。

RFC2965协议的苛刻的属性：

DefaultCookiePolicy.strict_rfc2965_unverifiable

按RFC2965协议的规则对无法核实的cookie活动进行处理（通常一个无法核实的交易源于对另外一个主机图片的重定向或者请求）。如果这个值为False的话，那么cookie将永远不会在可验证的基础上被屏蔽。

网景协议的限制的属性：

DefaultCookiePolicy.strict_ns_unverifiable

       使用RFC2965协议处理包括网景协议在内的未验证的cookie活动。

DefaultCookiePolicy.strict_ns_domain

       指示如何对网景协议的cookie进行严格的处理的标识。

下面是一些可选的值：

DefaultCookiePolicy.strict_ns_set_initial_dollar

       忽略Set-Cookie中头部以$开头的cookie。

DefaultCookiePolicy.strict_ns_set_path

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

strict_ns_domain是一组标识。它的值通常使用“|” 竖杠符号设定（比如DomainStrictNoDots|DomainStrictNonDomain意味着这两种标识都会被设置）。

DefaultCookiePolicy.DomainStrictNoDots

在设置cookie时，主机前缀不能包含点号（比如，www.foo.bar.com不能被设置成.bar.com的cookie，因为www.foo中包含一个点号）。

DefaultCookiePolicy.DomainStrictNonDomain

没有明确的指定cookie域属性的cookie只能返回一个能够设置这个cookie的域的等价域名（比如spam.example.com就不会返回example.com域名中没有域名属性的cookie）。

DefaultCookiePolicy.DomainRFC2965Match

       在设置cookie时需要完全符合RFC2965域匹配规则。

DefaultCookiePolicy.DomainLiberal

       相当于0（即所有的上述的网景域名的限制属性皆没并被设置）

DefaultCookiePolicy.DomainStrict

       相当于DomainStrictNoDots|DomainStrictNonDomain

20.21.5. Cookie类

Cookie实例的属性与标准cookie属性差不多。这种属性之间的关系并不是一一对应的，因为这其中有着复杂的默认值设定，有着max-age和expires等价的属性，也因为RFC2109类型的cookie可能会在cookielib中由版本1变为版本0了。

一般是不需要给这些cookie属性赋值的，除了在一些少有的情况下使用CookiePolicy中的方法进行赋值操作。这个类并不要求其内部一致性，所以编程时你要时刻了解你处理的是什么。

Cookie.version

整型或者为None。网景协议的cookie版本为0，RFC2965和RFC2109协议的cookie的版本为1。然而，cookielib可能会将RFC2109类型的cookie转变成网景类型的cookie，这样它的版本号就可能变为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

       整型，以秒为单位，表示新纪元之后的秒数（1970年？），或者为空（None）。

Cookie.discard

       值为True表示这是一个会话期间产生的cookie

Cookie.comment

       字符串类型，表示服务器方面表示的该cookie文件的作用，可以为空（None）

Cookie.comment_url

       链接，指向上面的功能介绍（comment），可为空（None）

Cookie.rfc2109

值为True表示该cookie是RFC2109类型的，这个值存在意义在于cookielib可能会将RFC2109版本的cookie转变成网景协议的版本，这样版本号就从1变为0，从而无法依据版本号来判断cookie文件的类型了。

Cookie.port_specified

值为True表示服务器已经明确指定了一个端口或者一组端口（端口设定在Set-Cookie/Set-Cookie2的头部）。

Cookie.domain_specified

       值为True表明服务器已经明确指定的域名

Cookie.domain_initial_dot

       值为True表明服务器已经明确指定了域名且以点‘.’开头。

Cookie还有一些非标准属性，可以使用如下的方法来获得它们：

Cookie.has_nonstandard_attr(name)

       返回True如果cookie有给定参数name的属性

Cookie.get_nonstandard_attr(name,default=None)

       如果cookie有给定参数name的属性则返回这个属性的值，否则返回参数default值。

Cookie.set_nonstandard_attr(name,value)

       设置cookie非标准属性名值对

Cookie类还定义了一下函数：

Cookie.is_expired([now=None])

返回True，如果cookie在服务器请求之后已经超时了。如果给定了now参数的话，返回cookie是否已经在给定的时间内超时。

20.21.6. 样例：

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

importcookielib, urllib2

cj= cookielib.CookieJar()

opener= urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))

r= opener.open(“http://example.com/”)

下面这个例子显示了如何通过网景，Mozilla或者Lynx的cookie文件打开URL（假定Unix/Netscape中的cookie文件在默认的位置）：

importos, 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类。

importurllib2

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

介绍cookie属性：资料源于：cookie属性介绍

expires属性

指定了coolie的生存期，默认情况下coolie是暂时存在的，他们存储的值只在浏览器会话期间存在，当用户推出浏览器后这些值也会丢失，如果想让cookie存在一段时间，就要为expires属性设置为未来的一个过期日期。现在已经被max-age属性所取代，max-age用秒来设置cookie的生存期。

path属性

它指定与cookie关联在一起的网页。在默认的情况下cookie会与创建它的网页，该网页处于同一目录下的网页以及与这个网页所在目录下的子目录下的网页关联。

domain属性

domain属性可以使多个web服务器共享cookie。domain属性的默认值是创建cookie的网页所在服务器的主机名。不能将一个cookie的域设置成服务器所在的域之外的域。

例如让位于order.example.com的服务器能够读取catalog.example.com设置的cookie值。如果catalog.example.com的页面创建的cookie把自己的path属性设置为“/”，把domain属性设置成“.example.com”，那么所有位于catalog.example.com的网页和所有位于orlders.example.com的网页，以及位于example.com域的其他服务器上的网页都可以访问这个coolie。

 secure属性

它是一个布尔值，指定在网络上如何传输cookie，默认是不安全的，通过一个普通的http连接传输

下载pdf：http://download.csdn.net/detail/whiterbear/8569389