|
1 :mod:`cookielib` --- Cookie handling for HTTP clients |
|
2 ===================================================== |
|
3 |
|
4 .. module:: cookielib |
|
5 :synopsis: Classes for automatic handling of HTTP cookies. |
|
6 .. moduleauthor:: John J. Lee <jjl@pobox.com> |
|
7 .. sectionauthor:: John J. Lee <jjl@pobox.com> |
|
8 |
|
9 .. note:: |
|
10 The :mod:`cookielib` module has been renamed to :mod:`http.cookiejar` in |
|
11 Python 3.0. The :term:`2to3` tool will automatically adapt imports when |
|
12 converting your sources to 3.0. |
|
13 |
|
14 |
|
15 .. versionadded:: 2.4 |
|
16 |
|
17 |
|
18 |
|
19 The :mod:`cookielib` module defines classes for automatic handling of HTTP |
|
20 cookies. It is useful for accessing web sites that require small pieces of data |
|
21 -- :dfn:`cookies` -- to be set on the client machine by an HTTP response from a |
|
22 web server, and then returned to the server in later HTTP requests. |
|
23 |
|
24 Both the regular Netscape cookie protocol and the protocol defined by |
|
25 :rfc:`2965` are handled. RFC 2965 handling is switched off by default. |
|
26 :rfc:`2109` cookies are parsed as Netscape cookies and subsequently treated |
|
27 either as Netscape or RFC 2965 cookies according to the 'policy' in effect. |
|
28 Note that the great majority of cookies on the Internet are Netscape cookies. |
|
29 :mod:`cookielib` attempts to follow the de-facto Netscape cookie protocol (which |
|
30 differs substantially from that set out in the original Netscape specification), |
|
31 including taking note of the ``max-age`` and ``port`` cookie-attributes |
|
32 introduced with RFC 2965. |
|
33 |
|
34 .. note:: |
|
35 |
|
36 The various named parameters found in :mailheader:`Set-Cookie` and |
|
37 :mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are |
|
38 conventionally referred to as :dfn:`attributes`. To distinguish them from |
|
39 Python attributes, the documentation for this module uses the term |
|
40 :dfn:`cookie-attribute` instead. |
|
41 |
|
42 |
|
43 The module defines the following exception: |
|
44 |
|
45 |
|
46 .. exception:: LoadError |
|
47 |
|
48 Instances of :class:`FileCookieJar` raise this exception on failure to load |
|
49 cookies from a file. |
|
50 |
|
51 .. note:: |
|
52 |
|
53 For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`), |
|
54 :exc:`LoadError` is a subclass of :exc:`IOError`. |
|
55 |
|
56 |
|
57 The following classes are provided: |
|
58 |
|
59 |
|
60 .. class:: CookieJar(policy=None) |
|
61 |
|
62 *policy* is an object implementing the :class:`CookiePolicy` interface. |
|
63 |
|
64 The :class:`CookieJar` class stores HTTP cookies. It extracts cookies from HTTP |
|
65 requests, and returns them in HTTP responses. :class:`CookieJar` instances |
|
66 automatically expire contained cookies when necessary. Subclasses are also |
|
67 responsible for storing and retrieving cookies from a file or database. |
|
68 |
|
69 |
|
70 .. class:: FileCookieJar(filename, delayload=None, policy=None) |
|
71 |
|
72 *policy* is an object implementing the :class:`CookiePolicy` interface. For the |
|
73 other arguments, see the documentation for the corresponding attributes. |
|
74 |
|
75 A :class:`CookieJar` which can load cookies from, and perhaps save cookies to, a |
|
76 file on disk. Cookies are **NOT** loaded from the named file until either the |
|
77 :meth:`load` or :meth:`revert` method is called. Subclasses of this class are |
|
78 documented in section :ref:`file-cookie-jar-classes`. |
|
79 |
|
80 |
|
81 .. class:: CookiePolicy() |
|
82 |
|
83 This class is responsible for deciding whether each cookie should be accepted |
|
84 from / returned to the server. |
|
85 |
|
86 |
|
87 .. class:: 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 ) |
|
88 |
|
89 Constructor arguments should be passed as keyword arguments only. |
|
90 *blocked_domains* is a sequence of domain names that we never accept cookies |
|
91 from, nor return cookies to. *allowed_domains* if not :const:`None`, this is a |
|
92 sequence of the only domains for which we accept and return cookies. For all |
|
93 other arguments, see the documentation for :class:`CookiePolicy` and |
|
94 :class:`DefaultCookiePolicy` objects. |
|
95 |
|
96 :class:`DefaultCookiePolicy` implements the standard accept / reject rules for |
|
97 Netscape and RFC 2965 cookies. By default, RFC 2109 cookies (ie. cookies |
|
98 received in a :mailheader:`Set-Cookie` header with a version cookie-attribute of |
|
99 1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling |
|
100 is turned off or :attr:`rfc2109_as_netscape` is True, RFC 2109 cookies are |
|
101 'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by |
|
102 setting the :attr:`version` attribute of the :class:`Cookie` instance to 0. |
|
103 :class:`DefaultCookiePolicy` also provides some parameters to allow some |
|
104 fine-tuning of policy. |
|
105 |
|
106 |
|
107 .. class:: Cookie() |
|
108 |
|
109 This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is not |
|
110 expected that users of :mod:`cookielib` construct their own :class:`Cookie` |
|
111 instances. Instead, if necessary, call :meth:`make_cookies` on a |
|
112 :class:`CookieJar` instance. |
|
113 |
|
114 |
|
115 .. seealso:: |
|
116 |
|
117 Module :mod:`urllib2` |
|
118 URL opening with automatic cookie handling. |
|
119 |
|
120 Module :mod:`Cookie` |
|
121 HTTP cookie classes, principally useful for server-side code. The |
|
122 :mod:`cookielib` and :mod:`Cookie` modules do not depend on each other. |
|
123 |
|
124 http://wwwsearch.sf.net/ClientCookie/ |
|
125 Extensions to this module, including a class for reading Microsoft Internet |
|
126 Explorer cookies on Windows. |
|
127 |
|
128 http://wp.netscape.com/newsref/std/cookie_spec.html |
|
129 The specification of the original Netscape cookie protocol. Though this is |
|
130 still the dominant protocol, the 'Netscape cookie protocol' implemented by all |
|
131 the major browsers (and :mod:`cookielib`) only bears a passing resemblance to |
|
132 the one sketched out in ``cookie_spec.html``. |
|
133 |
|
134 :rfc:`2109` - HTTP State Management Mechanism |
|
135 Obsoleted by RFC 2965. Uses :mailheader:`Set-Cookie` with version=1. |
|
136 |
|
137 :rfc:`2965` - HTTP State Management Mechanism |
|
138 The Netscape protocol with the bugs fixed. Uses :mailheader:`Set-Cookie2` in |
|
139 place of :mailheader:`Set-Cookie`. Not widely used. |
|
140 |
|
141 http://kristol.org/cookie/errata.html |
|
142 Unfinished errata to RFC 2965. |
|
143 |
|
144 :rfc:`2964` - Use of HTTP State Management |
|
145 |
|
146 .. _cookie-jar-objects: |
|
147 |
|
148 CookieJar and FileCookieJar Objects |
|
149 ----------------------------------- |
|
150 |
|
151 :class:`CookieJar` objects support the :term:`iterator` protocol for iterating over |
|
152 contained :class:`Cookie` objects. |
|
153 |
|
154 :class:`CookieJar` has the following methods: |
|
155 |
|
156 |
|
157 .. method:: CookieJar.add_cookie_header(request) |
|
158 |
|
159 Add correct :mailheader:`Cookie` header to *request*. |
|
160 |
|
161 If policy allows (ie. the :attr:`rfc2965` and :attr:`hide_cookie2` attributes of |
|
162 the :class:`CookieJar`'s :class:`CookiePolicy` instance are true and false |
|
163 respectively), the :mailheader:`Cookie2` header is also added when appropriate. |
|
164 |
|
165 The *request* object (usually a :class:`urllib2.Request` instance) must support |
|
166 the methods :meth:`get_full_url`, :meth:`get_host`, :meth:`get_type`, |
|
167 :meth:`unverifiable`, :meth:`get_origin_req_host`, :meth:`has_header`, |
|
168 :meth:`get_header`, :meth:`header_items`, and :meth:`add_unredirected_header`,as |
|
169 documented by :mod:`urllib2`. |
|
170 |
|
171 |
|
172 .. method:: CookieJar.extract_cookies(response, request) |
|
173 |
|
174 Extract cookies from HTTP *response* and store them in the :class:`CookieJar`, |
|
175 where allowed by policy. |
|
176 |
|
177 The :class:`CookieJar` will look for allowable :mailheader:`Set-Cookie` and |
|
178 :mailheader:`Set-Cookie2` headers in the *response* argument, and store cookies |
|
179 as appropriate (subject to the :meth:`CookiePolicy.set_ok` method's approval). |
|
180 |
|
181 The *response* object (usually the result of a call to :meth:`urllib2.urlopen`, |
|
182 or similar) should support an :meth:`info` method, which returns an object with |
|
183 a :meth:`getallmatchingheaders` method (usually a :class:`mimetools.Message` |
|
184 instance). |
|
185 |
|
186 The *request* object (usually a :class:`urllib2.Request` instance) must support |
|
187 the methods :meth:`get_full_url`, :meth:`get_host`, :meth:`unverifiable`, and |
|
188 :meth:`get_origin_req_host`, as documented by :mod:`urllib2`. The request is |
|
189 used to set default values for cookie-attributes as well as for checking that |
|
190 the cookie is allowed to be set. |
|
191 |
|
192 |
|
193 .. method:: CookieJar.set_policy(policy) |
|
194 |
|
195 Set the :class:`CookiePolicy` instance to be used. |
|
196 |
|
197 |
|
198 .. method:: CookieJar.make_cookies(response, request) |
|
199 |
|
200 Return sequence of :class:`Cookie` objects extracted from *response* object. |
|
201 |
|
202 See the documentation for :meth:`extract_cookies` for the interfaces required of |
|
203 the *response* and *request* arguments. |
|
204 |
|
205 |
|
206 .. method:: CookieJar.set_cookie_if_ok(cookie, request) |
|
207 |
|
208 Set a :class:`Cookie` if policy says it's OK to do so. |
|
209 |
|
210 |
|
211 .. method:: CookieJar.set_cookie(cookie) |
|
212 |
|
213 Set a :class:`Cookie`, without checking with policy to see whether or not it |
|
214 should be set. |
|
215 |
|
216 |
|
217 .. method:: CookieJar.clear([domain[, path[, name]]]) |
|
218 |
|
219 Clear some cookies. |
|
220 |
|
221 If invoked without arguments, clear all cookies. If given a single argument, |
|
222 only cookies belonging to that *domain* will be removed. If given two arguments, |
|
223 cookies belonging to the specified *domain* and URL *path* are removed. If |
|
224 given three arguments, then the cookie with the specified *domain*, *path* and |
|
225 *name* is removed. |
|
226 |
|
227 Raises :exc:`KeyError` if no matching cookie exists. |
|
228 |
|
229 |
|
230 .. method:: CookieJar.clear_session_cookies() |
|
231 |
|
232 Discard all session cookies. |
|
233 |
|
234 Discards all contained cookies that have a true :attr:`discard` attribute |
|
235 (usually because they had either no ``max-age`` or ``expires`` cookie-attribute, |
|
236 or an explicit ``discard`` cookie-attribute). For interactive browsers, the end |
|
237 of a session usually corresponds to closing the browser window. |
|
238 |
|
239 Note that the :meth:`save` method won't save session cookies anyway, unless you |
|
240 ask otherwise by passing a true *ignore_discard* argument. |
|
241 |
|
242 :class:`FileCookieJar` implements the following additional methods: |
|
243 |
|
244 |
|
245 .. method:: FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False) |
|
246 |
|
247 Save cookies to a file. |
|
248 |
|
249 This base class raises :exc:`NotImplementedError`. Subclasses may leave this |
|
250 method unimplemented. |
|
251 |
|
252 *filename* is the name of file in which to save cookies. If *filename* is not |
|
253 specified, :attr:`self.filename` is used (whose default is the value passed to |
|
254 the constructor, if any); if :attr:`self.filename` is :const:`None`, |
|
255 :exc:`ValueError` is raised. |
|
256 |
|
257 *ignore_discard*: save even cookies set to be discarded. *ignore_expires*: save |
|
258 even cookies that have expired |
|
259 |
|
260 The file is overwritten if it already exists, thus wiping all the cookies it |
|
261 contains. Saved cookies can be restored later using the :meth:`load` or |
|
262 :meth:`revert` methods. |
|
263 |
|
264 |
|
265 .. method:: FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False) |
|
266 |
|
267 Load cookies from a file. |
|
268 |
|
269 Old cookies are kept unless overwritten by newly loaded ones. |
|
270 |
|
271 Arguments are as for :meth:`save`. |
|
272 |
|
273 The named file must be in the format understood by the class, or |
|
274 :exc:`LoadError` will be raised. Also, :exc:`IOError` may be raised, for |
|
275 example if the file does not exist. |
|
276 |
|
277 .. note:: |
|
278 |
|
279 For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`), |
|
280 :exc:`LoadError` is a subclass of :exc:`IOError`. |
|
281 |
|
282 |
|
283 .. method:: FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False) |
|
284 |
|
285 Clear all cookies and reload cookies from a saved file. |
|
286 |
|
287 :meth:`revert` can raise the same exceptions as :meth:`load`. If there is a |
|
288 failure, the object's state will not be altered. |
|
289 |
|
290 :class:`FileCookieJar` instances have the following public attributes: |
|
291 |
|
292 |
|
293 .. attribute:: FileCookieJar.filename |
|
294 |
|
295 Filename of default file in which to keep cookies. This attribute may be |
|
296 assigned to. |
|
297 |
|
298 |
|
299 .. attribute:: FileCookieJar.delayload |
|
300 |
|
301 If true, load cookies lazily from disk. This attribute should not be assigned |
|
302 to. This is only a hint, since this only affects performance, not behaviour |
|
303 (unless the cookies on disk are changing). A :class:`CookieJar` object may |
|
304 ignore it. None of the :class:`FileCookieJar` classes included in the standard |
|
305 library lazily loads cookies. |
|
306 |
|
307 |
|
308 .. _file-cookie-jar-classes: |
|
309 |
|
310 FileCookieJar subclasses and co-operation with web browsers |
|
311 ----------------------------------------------------------- |
|
312 |
|
313 The following :class:`CookieJar` subclasses are provided for reading and writing |
|
314 . Further :class:`CookieJar` subclasses, including one that reads Microsoft |
|
315 Internet Explorer cookies, are available at |
|
316 http://wwwsearch.sf.net/ClientCookie/. |
|
317 |
|
318 |
|
319 .. class:: MozillaCookieJar(filename, delayload=None, policy=None) |
|
320 |
|
321 A :class:`FileCookieJar` that can load from and save cookies to disk in the |
|
322 Mozilla ``cookies.txt`` file format (which is also used by the Lynx and Netscape |
|
323 browsers). |
|
324 |
|
325 .. note:: |
|
326 |
|
327 Version 3 of the Firefox web browser no longer writes cookies in the |
|
328 ``cookies.txt`` file format. |
|
329 |
|
330 .. note:: |
|
331 |
|
332 This loses information about RFC 2965 cookies, and also about newer or |
|
333 non-standard cookie-attributes such as ``port``. |
|
334 |
|
335 .. warning:: |
|
336 |
|
337 Back up your cookies before saving if you have cookies whose loss / corruption |
|
338 would be inconvenient (there are some subtleties which may lead to slight |
|
339 changes in the file over a load / save round-trip). |
|
340 |
|
341 Also note that cookies saved while Mozilla is running will get clobbered by |
|
342 Mozilla. |
|
343 |
|
344 |
|
345 .. class:: LWPCookieJar(filename, delayload=None, policy=None) |
|
346 |
|
347 A :class:`FileCookieJar` that can load from and save cookies to disk in format |
|
348 compatible with the libwww-perl library's ``Set-Cookie3`` file format. This is |
|
349 convenient if you want to store cookies in a human-readable file. |
|
350 |
|
351 |
|
352 .. _cookie-policy-objects: |
|
353 |
|
354 CookiePolicy Objects |
|
355 -------------------- |
|
356 |
|
357 Objects implementing the :class:`CookiePolicy` interface have the following |
|
358 methods: |
|
359 |
|
360 |
|
361 .. method:: CookiePolicy.set_ok(cookie, request) |
|
362 |
|
363 Return boolean value indicating whether cookie should be accepted from server. |
|
364 |
|
365 *cookie* is a :class:`cookielib.Cookie` instance. *request* is an object |
|
366 implementing the interface defined by the documentation for |
|
367 :meth:`CookieJar.extract_cookies`. |
|
368 |
|
369 |
|
370 .. method:: CookiePolicy.return_ok(cookie, request) |
|
371 |
|
372 Return boolean value indicating whether cookie should be returned to server. |
|
373 |
|
374 *cookie* is a :class:`cookielib.Cookie` instance. *request* is an object |
|
375 implementing the interface defined by the documentation for |
|
376 :meth:`CookieJar.add_cookie_header`. |
|
377 |
|
378 |
|
379 .. method:: CookiePolicy.domain_return_ok(domain, request) |
|
380 |
|
381 Return false if cookies should not be returned, given cookie domain. |
|
382 |
|
383 This method is an optimization. It removes the need for checking every cookie |
|
384 with a particular domain (which might involve reading many files). Returning |
|
385 true from :meth:`domain_return_ok` and :meth:`path_return_ok` leaves all the |
|
386 work to :meth:`return_ok`. |
|
387 |
|
388 If :meth:`domain_return_ok` returns true for the cookie domain, |
|
389 :meth:`path_return_ok` is called for the cookie path. Otherwise, |
|
390 :meth:`path_return_ok` and :meth:`return_ok` are never called for that cookie |
|
391 domain. If :meth:`path_return_ok` returns true, :meth:`return_ok` is called |
|
392 with the :class:`Cookie` object itself for a full check. Otherwise, |
|
393 :meth:`return_ok` is never called for that cookie path. |
|
394 |
|
395 Note that :meth:`domain_return_ok` is called for every *cookie* domain, not just |
|
396 for the *request* domain. For example, the function might be called with both |
|
397 ``".example.com"`` and ``"www.example.com"`` if the request domain is |
|
398 ``"www.example.com"``. The same goes for :meth:`path_return_ok`. |
|
399 |
|
400 The *request* argument is as documented for :meth:`return_ok`. |
|
401 |
|
402 |
|
403 .. method:: CookiePolicy.path_return_ok(path, request) |
|
404 |
|
405 Return false if cookies should not be returned, given cookie path. |
|
406 |
|
407 See the documentation for :meth:`domain_return_ok`. |
|
408 |
|
409 In addition to implementing the methods above, implementations of the |
|
410 :class:`CookiePolicy` interface must also supply the following attributes, |
|
411 indicating which protocols should be used, and how. All of these attributes may |
|
412 be assigned to. |
|
413 |
|
414 |
|
415 .. attribute:: CookiePolicy.netscape |
|
416 |
|
417 Implement Netscape protocol. |
|
418 |
|
419 |
|
420 .. attribute:: CookiePolicy.rfc2965 |
|
421 |
|
422 Implement RFC 2965 protocol. |
|
423 |
|
424 |
|
425 .. attribute:: CookiePolicy.hide_cookie2 |
|
426 |
|
427 Don't add :mailheader:`Cookie2` header to requests (the presence of this header |
|
428 indicates to the server that we understand RFC 2965 cookies). |
|
429 |
|
430 The most useful way to define a :class:`CookiePolicy` class is by subclassing |
|
431 from :class:`DefaultCookiePolicy` and overriding some or all of the methods |
|
432 above. :class:`CookiePolicy` itself may be used as a 'null policy' to allow |
|
433 setting and receiving any and all cookies (this is unlikely to be useful). |
|
434 |
|
435 |
|
436 .. _default-cookie-policy-objects: |
|
437 |
|
438 DefaultCookiePolicy Objects |
|
439 --------------------------- |
|
440 |
|
441 Implements the standard rules for accepting and returning cookies. |
|
442 |
|
443 Both RFC 2965 and Netscape cookies are covered. RFC 2965 handling is switched |
|
444 off by default. |
|
445 |
|
446 The easiest way to provide your own policy is to override this class and call |
|
447 its methods in your overridden implementations before adding your own additional |
|
448 checks:: |
|
449 |
|
450 import cookielib |
|
451 class MyCookiePolicy(cookielib.DefaultCookiePolicy): |
|
452 def set_ok(self, cookie, request): |
|
453 if not cookielib.DefaultCookiePolicy.set_ok(self, cookie, request): |
|
454 return False |
|
455 if i_dont_want_to_store_this_cookie(cookie): |
|
456 return False |
|
457 return True |
|
458 |
|
459 In addition to the features required to implement the :class:`CookiePolicy` |
|
460 interface, this class allows you to block and allow domains from setting and |
|
461 receiving cookies. There are also some strictness switches that allow you to |
|
462 tighten up the rather loose Netscape protocol rules a little bit (at the cost of |
|
463 blocking some benign cookies). |
|
464 |
|
465 A domain blacklist and whitelist is provided (both off by default). Only domains |
|
466 not in the blacklist and present in the whitelist (if the whitelist is active) |
|
467 participate in cookie setting and returning. Use the *blocked_domains* |
|
468 constructor argument, and :meth:`blocked_domains` and |
|
469 :meth:`set_blocked_domains` methods (and the corresponding argument and methods |
|
470 for *allowed_domains*). If you set a whitelist, you can turn it off again by |
|
471 setting it to :const:`None`. |
|
472 |
|
473 Domains in block or allow lists that do not start with a dot must equal the |
|
474 cookie domain to be matched. For example, ``"example.com"`` matches a blacklist |
|
475 entry of ``"example.com"``, but ``"www.example.com"`` does not. Domains that do |
|
476 start with a dot are matched by more specific domains too. For example, both |
|
477 ``"www.example.com"`` and ``"www.coyote.example.com"`` match ``".example.com"`` |
|
478 (but ``"example.com"`` itself does not). IP addresses are an exception, and |
|
479 must match exactly. For example, if blocked_domains contains ``"192.168.1.2"`` |
|
480 and ``".168.1.2"``, 192.168.1.2 is blocked, but 193.168.1.2 is not. |
|
481 |
|
482 :class:`DefaultCookiePolicy` implements the following additional methods: |
|
483 |
|
484 |
|
485 .. method:: DefaultCookiePolicy.blocked_domains() |
|
486 |
|
487 Return the sequence of blocked domains (as a tuple). |
|
488 |
|
489 |
|
490 .. method:: DefaultCookiePolicy.set_blocked_domains(blocked_domains) |
|
491 |
|
492 Set the sequence of blocked domains. |
|
493 |
|
494 |
|
495 .. method:: DefaultCookiePolicy.is_blocked(domain) |
|
496 |
|
497 Return whether *domain* is on the blacklist for setting or receiving cookies. |
|
498 |
|
499 |
|
500 .. method:: DefaultCookiePolicy.allowed_domains() |
|
501 |
|
502 Return :const:`None`, or the sequence of allowed domains (as a tuple). |
|
503 |
|
504 |
|
505 .. method:: DefaultCookiePolicy.set_allowed_domains(allowed_domains) |
|
506 |
|
507 Set the sequence of allowed domains, or :const:`None`. |
|
508 |
|
509 |
|
510 .. method:: DefaultCookiePolicy.is_not_allowed(domain) |
|
511 |
|
512 Return whether *domain* is not on the whitelist for setting or receiving |
|
513 cookies. |
|
514 |
|
515 :class:`DefaultCookiePolicy` instances have the following attributes, which are |
|
516 all initialised from the constructor arguments of the same name, and which may |
|
517 all be assigned to. |
|
518 |
|
519 |
|
520 .. attribute:: DefaultCookiePolicy.rfc2109_as_netscape |
|
521 |
|
522 If true, request that the :class:`CookieJar` instance downgrade RFC 2109 cookies |
|
523 (ie. cookies received in a :mailheader:`Set-Cookie` header with a version |
|
524 cookie-attribute of 1) to Netscape cookies by setting the version attribute of |
|
525 the :class:`Cookie` instance to 0. The default value is :const:`None`, in which |
|
526 case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned |
|
527 off. Therefore, RFC 2109 cookies are downgraded by default. |
|
528 |
|
529 .. versionadded:: 2.5 |
|
530 |
|
531 General strictness switches: |
|
532 |
|
533 |
|
534 .. attribute:: DefaultCookiePolicy.strict_domain |
|
535 |
|
536 Don't allow sites to set two-component domains with country-code top-level |
|
537 domains like ``.co.uk``, ``.gov.uk``, ``.co.nz``.etc. This is far from perfect |
|
538 and isn't guaranteed to work! |
|
539 |
|
540 RFC 2965 protocol strictness switches: |
|
541 |
|
542 |
|
543 .. attribute:: DefaultCookiePolicy.strict_rfc2965_unverifiable |
|
544 |
|
545 Follow RFC 2965 rules on unverifiable transactions (usually, an unverifiable |
|
546 transaction is one resulting from a redirect or a request for an image hosted on |
|
547 another site). If this is false, cookies are *never* blocked on the basis of |
|
548 verifiability |
|
549 |
|
550 Netscape protocol strictness switches: |
|
551 |
|
552 |
|
553 .. attribute:: DefaultCookiePolicy.strict_ns_unverifiable |
|
554 |
|
555 apply RFC 2965 rules on unverifiable transactions even to Netscape cookies |
|
556 |
|
557 |
|
558 .. attribute:: DefaultCookiePolicy.strict_ns_domain |
|
559 |
|
560 Flags indicating how strict to be with domain-matching rules for Netscape |
|
561 cookies. See below for acceptable values. |
|
562 |
|
563 |
|
564 .. attribute:: DefaultCookiePolicy.strict_ns_set_initial_dollar |
|
565 |
|
566 Ignore cookies in Set-Cookie: headers that have names starting with ``'$'``. |
|
567 |
|
568 |
|
569 .. attribute:: DefaultCookiePolicy.strict_ns_set_path |
|
570 |
|
571 Don't allow setting cookies whose path doesn't path-match request URI. |
|
572 |
|
573 :attr:`strict_ns_domain` is a collection of flags. Its value is constructed by |
|
574 or-ing together (for example, ``DomainStrictNoDots|DomainStrictNonDomain`` means |
|
575 both flags are set). |
|
576 |
|
577 |
|
578 .. attribute:: DefaultCookiePolicy.DomainStrictNoDots |
|
579 |
|
580 When setting cookies, the 'host prefix' must not contain a dot (eg. |
|
581 ``www.foo.bar.com`` can't set a cookie for ``.bar.com``, because ``www.foo`` |
|
582 contains a dot). |
|
583 |
|
584 |
|
585 .. attribute:: DefaultCookiePolicy.DomainStrictNonDomain |
|
586 |
|
587 Cookies that did not explicitly specify a ``domain`` cookie-attribute can only |
|
588 be returned to a domain equal to the domain that set the cookie (eg. |
|
589 ``spam.example.com`` won't be returned cookies from ``example.com`` that had no |
|
590 ``domain`` cookie-attribute). |
|
591 |
|
592 |
|
593 .. attribute:: DefaultCookiePolicy.DomainRFC2965Match |
|
594 |
|
595 When setting cookies, require a full RFC 2965 domain-match. |
|
596 |
|
597 The following attributes are provided for convenience, and are the most useful |
|
598 combinations of the above flags: |
|
599 |
|
600 |
|
601 .. attribute:: DefaultCookiePolicy.DomainLiberal |
|
602 |
|
603 Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched |
|
604 off). |
|
605 |
|
606 |
|
607 .. attribute:: DefaultCookiePolicy.DomainStrict |
|
608 |
|
609 Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``. |
|
610 |
|
611 |
|
612 .. _cookielib-cookie-objects: |
|
613 |
|
614 Cookie Objects |
|
615 -------------- |
|
616 |
|
617 :class:`Cookie` instances have Python attributes roughly corresponding to the |
|
618 standard cookie-attributes specified in the various cookie standards. The |
|
619 correspondence is not one-to-one, because there are complicated rules for |
|
620 assigning default values, because the ``max-age`` and ``expires`` |
|
621 cookie-attributes contain equivalent information, and because RFC 2109 cookies |
|
622 may be 'downgraded' by :mod:`cookielib` from version 1 to version 0 (Netscape) |
|
623 cookies. |
|
624 |
|
625 Assignment to these attributes should not be necessary other than in rare |
|
626 circumstances in a :class:`CookiePolicy` method. The class does not enforce |
|
627 internal consistency, so you should know what you're doing if you do that. |
|
628 |
|
629 |
|
630 .. attribute:: Cookie.version |
|
631 |
|
632 Integer or :const:`None`. Netscape cookies have :attr:`version` 0. RFC 2965 and |
|
633 RFC 2109 cookies have a ``version`` cookie-attribute of 1. However, note that |
|
634 :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which |
|
635 case :attr:`version` is 0. |
|
636 |
|
637 |
|
638 .. attribute:: Cookie.name |
|
639 |
|
640 Cookie name (a string). |
|
641 |
|
642 |
|
643 .. attribute:: Cookie.value |
|
644 |
|
645 Cookie value (a string), or :const:`None`. |
|
646 |
|
647 |
|
648 .. attribute:: Cookie.port |
|
649 |
|
650 String representing a port or a set of ports (eg. '80', or '80,8080'), or |
|
651 :const:`None`. |
|
652 |
|
653 |
|
654 .. attribute:: Cookie.path |
|
655 |
|
656 Cookie path (a string, eg. ``'/acme/rocket_launchers'``). |
|
657 |
|
658 |
|
659 .. attribute:: Cookie.secure |
|
660 |
|
661 True if cookie should only be returned over a secure connection. |
|
662 |
|
663 |
|
664 .. attribute:: Cookie.expires |
|
665 |
|
666 Integer expiry date in seconds since epoch, or :const:`None`. See also the |
|
667 :meth:`is_expired` method. |
|
668 |
|
669 |
|
670 .. attribute:: Cookie.discard |
|
671 |
|
672 True if this is a session cookie. |
|
673 |
|
674 |
|
675 .. attribute:: Cookie.comment |
|
676 |
|
677 String comment from the server explaining the function of this cookie, or |
|
678 :const:`None`. |
|
679 |
|
680 |
|
681 .. attribute:: Cookie.comment_url |
|
682 |
|
683 URL linking to a comment from the server explaining the function of this cookie, |
|
684 or :const:`None`. |
|
685 |
|
686 |
|
687 .. attribute:: Cookie.rfc2109 |
|
688 |
|
689 True if this cookie was received as an RFC 2109 cookie (ie. the cookie |
|
690 arrived in a :mailheader:`Set-Cookie` header, and the value of the Version |
|
691 cookie-attribute in that header was 1). This attribute is provided because |
|
692 :mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in |
|
693 which case :attr:`version` is 0. |
|
694 |
|
695 .. versionadded:: 2.5 |
|
696 |
|
697 |
|
698 .. attribute:: Cookie.port_specified |
|
699 |
|
700 True if a port or set of ports was explicitly specified by the server (in the |
|
701 :mailheader:`Set-Cookie` / :mailheader:`Set-Cookie2` header). |
|
702 |
|
703 |
|
704 .. attribute:: Cookie.domain_specified |
|
705 |
|
706 True if a domain was explicitly specified by the server. |
|
707 |
|
708 |
|
709 .. attribute:: Cookie.domain_initial_dot |
|
710 |
|
711 True if the domain explicitly specified by the server began with a dot |
|
712 (``'.'``). |
|
713 |
|
714 Cookies may have additional non-standard cookie-attributes. These may be |
|
715 accessed using the following methods: |
|
716 |
|
717 |
|
718 .. method:: Cookie.has_nonstandard_attr(name) |
|
719 |
|
720 Return true if cookie has the named cookie-attribute. |
|
721 |
|
722 |
|
723 .. method:: Cookie.get_nonstandard_attr(name, default=None) |
|
724 |
|
725 If cookie has the named cookie-attribute, return its value. Otherwise, return |
|
726 *default*. |
|
727 |
|
728 |
|
729 .. method:: Cookie.set_nonstandard_attr(name, value) |
|
730 |
|
731 Set the value of the named cookie-attribute. |
|
732 |
|
733 The :class:`Cookie` class also defines the following method: |
|
734 |
|
735 |
|
736 .. method:: Cookie.is_expired([now=:const:`None`]) |
|
737 |
|
738 True if cookie has passed the time at which the server requested it should |
|
739 expire. If *now* is given (in seconds since the epoch), return whether the |
|
740 cookie has expired at the specified time. |
|
741 |
|
742 |
|
743 .. _cookielib-examples: |
|
744 |
|
745 Examples |
|
746 -------- |
|
747 |
|
748 The first example shows the most common usage of :mod:`cookielib`:: |
|
749 |
|
750 import cookielib, urllib2 |
|
751 cj = cookielib.CookieJar() |
|
752 opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj)) |
|
753 r = opener.open("http://example.com/") |
|
754 |
|
755 This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx |
|
756 cookies (assumes Unix/Netscape convention for location of the cookies file):: |
|
757 |
|
758 import os, cookielib, urllib2 |
|
759 cj = cookielib.MozillaCookieJar() |
|
760 cj.load(os.path.join(os.environ["HOME"], ".netscape/cookies.txt")) |
|
761 opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj)) |
|
762 r = opener.open("http://example.com/") |
|
763 |
|
764 The next example illustrates the use of :class:`DefaultCookiePolicy`. Turn on |
|
765 RFC 2965 cookies, be more strict about domains when setting and returning |
|
766 Netscape cookies, and block some domains from setting cookies or having them |
|
767 returned:: |
|
768 |
|
769 import urllib2 |
|
770 from cookielib import CookieJar, DefaultCookiePolicy |
|
771 policy = DefaultCookiePolicy( |
|
772 rfc2965=True, strict_ns_domain=Policy.DomainStrict, |
|
773 blocked_domains=["ads.net", ".ads.net"]) |
|
774 cj = CookieJar(policy) |
|
775 opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj)) |
|
776 r = opener.open("http://example.com/") |
|
777 |