/Doc/library/cookielib.rst

  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
 19The :mod:`cookielib` module defines classes for automatic handling of HTTP
 20cookies.  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
 22web server, and then returned to the server in later HTTP requests.
 23
 24Both 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
 27either as Netscape or RFC 2965 cookies according to the 'policy' in effect.
 28Note 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
 30differs substantially from that set out in the original Netscape specification),
 31including taking note of the ``max-age`` and ``port`` cookie-attributes
 32introduced 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
 43The 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
 57The 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
148CookieJar and FileCookieJar Objects
149-----------------------------------
150
151:class:`CookieJar` objects support the :term:`iterator` protocol for iterating over
152contained :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
310FileCookieJar subclasses and co-operation with web browsers
311-----------------------------------------------------------
312
313The following :class:`CookieJar` subclasses are provided for reading and writing
314.  Further :class:`CookieJar` subclasses, including one that reads Microsoft
315Internet Explorer cookies, are available at
316http://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
354CookiePolicy Objects
355--------------------
356
357Objects implementing the :class:`CookiePolicy` interface have the following
358methods:
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
409In addition to implementing the methods above, implementations of the
410:class:`CookiePolicy` interface must also supply the following attributes,
411indicating which protocols should be used, and how.  All of these attributes may
412be 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
430The most useful way to define a :class:`CookiePolicy` class is by subclassing
431from :class:`DefaultCookiePolicy` and overriding some or all of the methods
432above.  :class:`CookiePolicy` itself may be used as a 'null policy' to allow
433setting and receiving any and all cookies (this is unlikely to be useful).
434
435
436.. _default-cookie-policy-objects:
437
438DefaultCookiePolicy Objects
439---------------------------
440
441Implements the standard rules for accepting and returning cookies.
442
443Both RFC 2965 and Netscape cookies are covered.  RFC 2965 handling is switched
444off by default.
445
446The easiest way to provide your own policy is to override this class and call
447its methods in your overridden implementations before adding your own additional
448checks::
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
459In addition to the features required to implement the :class:`CookiePolicy`
460interface, this class allows you to block and allow domains from setting and
461receiving cookies.  There are also some strictness switches that allow you to
462tighten up the rather loose Netscape protocol rules a little bit (at the cost of
463blocking some benign cookies).
464
465A domain blacklist and whitelist is provided (both off by default). Only domains
466not in the blacklist and present in the whitelist (if the whitelist is active)
467participate in cookie setting and returning.  Use the *blocked_domains*
468constructor argument, and :meth:`blocked_domains` and
469:meth:`set_blocked_domains` methods (and the corresponding argument and methods
470for *allowed_domains*).  If you set a whitelist, you can turn it off again by
471setting it to :const:`None`.
472
473Domains in block or allow lists that do not start with a dot must equal the
474cookie domain to be matched.  For example, ``"example.com"`` matches a blacklist
475entry of ``"example.com"``, but ``"www.example.com"`` does not.  Domains that do
476start 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
479must match exactly.  For example, if blocked_domains contains ``"192.168.1.2"``
480and ``".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
516all initialised from the constructor arguments of the same name, and which may
517all 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
531General 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
540RFC 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
550Netscape 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
574or-ing together (for example, ``DomainStrictNoDots|DomainStrictNonDomain`` means
575both 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
597The following attributes are provided for convenience, and are the most useful
598combinations 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
614Cookie Objects
615--------------
616
617:class:`Cookie` instances have Python attributes roughly corresponding to the
618standard cookie-attributes specified in the various cookie standards.  The
619correspondence is not one-to-one, because there are complicated rules for
620assigning default values, because the ``max-age`` and ``expires``
621cookie-attributes contain equivalent information, and because RFC 2109 cookies
622may be 'downgraded' by :mod:`cookielib` from version 1 to version 0 (Netscape)
623cookies.
624
625Assignment to these attributes should not be necessary other than in rare
626circumstances in a :class:`CookiePolicy` method.  The class does not enforce
627internal 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
714Cookies may have additional non-standard cookie-attributes.  These may be
715accessed 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
733The :class:`Cookie` class also defines the following method:
734
735
736.. method:: Cookie.is_expired([now=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
745Examples
746--------
747
748The 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
755This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx
756cookies (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
764The next example illustrates the use of :class:`DefaultCookiePolicy`. Turn on
765RFC 2965 cookies, be more strict about domains when setting and returning
766Netscape cookies, and block some domains from setting cookies or having them
767returned::
768
769   import urllib2
770   from cookielib import CookieJar, DefaultCookiePolicy
771   policy = DefaultCookiePolicy(
772       rfc2965=True, strict_ns_domain=DefaultCookiePolicy.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