CookieJar 與 FileCookieJar 物件¶

CookieJar objects support theiterator protocol for iterating overcontainedCookie objects.

CookieJar 擁有以下方法：

CookieJar.add_cookie_header(request)¶

將正確的Cookie 標頭加入request。

If policy allows (ie. therfc2965 andhide_cookie2 attributes oftheCookieJar'sCookiePolicy instance are true and falserespectively), theCookie2 header is also added when appropriate.

Therequest object (usually aurllib.request.Request instance)must support the methodsget_full_url(),has_header(),get_header(),header_items(),add_unredirected_header()and the attributeshost,type,unverifiableandorigin_req_host as documented byurllib.request.

在 3.3 版的變更:request object needsorigin_req_host attribute. Dependency on adeprecated methodget_origin_req_host() has been removed.

CookieJar.extract_cookies(response,request)¶

Extract cookies from HTTPresponse and store them in theCookieJar,where allowed by policy.

TheCookieJar will look for allowableSet-Cookie andSet-Cookie2 headers in theresponse argument, and store cookiesas appropriate (subject to theCookiePolicy.set_ok() method's approval).

Theresponse object (usually the result of a call tourllib.request.urlopen(), or similar) should support aninfo()method, which returns anemail.message.Message instance.

Therequest object (usually aurllib.request.Request instance)must support the methodget_full_url() and the attributeshost,unverifiable andorigin_req_host,as documented byurllib.request. The request is used to setdefault values for cookie-attributes as well as for checking that thecookie is allowed to be set.

在 3.3 版的變更:request object needsorigin_req_host attribute. Dependency on adeprecated methodget_origin_req_host() has been removed.

CookieJar.set_policy(policy)¶

Set theCookiePolicy instance to be used.

CookieJar.make_cookies(response,request)¶

Return sequence ofCookie objects extracted fromresponse object.

See the documentation forextract_cookies() for the interfaces required oftheresponse andrequest arguments.

CookieJar.set_cookie_if_ok(cookie,request)¶

Set aCookie if policy says it's OK to do so.

CookieJar.set_cookie(cookie)¶

Set aCookie, without checking with policy to see whether or not itshould be set.

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

清除一些 cookies。

If invoked without arguments, clear all cookies. If given a single argument,only cookies belonging to thatdomain will be removed. If given two arguments,cookies belonging to the specifieddomain and URLpath are removed. Ifgiven three arguments, then the cookie with the specifieddomain,path andname is removed.

如果沒有符合的 cookie 存在，則引發KeyError。

CookieJar.clear_session_cookies()¶

Discard all session cookies.

Discards all contained cookies that have a truediscard attribute(usually because they had either nomax-age orexpires cookie-attribute,or an explicitdiscard cookie-attribute). For interactive browsers, the endof a session usually corresponds to closing the browser window.

Note that thesave() method won't save session cookies anyway, unless youask otherwise by passing a trueignore_discard argument.

FileCookieJar implements the following additional methods:

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

將 cookies 儲存到檔案中。

This base class raisesNotImplementedError. Subclasses may leave thismethod unimplemented.

filename is the name of file in which to save cookies. Iffilename is notspecified,self.filename is used (whose default is the value passed tothe constructor, if any); ifself.filename isNone,ValueError is raised.

ignore_discard: save even cookies set to be discarded.ignore_expires: saveeven cookies that have expired

The file is overwritten if it already exists, thus wiping all the cookies itcontains. Saved cookies can be restored later using theload() orrevert() methods.

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

從檔案中載入 cookies。

舊的 cookies 會被保留，除非被新載入的 cookies 覆蓋。

引數與save() 相同。

The named file must be in the format understood by the class, orLoadError will be raised. Also,OSError may be raised, forexample if the file does not exist.

在 3.3 版的變更:以前會引發IOError，現在它是OSError 的別名。

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

Clear all cookies and reload cookies from a saved file.

revert() can raise the same exceptions asload(). If there is afailure, the object's state will not be altered.

FileCookieJar 實例擁有以下公開屬性：

FileCookieJar.filename¶

Filename of default file in which to keep cookies. This attribute may beassigned to.

FileCookieJar.delayload¶

If true, load cookies lazily from disk. This attribute should not be assignedto. This is only a hint, since this only affects performance, not behaviour(unless the cookies on disk are changing). ACookieJar object mayignore it. None of theFileCookieJar classes included in the standardlibrary lazily loads cookies.

FileCookieJar subclasses and co-operation with web browsers¶

The followingCookieJar subclasses are provided for reading andwriting.

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

AFileCookieJar that can load from and save cookies to disk in theMozillacookies.txt file format (which is also used by curl and the Lynxand Netscape browsers).

備註

This loses information aboutRFC 2965 cookies, and also about newer ornon-standard cookie-attributes such asport.

警告

Back up your cookies before saving if you have cookies whose loss / corruptionwould be inconvenient (there are some subtleties which may lead to slightchanges in the file over a load / save round-trip).

Also note that cookies saved while Mozilla is running will get clobbered byMozilla.

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

AFileCookieJar that can load from and save cookies to disk in formatcompatible with the libwww-perl library'sSet-Cookie3 file format. This isconvenient if you want to store cookies in a human-readable file.

在 3.8 版的變更:The filename parameter supports apath-like object.

CookiePolicy 物件¶

Objects implementing theCookiePolicy interface have the followingmethods:

CookiePolicy.set_ok(cookie,request)¶

Return boolean value indicating whether cookie should be accepted from server.

cookie is aCookie instance.request is an objectimplementing the interface defined by the documentation forCookieJar.extract_cookies().

CookiePolicy.return_ok(cookie,request)¶

Return boolean value indicating whether cookie should be returned to server.

cookie is aCookie instance.request is an objectimplementing the interface defined by the documentation forCookieJar.add_cookie_header().

CookiePolicy.domain_return_ok(domain,request)¶

ReturnFalse if cookies should not be returned, given cookie domain.

This method is an optimization. It removes the need for checking every cookiewith a particular domain (which might involve reading many files). Returningtrue fromdomain_return_ok() andpath_return_ok() leaves all thework toreturn_ok().

Ifdomain_return_ok() returns true for the cookie domain,path_return_ok() is called for the cookie path. Otherwise,path_return_ok() andreturn_ok() are never called for that cookiedomain. Ifpath_return_ok() returns true,return_ok() is calledwith theCookie object itself for a full check. Otherwise,return_ok() is never called for that cookie path.

Note thatdomain_return_ok() is called for everycookie domain, not justfor therequest domain. For example, the function might be called with both".example.com" and"www.example.com" if the request domain is"www.example.com". The same goes forpath_return_ok().

Therequest argument is as documented forreturn_ok().

CookiePolicy.path_return_ok(path,request)¶

ReturnFalse if cookies should not be returned, given cookie path.

關於domain_return_ok() 請見文件。

In addition to implementing the methods above, implementations of theCookiePolicy interface must also supply the following attributes,indicating which protocols should be used, and how. All of these attributes maybe assigned to.

CookiePolicy.netscape¶

實作 Netscape 協定。

CookiePolicy.rfc2965¶

實作RFC 2965 協定。

CookiePolicy.hide_cookie2¶

Don't addCookie2 header to requests (the presence of this headerindicates to the server that we understandRFC 2965 cookies).

The most useful way to define aCookiePolicy class is by subclassingfromDefaultCookiePolicy and overriding some or all of the methodsabove.CookiePolicy itself may be used as a 'null policy' to allowsetting and receiving any and all cookies (this is unlikely to be useful).

DefaultCookiePolicy 物件¶

Implements the standard rules for accepting and returning cookies.

BothRFC 2965 and Netscape cookies are covered. RFC 2965 handling is switchedoff by default.

The easiest way to provide your own policy is to override this class and callits methods in your overridden implementations before adding your own additionalchecks:

importhttp.cookiejarclassMyCookiePolicy(http.cookiejar.DefaultCookiePolicy):defset_ok(self,cookie,request):ifnothttp.cookiejar.DefaultCookiePolicy.set_ok(self,cookie,request):returnFalseifi_dont_want_to_store_this_cookie(cookie):returnFalsereturnTrue

In addition to the features required to implement theCookiePolicyinterface, this class allows you to block and allow domains from setting andreceiving cookies. There are also some strictness switches that allow you totighten up the rather loose Netscape protocol rules a little bit (at the cost ofblocking some benign cookies).

A domain blocklist and allowlist is provided (both off by default). Only domainsnot in the blocklist and present in the allowlist (if the allowlist is active)participate in cookie setting and returning. Use theblocked_domainsconstructor argument, andblocked_domains() andset_blocked_domains() methods (and the corresponding argument and methodsforallowed_domains). If you set an allowlist, you can turn it off again bysetting it toNone.

Domains in block or allow lists that do not start with a dot must equal thecookie domain to be matched. For example,"example.com" matches a blocklistentry of"example.com", but"www.example.com" does not. Domains that dostart with a dot are matched by more specific domains too. For example, both"www.example.com" and"www.coyote.example.com" match".example.com"(but"example.com" itself does not). IP addresses are an exception, andmust match exactly. For example, if blocked_domains contains"192.168.1.2"and".168.1.2", 192.168.1.2 is blocked, but 193.168.1.2 is not.

DefaultCookiePolicy implements the following additional methods:

DefaultCookiePolicy.blocked_domains()¶

Return the sequence of blocked domains (as a tuple).

DefaultCookiePolicy.set_blocked_domains(blocked_domains)¶

Set the sequence of blocked domains.

DefaultCookiePolicy.is_blocked(domain)¶

ReturnTrue ifdomain is on the blocklist for setting or receivingcookies.

DefaultCookiePolicy.allowed_domains()¶

ReturnNone, or the sequence of allowed domains (as a tuple).

DefaultCookiePolicy.set_allowed_domains(allowed_domains)¶

Set the sequence of allowed domains, orNone.

DefaultCookiePolicy.is_not_allowed(domain)¶

ReturnTrue ifdomain is not on the allowlist for setting or receivingcookies.

DefaultCookiePolicy instances have the following attributes, which areall initialised from the constructor arguments of the same name, and which mayall be assigned to.

DefaultCookiePolicy.rfc2109_as_netscape¶

If true, request that theCookieJar instance downgradeRFC 2109 cookies(ie. cookies received in aSet-Cookie header with a versioncookie-attribute of 1) to Netscape cookies by setting the version attribute oftheCookie instance to 0. The default value isNone, in whichcase RFC 2109 cookies are downgraded if and only ifRFC 2965 handling is turnedoff. Therefore, RFC 2109 cookies are downgraded by default.

General strictness switches:

DefaultCookiePolicy.strict_domain¶

Don't allow sites to set two-component domains with country-code top-leveldomains like.co.uk,.gov.uk,.co.nz.etc. This is far from perfectand isn't guaranteed to work!

RFC 2965 protocol strictness switches:

DefaultCookiePolicy.strict_rfc2965_unverifiable¶

FollowRFC 2965 rules on unverifiable transactions (usually, an unverifiabletransaction is one resulting from a redirect or a request for an image hosted onanother site). If this is false, cookies arenever blocked on the basis ofverifiability

Netscape protocol strictness switches:

DefaultCookiePolicy.strict_ns_unverifiable¶

ApplyRFC 2965 rules on unverifiable transactions even to Netscape cookies.

DefaultCookiePolicy.strict_ns_domain¶

Flags indicating how strict to be with domain-matching rules for Netscapecookies. See below for acceptable values.

DefaultCookiePolicy.strict_ns_set_initial_dollar¶

Ignore cookies in Set-Cookie: headers that have names starting with'$'.

DefaultCookiePolicy.strict_ns_set_path¶

Don't allow setting cookies whose path doesn't path-match request URI.

strict_ns_domain is a collection of flags. Its value is constructed byor-ing together (for example,DomainStrictNoDots|DomainStrictNonDomain meansboth flags are set).

DefaultCookiePolicy.DomainStrictNoDots¶

When setting cookies, the 'host prefix' must not contain a dot (eg.www.foo.bar.com can't set a cookie for.bar.com, becausewww.foocontains a dot).

DefaultCookiePolicy.DomainStrictNonDomain¶

Cookies that did not explicitly specify adomain cookie-attribute can onlybe returned to a domain equal to the domain that set the cookie (eg.spam.example.com won't be returned cookies fromexample.com that had nodomain cookie-attribute).

DefaultCookiePolicy.DomainRFC2965Match¶

When setting cookies, require a fullRFC 2965 domain-match.

The following attributes are provided for convenience, and are the most usefulcombinations of the above flags:

DefaultCookiePolicy.DomainLiberal¶

Equivalent to 0 (ie. all of the above Netscape domain strictness flags switchedoff).

DefaultCookiePolicy.DomainStrict¶

等價於DomainStrictNoDots|DomainStrictNonDomain。

Cookie 物件¶

Cookie instances have Python attributes roughly corresponding to thestandard cookie-attributes specified in the various cookie standards. Thecorrespondence is not one-to-one, because there are complicated rules forassigning default values, because themax-age andexpirescookie-attributes contain equivalent information, and becauseRFC 2109 cookiesmay be 'downgraded' byhttp.cookiejar from version 1 to version 0 (Netscape)cookies.

Assignment to these attributes should not be necessary other than in rarecircumstances in aCookiePolicy method. The class does not enforceinternal consistency, so you should know what you're doing if you do that.

Cookie.version¶

Integer orNone. Netscape cookies haveversion 0.RFC 2965 andRFC 2109 cookies have aversion cookie-attribute of 1. However, note thathttp.cookiejar may 'downgrade' RFC 2109 cookies to Netscape cookies, in whichcaseversion is 0.

Cookie.name¶

Cookie name (a string).

Cookie.value¶

Cookie value (a string), orNone.

Cookie.port¶

String representing a port or a set of ports (eg. '80', or '80,8080'), orNone.

Cookie.domain¶

Cookie domain (a string).

Cookie.path¶

Cookie path (a string, eg.'/acme/rocket_launchers').

Cookie.secure¶

True if cookie should only be returned over a secure connection.

Cookie.expires¶

Integer expiry date in seconds since epoch, orNone. See also theis_expired() method.

Cookie.discard¶

True if this is a session cookie.

Cookie.comment¶

String comment from the server explaining the function of this cookie, orNone.

Cookie.comment_url¶

URL linking to a comment from the server explaining the function of this cookie,orNone.

Cookie.rfc2109¶

True if this cookie was received as anRFC 2109 cookie (ie. the cookiearrived in aSet-Cookie header, and the value of the Versioncookie-attribute in that header was 1). This attribute is provided becausehttp.cookiejar may 'downgrade' RFC 2109 cookies to Netscape cookies, inwhich caseversion is 0.

Cookie.port_specified¶

True if a port or set of ports was explicitly specified by the server (in theSet-Cookie /Set-Cookie2 header).

Cookie.domain_specified¶

True if a domain was explicitly specified by the server.

Cookie.domain_initial_dot¶

True if the domain explicitly specified by the server began with a dot('.').

Cookies may have additional non-standard cookie-attributes. These may beaccessed using the following methods:

Cookie.has_nonstandard_attr(name)¶

ReturnTrue if cookie has the named cookie-attribute.

Cookie.get_nonstandard_attr(name,default=None)¶

If cookie has the named cookie-attribute, return its value. Otherwise, returndefault.

Cookie.set_nonstandard_attr(name,value)¶

Set the value of the named cookie-attribute.

TheCookie class also defines the following method:

Cookie.is_expired(now=None)¶

True if cookie has passed the time at which the server requested it shouldexpire. Ifnow is given (in seconds since the epoch), return whether thecookie has expired at the specified time.

範例¶

The first example shows the most common usage ofhttp.cookiejar:

importhttp.cookiejar,urllib.requestcj=http.cookiejar.CookieJar()opener=urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))r=opener.open("http://example.com/")

This example illustrates how to open a URL using your Netscape, Mozilla, or Lynxcookies (assumes Unix/Netscape convention for location of the cookies file):

importos,http.cookiejar,urllib.requestcj=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/")

The next example illustrates the use ofDefaultCookiePolicy. Turn onRFC 2965 cookies, be more strict about domains when setting and returningNetscape cookies, and block some domains from setting cookies or having themreturned:

importurllib.requestfromhttp.cookiejarimportCookieJar,DefaultCookiePolicypolicy=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/")