Debian Codegraph @

Doc/library/http.cookiejar.rst

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