cpython/Doc/library/http.cookiejar.rst

771 lines
28 KiB
ReStructuredText
Raw Normal View History

2008-05-26 13:32:26 -03:00
:mod:`http.cookiejar` --- Cookie handling for HTTP clients
==========================================================
2007-08-15 11:28:22 -03:00
2008-05-26 13:32:26 -03:00
.. module:: http.cookiejar
2007-08-15 11:28:22 -03:00
:synopsis: Classes for automatic handling of HTTP cookies.
2007-08-15 11:28:22 -03:00
.. moduleauthor:: John J. Lee <jjl@pobox.com>
.. sectionauthor:: John J. Lee <jjl@pobox.com>
2011-01-27 16:38:46 -04:00
**Source code:** :source:`Lib/http/cookiejar.py`
--------------
2007-08-15 11:28:22 -03:00
2008-05-26 13:32:26 -03:00
The :mod:`http.cookiejar` module defines classes for automatic handling of HTTP
2007-08-15 11:28:22 -03:00
cookies. It is useful for accessing web sites that require small pieces of data
-- :dfn:`cookies` -- to be set on the client machine by an HTTP response from a
web server, and then returned to the server in later HTTP requests.
Both the regular Netscape cookie protocol and the protocol defined by
:rfc:`2965` are handled. RFC 2965 handling is switched off by default.
:rfc:`2109` cookies are parsed as Netscape cookies and subsequently treated
either as Netscape or RFC 2965 cookies according to the 'policy' in effect.
Note that the great majority of cookies on the internet are Netscape cookies.
2008-05-26 13:32:26 -03:00
:mod:`http.cookiejar` attempts to follow the de-facto Netscape cookie protocol (which
2007-08-15 11:28:22 -03:00
differs substantially from that set out in the original Netscape specification),
including taking note of the ``max-age`` and ``port`` cookie-attributes
introduced with RFC 2965.
.. note::
The various named parameters found in :mailheader:`Set-Cookie` and
:mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are
conventionally referred to as :dfn:`attributes`. To distinguish them from
Python attributes, the documentation for this module uses the term
:dfn:`cookie-attribute` instead.
The module defines the following exception:
.. exception:: LoadError
Instances of :class:`FileCookieJar` raise this exception on failure to load
2011-10-12 15:10:51 -03:00
cookies from a file. :exc:`LoadError` is a subclass of :exc:`OSError`.
.. versionchanged:: 3.3
LoadError was made a subclass of :exc:`OSError` instead of
:exc:`IOError`.
2007-08-15 11:28:22 -03:00
The following classes are provided:
.. class:: CookieJar(policy=None)
*policy* is an object implementing the :class:`CookiePolicy` interface.
The :class:`CookieJar` class stores HTTP cookies. It extracts cookies from HTTP
requests, and returns them in HTTP responses. :class:`CookieJar` instances
automatically expire contained cookies when necessary. Subclasses are also
responsible for storing and retrieving cookies from a file or database.
.. class:: FileCookieJar(filename=None, delayload=None, policy=None)
2007-08-15 11:28:22 -03:00
*policy* is an object implementing the :class:`CookiePolicy` interface. For the
other arguments, see the documentation for the corresponding attributes.
A :class:`CookieJar` which can load cookies from, and perhaps save cookies to, a
file on disk. Cookies are **NOT** loaded from the named file until either the
:meth:`load` or :meth:`revert` method is called. Subclasses of this class are
documented in section :ref:`file-cookie-jar-classes`.
This should not be initialized directly use its subclasses below instead.
.. versionchanged:: 3.8
The filename parameter supports a :term:`path-like object`.
2007-08-15 11:28:22 -03:00
.. class:: CookiePolicy()
This class is responsible for deciding whether each cookie should be accepted
from / returned to the server.
.. 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") )
2007-08-15 11:28:22 -03:00
Constructor arguments should be passed as keyword arguments only.
*blocked_domains* is a sequence of domain names that we never accept cookies
from, nor return cookies to. *allowed_domains* if not :const:`None`, this is a
sequence of the only domains for which we accept and return cookies.
*secure_protocols* is a sequence of protocols for which secure cookies can be
added to. By default *https* and *wss* (secure websocket) are considered
secure protocols. For all other arguments, see the documentation for
:class:`CookiePolicy` and :class:`DefaultCookiePolicy` objects.
2007-08-15 11:28:22 -03:00
:class:`DefaultCookiePolicy` implements the standard accept / reject rules for
Netscape and :rfc:`2965` cookies. By default, :rfc:`2109` cookies (ie. cookies
2007-08-15 11:28:22 -03:00
received in a :mailheader:`Set-Cookie` header with a version cookie-attribute of
1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling
is turned off or :attr:`rfc2109_as_netscape` is ``True``, RFC 2109 cookies are
2007-08-15 11:28:22 -03:00
'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by
setting the :attr:`version` attribute of the :class:`Cookie` instance to 0.
:class:`DefaultCookiePolicy` also provides some parameters to allow some
fine-tuning of policy.
.. class:: Cookie()
This class represents Netscape, :rfc:`2109` and :rfc:`2965` cookies. It is not
2008-05-26 13:32:26 -03:00
expected that users of :mod:`http.cookiejar` construct their own :class:`Cookie`
2007-08-15 11:28:22 -03:00
instances. Instead, if necessary, call :meth:`make_cookies` on a
:class:`CookieJar` instance.
.. seealso::
2008-06-23 08:44:14 -03:00
Module :mod:`urllib.request`
2007-08-15 11:28:22 -03:00
URL opening with automatic cookie handling.
2008-05-26 13:32:26 -03:00
Module :mod:`http.cookies`
2007-08-15 11:28:22 -03:00
HTTP cookie classes, principally useful for server-side code. The
2008-05-26 13:32:26 -03:00
:mod:`http.cookiejar` and :mod:`http.cookies` modules do not depend on each
other.
2007-08-15 11:28:22 -03:00
https://curl.se/rfc/cookie_spec.html
2007-08-15 11:28:22 -03:00
The specification of the original Netscape cookie protocol. Though this is
still the dominant protocol, the 'Netscape cookie protocol' implemented by all
2008-05-26 13:32:26 -03:00
the major browsers (and :mod:`http.cookiejar`) only bears a passing resemblance to
2007-08-15 11:28:22 -03:00
the one sketched out in ``cookie_spec.html``.
:rfc:`2109` - HTTP State Management Mechanism
Obsoleted by :rfc:`2965`. Uses :mailheader:`Set-Cookie` with version=1.
2007-08-15 11:28:22 -03:00
:rfc:`2965` - HTTP State Management Mechanism
The Netscape protocol with the bugs fixed. Uses :mailheader:`Set-Cookie2` in
place of :mailheader:`Set-Cookie`. Not widely used.
http://kristol.org/cookie/errata.html
Unfinished errata to :rfc:`2965`.
2007-08-15 11:28:22 -03:00
:rfc:`2964` - Use of HTTP State Management
.. _cookie-jar-objects:
CookieJar and FileCookieJar Objects
-----------------------------------
#1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Merged revisions 58221-58741 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r58221 | georg.brandl | 2007-09-20 10:57:59 -0700 (Thu, 20 Sep 2007) | 2 lines Patch #1181: add os.environ.clear() method. ........ r58225 | sean.reifschneider | 2007-09-20 23:33:28 -0700 (Thu, 20 Sep 2007) | 3 lines Issue1704287: "make install" fails unless you do "make" first. Make oldsharedmods and sharedmods in "libinstall". ........ r58232 | guido.van.rossum | 2007-09-22 13:18:03 -0700 (Sat, 22 Sep 2007) | 4 lines Patch # 188 by Philip Jenvey. Make tell() mark CRLF as a newline. With unit test. ........ r58242 | georg.brandl | 2007-09-24 10:55:47 -0700 (Mon, 24 Sep 2007) | 2 lines Fix typo and double word. ........ r58245 | georg.brandl | 2007-09-24 10:59:28 -0700 (Mon, 24 Sep 2007) | 2 lines #1196: document default radix for int(). ........ r58247 | georg.brandl | 2007-09-24 11:08:24 -0700 (Mon, 24 Sep 2007) | 2 lines #1177: accept 2xx responses for https too, not only http. ........ r58249 | andrew.kuchling | 2007-09-24 16:45:51 -0700 (Mon, 24 Sep 2007) | 1 line Remove stray odd character; grammar fix ........ r58250 | andrew.kuchling | 2007-09-24 16:46:28 -0700 (Mon, 24 Sep 2007) | 1 line Typo fix ........ r58251 | andrew.kuchling | 2007-09-24 17:09:42 -0700 (Mon, 24 Sep 2007) | 1 line Add various items ........ r58268 | vinay.sajip | 2007-09-26 22:34:45 -0700 (Wed, 26 Sep 2007) | 1 line Change to flush and close logic to fix #1760556. ........ r58269 | vinay.sajip | 2007-09-26 22:38:51 -0700 (Wed, 26 Sep 2007) | 1 line Change to basicConfig() to fix #1021. ........ r58270 | georg.brandl | 2007-09-26 23:26:58 -0700 (Wed, 26 Sep 2007) | 2 lines #1208: document match object's boolean value. ........ r58271 | vinay.sajip | 2007-09-26 23:56:13 -0700 (Wed, 26 Sep 2007) | 1 line Minor date change. ........ r58272 | vinay.sajip | 2007-09-27 00:35:10 -0700 (Thu, 27 Sep 2007) | 1 line Change to LogRecord.__init__() to fix #1206. Note that archaic use of type(x) == types.DictType is because of keeping 1.5.2 compatibility. While this is much less relevant these days, there probably needs to be a separate commit for removing all archaic constructs at the same time. ........ r58288 | brett.cannon | 2007-09-30 12:45:10 -0700 (Sun, 30 Sep 2007) | 9 lines tuple.__repr__ did not consider a reference loop as it is not possible from Python code; but it is possible from C. object.__str__ had the issue of not expecting a type to doing something within it's tp_str implementation that could trigger an infinite recursion, but it could in C code.. Both found thanks to BaseException and how it handles its repr. Closes issue #1686386. Thanks to Thomas Herve for taking an initial stab at coming up with a solution. ........ r58289 | brett.cannon | 2007-09-30 13:37:19 -0700 (Sun, 30 Sep 2007) | 3 lines Fix error introduced by r58288; if a tuple is length 0 return its repr and don't worry about any self-referring tuples. ........ r58294 | facundo.batista | 2007-10-02 10:01:24 -0700 (Tue, 02 Oct 2007) | 11 lines Made the various is_* operations return booleans. This was discussed with Cawlishaw by mail, and he basically confirmed that to these is_* operations, there's no need to return Decimal(0) and Decimal(1) if the language supports the False and True booleans. Also added a few tests for the these functions in extra.decTest, since they are mostly untested (apart from the doctests). Thanks Mark Dickinson ........ r58295 | facundo.batista | 2007-10-02 11:21:18 -0700 (Tue, 02 Oct 2007) | 4 lines Added a class to store the digits of log(10), so that they can be made available when necessary without recomputing. Thanks Mark Dickinson ........ r58299 | mark.summerfield | 2007-10-03 01:53:21 -0700 (Wed, 03 Oct 2007) | 4 lines Added note in footnote about string comparisons about unicodedata.normalize(). ........ r58304 | raymond.hettinger | 2007-10-03 14:18:11 -0700 (Wed, 03 Oct 2007) | 1 line enumerate() is no longer bounded to using sequences shorter than LONG_MAX. The possibility of overflow was sending some newsgroup posters into a tizzy. ........ r58305 | raymond.hettinger | 2007-10-03 17:20:27 -0700 (Wed, 03 Oct 2007) | 1 line itertools.count() no longer limited to sys.maxint. ........ r58306 | kurt.kaiser | 2007-10-03 18:49:54 -0700 (Wed, 03 Oct 2007) | 3 lines Assume that the user knows when he wants to end the line; don't insert something he didn't select or complete. ........ r58307 | kurt.kaiser | 2007-10-03 19:07:50 -0700 (Wed, 03 Oct 2007) | 2 lines Remove unused theme that was causing a fault in p3k. ........ r58308 | kurt.kaiser | 2007-10-03 19:09:17 -0700 (Wed, 03 Oct 2007) | 2 lines Clean up EditorWindow close. ........ r58309 | kurt.kaiser | 2007-10-03 19:53:07 -0700 (Wed, 03 Oct 2007) | 7 lines textView cleanup. Patch 1718043 Tal Einat. M idlelib/EditorWindow.py M idlelib/aboutDialog.py M idlelib/textView.py M idlelib/NEWS.txt ........ r58310 | kurt.kaiser | 2007-10-03 20:11:12 -0700 (Wed, 03 Oct 2007) | 3 lines configDialog cleanup. Patch 1730217 Tal Einat. ........ r58311 | neal.norwitz | 2007-10-03 23:00:48 -0700 (Wed, 03 Oct 2007) | 4 lines Coverity #151: Remove deadcode. All this code already exists above starting at line 653. ........ r58325 | fred.drake | 2007-10-04 19:46:12 -0700 (Thu, 04 Oct 2007) | 1 line wrap lines to <80 characters before fixing errors ........ r58326 | raymond.hettinger | 2007-10-04 19:47:07 -0700 (Thu, 04 Oct 2007) | 6 lines Add __asdict__() to NamedTuple and refine the docs. Add maxlen support to deque() and fixup docs. Partially fix __reduce__(). The None as a third arg was no longer supported. Still needs work on __reduce__() to handle recursive inputs. ........ r58327 | fred.drake | 2007-10-04 19:48:32 -0700 (Thu, 04 Oct 2007) | 3 lines move descriptions of ac_(in|out)_buffer_size to the right place http://bugs.python.org/issue1053 ........ r58329 | neal.norwitz | 2007-10-04 20:39:17 -0700 (Thu, 04 Oct 2007) | 3 lines dict could be NULL, so we need to XDECREF. Fix a compiler warning about passing a PyTypeObject* instead of PyObject*. ........ r58330 | neal.norwitz | 2007-10-04 20:41:19 -0700 (Thu, 04 Oct 2007) | 2 lines Fix Coverity #158: Check the correct variable. ........ r58332 | neal.norwitz | 2007-10-04 22:01:38 -0700 (Thu, 04 Oct 2007) | 7 lines Fix Coverity #159. This code was broken if save() returned a negative number since i contained a boolean value and then we compared i < 0 which should never be true. Will backport (assuming it's necessary) ........ r58334 | neal.norwitz | 2007-10-04 22:29:17 -0700 (Thu, 04 Oct 2007) | 1 line Add a note about fixing some more warnings found by Coverity. ........ r58338 | raymond.hettinger | 2007-10-05 12:07:31 -0700 (Fri, 05 Oct 2007) | 1 line Restore BEGIN/END THREADS macros which were squashed in the previous checkin ........ r58343 | gregory.p.smith | 2007-10-06 00:48:10 -0700 (Sat, 06 Oct 2007) | 3 lines Stab in the dark attempt to fix the test_bsddb3 failure on sparc and S-390 ubuntu buildbots. ........ r58344 | gregory.p.smith | 2007-10-06 00:51:59 -0700 (Sat, 06 Oct 2007) | 2 lines Allows BerkeleyDB 4.6.x >= 4.6.21 for the bsddb module. ........ r58348 | gregory.p.smith | 2007-10-06 08:47:37 -0700 (Sat, 06 Oct 2007) | 3 lines Use the host the author likely meant in the first place. pop.gmail.com is reliable. gmail.org is someones personal domain. ........ r58351 | neal.norwitz | 2007-10-06 12:16:28 -0700 (Sat, 06 Oct 2007) | 3 lines Ensure that this test will pass even if another test left an unwritable TESTFN. Also use the safe unlink in test_support instead of rolling our own here. ........ r58368 | georg.brandl | 2007-10-08 00:50:24 -0700 (Mon, 08 Oct 2007) | 3 lines #1123: fix the docs for the str.split(None, sep) case. Also expand a few other methods' docs, which had more info in the deprecated string module docs. ........ r58369 | georg.brandl | 2007-10-08 01:06:05 -0700 (Mon, 08 Oct 2007) | 2 lines Update docstring of sched, also remove an unused assignment. ........ r58370 | raymond.hettinger | 2007-10-08 02:14:28 -0700 (Mon, 08 Oct 2007) | 5 lines Add comments to NamedTuple code. Let the field spec be either a string or a non-string sequence (suggested by Martin Blais with use cases). Improve the error message in the case of a SyntaxError (caused by a duplicate field name). ........ r58371 | raymond.hettinger | 2007-10-08 02:56:29 -0700 (Mon, 08 Oct 2007) | 1 line Missed a line in the docs ........ r58372 | raymond.hettinger | 2007-10-08 03:11:51 -0700 (Mon, 08 Oct 2007) | 1 line Better variable names ........ r58376 | georg.brandl | 2007-10-08 07:12:47 -0700 (Mon, 08 Oct 2007) | 3 lines #1199: docs for tp_as_{number,sequence,mapping}, by Amaury Forgeot d'Arc. No need to merge this to py3k! ........ r58380 | raymond.hettinger | 2007-10-08 14:26:58 -0700 (Mon, 08 Oct 2007) | 1 line Eliminate camelcase function name ........ r58381 | andrew.kuchling | 2007-10-08 16:23:03 -0700 (Mon, 08 Oct 2007) | 1 line Eliminate camelcase function name ........ r58382 | raymond.hettinger | 2007-10-08 18:36:23 -0700 (Mon, 08 Oct 2007) | 1 line Make the error messages more specific ........ r58384 | gregory.p.smith | 2007-10-08 23:02:21 -0700 (Mon, 08 Oct 2007) | 10 lines Splits Modules/_bsddb.c up into bsddb.h and _bsddb.c and adds a C API object available as bsddb.db.api. This is based on the patch submitted by Duncan Grisby here: http://sourceforge.net/tracker/index.php?func=detail&aid=1551895&group_id=13900&atid=313900 See this thread for additional info: http://sourceforge.net/mailarchive/forum.php?thread_name=E1GAVDK-0002rk-Iw%40apasphere.com&forum_name=pybsddb-users It also cleans up the code a little by removing some ifdef/endifs for python prior to 2.1 and for unsupported Berkeley DB <= 3.2. ........ r58385 | gregory.p.smith | 2007-10-08 23:50:43 -0700 (Mon, 08 Oct 2007) | 5 lines Fix a double free when positioning a database cursor to a non-existant string key (and probably a few other situations with string keys). This was reported with a patch as pybsddb sourceforge bug 1708868 by jjjhhhlll at gmail. ........ r58386 | gregory.p.smith | 2007-10-09 00:19:11 -0700 (Tue, 09 Oct 2007) | 3 lines Use the highest cPickle protocol in bsddb.dbshelve. This comes from sourceforge pybsddb patch 1551443 by w_barnes. ........ r58394 | gregory.p.smith | 2007-10-09 11:26:02 -0700 (Tue, 09 Oct 2007) | 2 lines remove another sleepycat reference ........ r58396 | kurt.kaiser | 2007-10-09 12:31:30 -0700 (Tue, 09 Oct 2007) | 3 lines Allow interrupt only when executing user code in subprocess Patch 1225 Tal Einat modified from IDLE-Spoon. ........ r58399 | brett.cannon | 2007-10-09 17:07:50 -0700 (Tue, 09 Oct 2007) | 5 lines Remove file-level typedefs that were inconsistently used throughout the file. Just move over to the public API names. Closes issue1238. ........ r58401 | raymond.hettinger | 2007-10-09 17:26:46 -0700 (Tue, 09 Oct 2007) | 1 line Accept Jim Jewett's api suggestion to use None instead of -1 to indicate unbounded deques. ........ r58403 | kurt.kaiser | 2007-10-09 17:55:40 -0700 (Tue, 09 Oct 2007) | 2 lines Allow cursor color change w/o restart. Patch 1725576 Tal Einat. ........ r58404 | kurt.kaiser | 2007-10-09 18:06:47 -0700 (Tue, 09 Oct 2007) | 2 lines show paste if > 80 columns. Patch 1659326 Tal Einat. ........ r58415 | thomas.heller | 2007-10-11 12:51:32 -0700 (Thu, 11 Oct 2007) | 5 lines On OS X, use os.uname() instead of gestalt.sysv(...) to get the operating system version. This allows to use ctypes when Python was configured with --disable-toolbox-glue. ........ r58419 | neal.norwitz | 2007-10-11 20:01:01 -0700 (Thu, 11 Oct 2007) | 1 line Get rid of warning about not being able to create an existing directory. ........ r58420 | neal.norwitz | 2007-10-11 20:01:30 -0700 (Thu, 11 Oct 2007) | 1 line Get rid of warnings on a bunch of platforms by using a proper prototype. ........ r58421 | neal.norwitz | 2007-10-11 20:01:54 -0700 (Thu, 11 Oct 2007) | 4 lines Get rid of compiler warning about retval being used (returned) without being initialized. (gcc warning and Coverity 202) ........ r58422 | neal.norwitz | 2007-10-11 20:03:23 -0700 (Thu, 11 Oct 2007) | 1 line Fix Coverity 168: Close the file before returning (exiting). ........ r58423 | neal.norwitz | 2007-10-11 20:04:18 -0700 (Thu, 11 Oct 2007) | 4 lines Fix Coverity 180: Don't overallocate. We don't need structs, but pointers. Also fix a memory leak. ........ r58424 | neal.norwitz | 2007-10-11 20:05:19 -0700 (Thu, 11 Oct 2007) | 5 lines Fix Coverity 185-186: If the passed in FILE is NULL, uninitialized memory would be accessed. Will backport. ........ r58425 | neal.norwitz | 2007-10-11 20:52:34 -0700 (Thu, 11 Oct 2007) | 1 line Get this module to compile with bsddb versions prior to 4.3 ........ r58430 | martin.v.loewis | 2007-10-12 01:56:52 -0700 (Fri, 12 Oct 2007) | 3 lines Bug #1216: Restore support for Visual Studio 2002. Will backport to 2.5. ........ r58433 | raymond.hettinger | 2007-10-12 10:53:11 -0700 (Fri, 12 Oct 2007) | 1 line Fix test of count.__repr__() to ignore the 'L' if the count is a long ........ r58434 | gregory.p.smith | 2007-10-12 11:44:06 -0700 (Fri, 12 Oct 2007) | 4 lines Fixes http://bugs.python.org/issue1233 - bsddb.dbshelve.DBShelf.append was useless due to inverted logic. Also adds a test case for RECNO dbs to test_dbshelve. ........ r58445 | georg.brandl | 2007-10-13 06:20:03 -0700 (Sat, 13 Oct 2007) | 2 lines Fix email example. ........ r58450 | gregory.p.smith | 2007-10-13 16:02:05 -0700 (Sat, 13 Oct 2007) | 2 lines Fix an uncollectable reference leak in bsddb.db.DBShelf.append ........ r58453 | neal.norwitz | 2007-10-13 17:18:40 -0700 (Sat, 13 Oct 2007) | 8 lines Let the O/S supply a port if none of the default ports can be used. This should make the tests more robust at the expense of allowing tests to be sloppier by not requiring them to cleanup after themselves. (It will legitamitely help when running two test suites simultaneously or if another process is already using one of the predefined ports.) Also simplifies (slightLy) the exception handling elsewhere. ........ r58459 | neal.norwitz | 2007-10-14 11:30:21 -0700 (Sun, 14 Oct 2007) | 2 lines Don't raise a string exception, they don't work anymore. ........ r58460 | neal.norwitz | 2007-10-14 11:40:37 -0700 (Sun, 14 Oct 2007) | 1 line Use unittest for assertions ........ r58468 | armin.rigo | 2007-10-15 00:48:35 -0700 (Mon, 15 Oct 2007) | 2 lines test_bigbits was not testing what it seemed to. ........ r58471 | guido.van.rossum | 2007-10-15 08:54:11 -0700 (Mon, 15 Oct 2007) | 3 lines Change a PyErr_Print() into a PyErr_Clear(), per discussion in issue 1031213. ........ r58500 | raymond.hettinger | 2007-10-16 12:18:30 -0700 (Tue, 16 Oct 2007) | 1 line Improve error messages ........ r58506 | raymond.hettinger | 2007-10-16 14:28:32 -0700 (Tue, 16 Oct 2007) | 1 line More docs, error messages, and tests ........ r58507 | andrew.kuchling | 2007-10-16 15:58:03 -0700 (Tue, 16 Oct 2007) | 1 line Add items ........ r58508 | brett.cannon | 2007-10-16 16:24:06 -0700 (Tue, 16 Oct 2007) | 3 lines Remove ``:const:`` notation on None in parameter list. Since the markup is not rendered for parameters it just showed up as ``:const:`None` `` in the output. ........ r58509 | brett.cannon | 2007-10-16 16:26:45 -0700 (Tue, 16 Oct 2007) | 3 lines Re-order some functions whose parameters differ between PyObject and const char * so that they are next to each other. ........ r58522 | armin.rigo | 2007-10-17 11:46:37 -0700 (Wed, 17 Oct 2007) | 5 lines Fix the overflow checking of list_repeat. Introduce overflow checking into list_inplace_repeat. Backport candidate, possibly. ........ r58530 | facundo.batista | 2007-10-17 20:16:03 -0700 (Wed, 17 Oct 2007) | 7 lines Issue #1580738. When HTTPConnection reads the whole stream with read(), it closes itself. When the stream is read in several calls to read(n), it should behave in the same way if HTTPConnection knows where the end of the stream is (through self.length). Added a test case for this behaviour. ........ r58531 | facundo.batista | 2007-10-17 20:44:48 -0700 (Wed, 17 Oct 2007) | 3 lines Issue 1289, just a typo. ........ r58532 | gregory.p.smith | 2007-10-18 00:56:54 -0700 (Thu, 18 Oct 2007) | 4 lines cleanup test_dbtables to use mkdtemp. cleanup dbtables to pass txn as a keyword argument whenever possible to avoid bugs and confusion. (dbtables.py line 447 self.db.get using txn as a non-keyword was an actual bug due to this) ........ r58533 | gregory.p.smith | 2007-10-18 01:34:20 -0700 (Thu, 18 Oct 2007) | 4 lines Fix a weird bug in dbtables: if it chose a random rowid string that contained NULL bytes it would cause the database all sorts of problems in the future leading to very strange random failures and corrupt dbtables.bsdTableDb dbs. ........ r58534 | gregory.p.smith | 2007-10-18 09:32:02 -0700 (Thu, 18 Oct 2007) | 3 lines A cleaner fix than the one committed last night. Generate random rowids that do not contain null bytes. ........ r58537 | gregory.p.smith | 2007-10-18 10:17:57 -0700 (Thu, 18 Oct 2007) | 2 lines mention bsddb fixes. ........ r58538 | raymond.hettinger | 2007-10-18 14:13:06 -0700 (Thu, 18 Oct 2007) | 1 line Remove useless warning ........ r58539 | gregory.p.smith | 2007-10-19 00:31:20 -0700 (Fri, 19 Oct 2007) | 2 lines squelch the warning that this test is supposed to trigger. ........ r58542 | georg.brandl | 2007-10-19 05:32:39 -0700 (Fri, 19 Oct 2007) | 2 lines Clarify wording for apply(). ........ r58544 | mark.summerfield | 2007-10-19 05:48:17 -0700 (Fri, 19 Oct 2007) | 3 lines Added a cross-ref to each other. ........ r58545 | georg.brandl | 2007-10-19 10:38:49 -0700 (Fri, 19 Oct 2007) | 2 lines #1284: "S" means "seen", not unread. ........ r58548 | thomas.heller | 2007-10-19 11:11:41 -0700 (Fri, 19 Oct 2007) | 4 lines Fix ctypes on 32-bit systems when Python is configured --with-system-ffi. See also https://bugs.launchpad.net/bugs/72505. Ported from release25-maint branch. ........ r58550 | facundo.batista | 2007-10-19 12:25:57 -0700 (Fri, 19 Oct 2007) | 8 lines The constructor from tuple was way too permissive: it allowed bad coefficient numbers, floats in the sign, and other details that generated directly the wrong number in the best case, or triggered misfunctionality in the alorithms. Test cases added for these issues. Thanks Mark Dickinson. ........ r58559 | georg.brandl | 2007-10-20 06:22:53 -0700 (Sat, 20 Oct 2007) | 2 lines Fix code being interpreted as a target. ........ r58561 | georg.brandl | 2007-10-20 06:36:24 -0700 (Sat, 20 Oct 2007) | 2 lines Document new "cmdoption" directive. ........ r58562 | georg.brandl | 2007-10-20 08:21:22 -0700 (Sat, 20 Oct 2007) | 2 lines Make a path more Unix-standardy. ........ r58564 | georg.brandl | 2007-10-20 10:51:39 -0700 (Sat, 20 Oct 2007) | 2 lines Document new directive "envvar". ........ r58567 | georg.brandl | 2007-10-20 11:08:14 -0700 (Sat, 20 Oct 2007) | 6 lines * Add new toplevel chapter, "Using Python." (how to install, configure and setup python on different platforms -- at least in theory.) * Move the Python on Mac docs in that chapter. * Add a new chapter about the command line invocation, by stargaming. ........ r58568 | georg.brandl | 2007-10-20 11:33:20 -0700 (Sat, 20 Oct 2007) | 2 lines Change title, for now. ........ r58569 | georg.brandl | 2007-10-20 11:39:25 -0700 (Sat, 20 Oct 2007) | 2 lines Add entry to ACKS. ........ r58570 | georg.brandl | 2007-10-20 12:05:45 -0700 (Sat, 20 Oct 2007) | 2 lines Clarify -E docs. ........ r58571 | georg.brandl | 2007-10-20 12:08:36 -0700 (Sat, 20 Oct 2007) | 2 lines Even more clarification. ........ r58572 | andrew.kuchling | 2007-10-20 12:25:37 -0700 (Sat, 20 Oct 2007) | 1 line Fix protocol name ........ r58573 | andrew.kuchling | 2007-10-20 12:35:18 -0700 (Sat, 20 Oct 2007) | 1 line Various items ........ r58574 | andrew.kuchling | 2007-10-20 12:39:35 -0700 (Sat, 20 Oct 2007) | 1 line Use correct header line ........ r58576 | armin.rigo | 2007-10-21 02:14:15 -0700 (Sun, 21 Oct 2007) | 3 lines Add a crasher for the long-standing issue with closing a file while another thread uses it. ........ r58577 | georg.brandl | 2007-10-21 03:01:56 -0700 (Sun, 21 Oct 2007) | 2 lines Remove duplicate crasher. ........ r58578 | georg.brandl | 2007-10-21 03:24:20 -0700 (Sun, 21 Oct 2007) | 2 lines Unify "byte code" to "bytecode". Also sprinkle :term: markup for it. ........ r58579 | georg.brandl | 2007-10-21 03:32:54 -0700 (Sun, 21 Oct 2007) | 2 lines Add markup to new function descriptions. ........ r58580 | georg.brandl | 2007-10-21 03:45:46 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term:s for descriptors. ........ r58581 | georg.brandl | 2007-10-21 03:46:24 -0700 (Sun, 21 Oct 2007) | 2 lines Unify "file-descriptor" to "file descriptor". ........ r58582 | georg.brandl | 2007-10-21 03:52:38 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term: for generators. ........ r58583 | georg.brandl | 2007-10-21 05:10:28 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term:s for iterator. ........ r58584 | georg.brandl | 2007-10-21 05:15:05 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term:s for "new-style class". ........ r58588 | neal.norwitz | 2007-10-21 21:47:54 -0700 (Sun, 21 Oct 2007) | 1 line Add Chris Monson so he can edit PEPs. ........ r58594 | guido.van.rossum | 2007-10-22 09:27:19 -0700 (Mon, 22 Oct 2007) | 4 lines Issue #1307, patch by Derek Shockey. When "MAIL" is received without args, an exception happens instead of sending a 501 syntax error response. ........ r58598 | travis.oliphant | 2007-10-22 19:40:56 -0700 (Mon, 22 Oct 2007) | 1 line Add phuang patch from Issue 708374 which adds offset parameter to mmap module. ........ r58601 | neal.norwitz | 2007-10-22 22:44:27 -0700 (Mon, 22 Oct 2007) | 2 lines Bug #1313, fix typo (wrong variable name) in example. ........ r58609 | georg.brandl | 2007-10-23 11:21:35 -0700 (Tue, 23 Oct 2007) | 2 lines Update Pygments version from externals. ........ r58618 | guido.van.rossum | 2007-10-23 12:25:41 -0700 (Tue, 23 Oct 2007) | 3 lines Issue 1307 by Derek Shockey, fox the same bug for RCPT. Neal: please backport! ........ r58620 | raymond.hettinger | 2007-10-23 13:37:41 -0700 (Tue, 23 Oct 2007) | 1 line Shorter name for namedtuple() ........ r58621 | andrew.kuchling | 2007-10-23 13:55:47 -0700 (Tue, 23 Oct 2007) | 1 line Update name ........ r58622 | raymond.hettinger | 2007-10-23 14:23:07 -0700 (Tue, 23 Oct 2007) | 1 line Fixup news entry ........ r58623 | raymond.hettinger | 2007-10-23 18:28:33 -0700 (Tue, 23 Oct 2007) | 1 line Optimize sum() for integer and float inputs. ........ r58624 | raymond.hettinger | 2007-10-23 19:05:51 -0700 (Tue, 23 Oct 2007) | 1 line Fixup error return and add support for intermixed ints and floats/ ........ r58628 | vinay.sajip | 2007-10-24 03:47:06 -0700 (Wed, 24 Oct 2007) | 1 line Bug #1321: Fixed logic error in TimedRotatingFileHandler.__init__() ........ r58641 | facundo.batista | 2007-10-24 12:11:08 -0700 (Wed, 24 Oct 2007) | 4 lines Issue 1290. CharacterData.__repr__ was constructing a string in response that keeped having a non-ascii character. ........ r58643 | thomas.heller | 2007-10-24 12:50:45 -0700 (Wed, 24 Oct 2007) | 1 line Added unittest for calling a function with paramflags (backport from py3k branch). ........ r58645 | matthias.klose | 2007-10-24 13:00:44 -0700 (Wed, 24 Oct 2007) | 2 lines - Build using system ffi library on arm*-linux*. ........ r58651 | georg.brandl | 2007-10-24 14:40:38 -0700 (Wed, 24 Oct 2007) | 2 lines Bug #1287: make os.environ.pop() work as expected. ........ r58652 | raymond.hettinger | 2007-10-24 19:26:58 -0700 (Wed, 24 Oct 2007) | 1 line Missing DECREFs ........ r58653 | matthias.klose | 2007-10-24 23:37:24 -0700 (Wed, 24 Oct 2007) | 2 lines - Build using system ffi library on arm*-linux*, pass --with-system-ffi to CONFIG_ARGS ........ r58655 | thomas.heller | 2007-10-25 12:47:32 -0700 (Thu, 25 Oct 2007) | 2 lines ffi_type_longdouble may be already #defined. See issue 1324. ........ r58656 | kurt.kaiser | 2007-10-25 15:43:45 -0700 (Thu, 25 Oct 2007) | 3 lines Correct an ancient bug in an unused path by removing that path: register() is now idempotent. ........ r58660 | kurt.kaiser | 2007-10-25 17:10:09 -0700 (Thu, 25 Oct 2007) | 4 lines 1. Add comments to provide top-level documentation. 2. Refactor to use more descriptive names. 3. Enhance tests in main(). ........ r58675 | georg.brandl | 2007-10-26 11:30:41 -0700 (Fri, 26 Oct 2007) | 2 lines Fix new pop() method on os.environ on ignorecase-platforms. ........ r58696 | neal.norwitz | 2007-10-27 15:32:21 -0700 (Sat, 27 Oct 2007) | 1 line Update URL for Pygments. 0.8.1 is no longer available ........ r58697 | hyeshik.chang | 2007-10-28 04:19:02 -0700 (Sun, 28 Oct 2007) | 3 lines - Add support for FreeBSD 8 which is recently forked from FreeBSD 7. - Regenerate IN module for most recent maintenance tree of FreeBSD 6 and 7. ........ r58698 | hyeshik.chang | 2007-10-28 05:38:09 -0700 (Sun, 28 Oct 2007) | 2 lines Enable platform-specific tweaks for FreeBSD 8 (exactly same to FreeBSD 7's yet) ........ r58700 | kurt.kaiser | 2007-10-28 12:03:59 -0700 (Sun, 28 Oct 2007) | 2 lines Add confirmation dialog before printing. Patch 1717170 Tal Einat. ........ r58706 | guido.van.rossum | 2007-10-29 13:52:45 -0700 (Mon, 29 Oct 2007) | 3 lines Patch 1353 by Jacob Winther. Add mp4 mapping to mimetypes.py. ........ r58709 | guido.van.rossum | 2007-10-29 15:15:05 -0700 (Mon, 29 Oct 2007) | 6 lines Backport fixes for the code that decodes octal escapes (and for PyString also hex escapes) -- this was reaching beyond the end of the input string buffer, even though it is not supposed to be \0-terminated. This has no visible effect but is clearly the correct thing to do. (In 3.0 it had a visible effect after removing ob_sstate from PyString.) ........ r58710 | kurt.kaiser | 2007-10-29 19:38:54 -0700 (Mon, 29 Oct 2007) | 7 lines check in Tal Einat's update to tabpage.py Patch 1612746 M configDialog.py M NEWS.txt AM tabbedpages.py ........ r58715 | georg.brandl | 2007-10-30 10:51:18 -0700 (Tue, 30 Oct 2007) | 2 lines Use correct markup. ........ r58716 | georg.brandl | 2007-10-30 10:57:12 -0700 (Tue, 30 Oct 2007) | 2 lines Make example about hiding None return values at the prompt clearer. ........ r58728 | neal.norwitz | 2007-10-30 23:33:20 -0700 (Tue, 30 Oct 2007) | 1 line Fix some compiler warnings for signed comparisons on Unix and Windows. ........ r58731 | martin.v.loewis | 2007-10-31 10:19:33 -0700 (Wed, 31 Oct 2007) | 2 lines Adding Christian Heimes. ........ r58737 | raymond.hettinger | 2007-10-31 14:57:58 -0700 (Wed, 31 Oct 2007) | 1 line Clarify the reasons why pickle is almost always better than marshal ........ r58739 | raymond.hettinger | 2007-10-31 15:15:49 -0700 (Wed, 31 Oct 2007) | 1 line Sets are marshalable. ........
2007-11-01 17:32:30 -03:00
:class:`CookieJar` objects support the :term:`iterator` protocol for iterating over
2007-08-15 11:28:22 -03:00
contained :class:`Cookie` objects.
:class:`CookieJar` has the following methods:
.. method:: CookieJar.add_cookie_header(request)
Add correct :mailheader:`Cookie` header to *request*.
If policy allows (ie. the :attr:`rfc2965` and :attr:`hide_cookie2` attributes of
the :class:`CookieJar`'s :class:`CookiePolicy` instance are true and false
respectively), the :mailheader:`Cookie2` header is also added when appropriate.
The *request* object (usually a :class:`urllib.request.Request` instance)
must support the methods :meth:`get_full_url`, :meth:`has_header`,
:meth:`get_header`, :meth:`header_items`, :meth:`add_unredirected_header`
and the attributes :attr:`host`, :attr:`!type`, :attr:`unverifiable`
and :attr:`origin_req_host` as documented by :mod:`urllib.request`.
.. versionchanged:: 3.3
*request* object needs :attr:`origin_req_host` attribute. Dependency on a
deprecated method :meth:`get_origin_req_host` has been removed.
2007-08-15 11:28:22 -03:00
.. method:: CookieJar.extract_cookies(response, request)
Extract cookies from HTTP *response* and store them in the :class:`CookieJar`,
where allowed by policy.
The :class:`CookieJar` will look for allowable :mailheader:`Set-Cookie` and
:mailheader:`Set-Cookie2` headers in the *response* argument, and store cookies
as appropriate (subject to the :meth:`CookiePolicy.set_ok` method's approval).
2008-06-12 15:52:31 -03:00
The *response* object (usually the result of a call to
2008-06-23 08:44:14 -03:00
:meth:`urllib.request.urlopen`, or similar) should support an :meth:`info`
method, which returns an :class:`email.message.Message` instance.
2007-08-15 11:28:22 -03:00
2008-06-23 08:44:14 -03:00
The *request* object (usually a :class:`urllib.request.Request` instance)
must support the method :meth:`get_full_url` and the attributes
:attr:`host`, :attr:`unverifiable` and :attr:`origin_req_host`,
as documented by :mod:`urllib.request`. The request is used to set
default values for cookie-attributes as well as for checking that the
cookie is allowed to be set.
2007-08-15 11:28:22 -03:00
.. versionchanged:: 3.3
*request* object needs :attr:`origin_req_host` attribute. Dependency on a
deprecated method :meth:`get_origin_req_host` has been removed.
2007-08-15 11:28:22 -03:00
.. method:: CookieJar.set_policy(policy)
Set the :class:`CookiePolicy` instance to be used.
.. method:: CookieJar.make_cookies(response, request)
Return sequence of :class:`Cookie` objects extracted from *response* object.
See the documentation for :meth:`extract_cookies` for the interfaces required of
the *response* and *request* arguments.
.. method:: CookieJar.set_cookie_if_ok(cookie, request)
Set a :class:`Cookie` if policy says it's OK to do so.
.. method:: CookieJar.set_cookie(cookie)
Set a :class:`Cookie`, without checking with policy to see whether or not it
should be set.
.. method:: CookieJar.clear([domain[, path[, name]]])
Clear some cookies.
If invoked without arguments, clear all cookies. If given a single argument,
only cookies belonging to that *domain* will be removed. If given two arguments,
cookies belonging to the specified *domain* and URL *path* are removed. If
given three arguments, then the cookie with the specified *domain*, *path* and
*name* is removed.
Raises :exc:`KeyError` if no matching cookie exists.
.. method:: CookieJar.clear_session_cookies()
Discard all session cookies.
Discards all contained cookies that have a true :attr:`discard` attribute
(usually because they had either no ``max-age`` or ``expires`` cookie-attribute,
or an explicit ``discard`` cookie-attribute). For interactive browsers, the end
of a session usually corresponds to closing the browser window.
Note that the :meth:`save` method won't save session cookies anyway, unless you
ask otherwise by passing a true *ignore_discard* argument.
:class:`FileCookieJar` implements the following additional methods:
.. method:: FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False)
Save cookies to a file.
This base class raises :exc:`NotImplementedError`. Subclasses may leave this
method unimplemented.
*filename* is the name of file in which to save cookies. If *filename* is not
specified, :attr:`self.filename` is used (whose default is the value passed to
the constructor, if any); if :attr:`self.filename` is :const:`None`,
:exc:`ValueError` is raised.
*ignore_discard*: save even cookies set to be discarded. *ignore_expires*: save
even cookies that have expired
The file is overwritten if it already exists, thus wiping all the cookies it
contains. Saved cookies can be restored later using the :meth:`load` or
:meth:`revert` methods.
.. method:: FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)
Load cookies from a file.
Old cookies are kept unless overwritten by newly loaded ones.
Arguments are as for :meth:`save`.
The named file must be in the format understood by the class, or
2011-10-12 15:10:51 -03:00
:exc:`LoadError` will be raised. Also, :exc:`OSError` may be raised, for
2007-08-15 11:28:22 -03:00
example if the file does not exist.
2011-10-12 15:10:51 -03:00
.. versionchanged:: 3.3
:exc:`IOError` used to be raised, it is now an alias of :exc:`OSError`.
2007-08-15 11:28:22 -03:00
.. method:: FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)
Clear all cookies and reload cookies from a saved file.
:meth:`revert` can raise the same exceptions as :meth:`load`. If there is a
failure, the object's state will not be altered.
:class:`FileCookieJar` instances have the following public attributes:
.. attribute:: FileCookieJar.filename
Filename of default file in which to keep cookies. This attribute may be
assigned to.
.. attribute:: FileCookieJar.delayload
If true, load cookies lazily from disk. This attribute should not be assigned
to. This is only a hint, since this only affects performance, not behaviour
(unless the cookies on disk are changing). A :class:`CookieJar` object may
ignore it. None of the :class:`FileCookieJar` classes included in the standard
library lazily loads cookies.
.. _file-cookie-jar-classes:
FileCookieJar subclasses and co-operation with web browsers
-----------------------------------------------------------
The following :class:`CookieJar` subclasses are provided for reading and
writing.
2007-08-15 11:28:22 -03:00
.. class:: MozillaCookieJar(filename=None, delayload=None, policy=None)
2007-08-15 11:28:22 -03:00
A :class:`FileCookieJar` that can load from and save cookies to disk in the
Mozilla ``cookies.txt`` file format (which is also used by curl and the Lynx
and Netscape browsers).
2007-08-15 11:28:22 -03:00
.. note::
This loses information about :rfc:`2965` cookies, and also about newer or
2007-08-15 11:28:22 -03:00
non-standard cookie-attributes such as ``port``.
.. warning::
Back up your cookies before saving if you have cookies whose loss / corruption
would be inconvenient (there are some subtleties which may lead to slight
changes in the file over a load / save round-trip).
Also note that cookies saved while Mozilla is running will get clobbered by
Mozilla.
.. class:: LWPCookieJar(filename=None, delayload=None, policy=None)
2007-08-15 11:28:22 -03:00
A :class:`FileCookieJar` that can load from and save cookies to disk in format
compatible with the libwww-perl library's ``Set-Cookie3`` file format. This is
convenient if you want to store cookies in a human-readable file.
.. versionchanged:: 3.8
The filename parameter supports a :term:`path-like object`.
2007-08-15 11:28:22 -03:00
.. _cookie-policy-objects:
CookiePolicy Objects
--------------------
Objects implementing the :class:`CookiePolicy` interface have the following
methods:
.. method:: CookiePolicy.set_ok(cookie, request)
Return boolean value indicating whether cookie should be accepted from server.
2008-05-26 13:32:26 -03:00
*cookie* is a :class:`Cookie` instance. *request* is an object
2007-08-15 11:28:22 -03:00
implementing the interface defined by the documentation for
:meth:`CookieJar.extract_cookies`.
.. method:: CookiePolicy.return_ok(cookie, request)
Return boolean value indicating whether cookie should be returned to server.
2008-05-26 13:32:26 -03:00
*cookie* is a :class:`Cookie` instance. *request* is an object
2007-08-15 11:28:22 -03:00
implementing the interface defined by the documentation for
:meth:`CookieJar.add_cookie_header`.
.. method:: CookiePolicy.domain_return_ok(domain, request)
Return ``False`` if cookies should not be returned, given cookie domain.
2007-08-15 11:28:22 -03:00
This method is an optimization. It removes the need for checking every cookie
with a particular domain (which might involve reading many files). Returning
true from :meth:`domain_return_ok` and :meth:`path_return_ok` leaves all the
work to :meth:`return_ok`.
If :meth:`domain_return_ok` returns true for the cookie domain,
:meth:`path_return_ok` is called for the cookie path. Otherwise,
:meth:`path_return_ok` and :meth:`return_ok` are never called for that cookie
domain. If :meth:`path_return_ok` returns true, :meth:`return_ok` is called
with the :class:`Cookie` object itself for a full check. Otherwise,
:meth:`return_ok` is never called for that cookie path.
Note that :meth:`domain_return_ok` is called for every *cookie* domain, not just
for the *request* domain. For example, the function might be called with both
``".example.com"`` and ``"www.example.com"`` if the request domain is
``"www.example.com"``. The same goes for :meth:`path_return_ok`.
The *request* argument is as documented for :meth:`return_ok`.
.. method:: CookiePolicy.path_return_ok(path, request)
Return ``False`` if cookies should not be returned, given cookie path.
2007-08-15 11:28:22 -03:00
See the documentation for :meth:`domain_return_ok`.
In addition to implementing the methods above, implementations of the
:class:`CookiePolicy` interface must also supply the following attributes,
indicating which protocols should be used, and how. All of these attributes may
be assigned to.
.. attribute:: CookiePolicy.netscape
Implement Netscape protocol.
.. attribute:: CookiePolicy.rfc2965
Implement :rfc:`2965` protocol.
2007-08-15 11:28:22 -03:00
.. attribute:: CookiePolicy.hide_cookie2
Don't add :mailheader:`Cookie2` header to requests (the presence of this header
indicates to the server that we understand :rfc:`2965` cookies).
2007-08-15 11:28:22 -03:00
The most useful way to define a :class:`CookiePolicy` class is by subclassing
from :class:`DefaultCookiePolicy` and overriding some or all of the methods
above. :class:`CookiePolicy` itself may be used as a 'null policy' to allow
setting and receiving any and all cookies (this is unlikely to be useful).
.. _default-cookie-policy-objects:
DefaultCookiePolicy Objects
---------------------------
Implements the standard rules for accepting and returning cookies.
Both :rfc:`2965` and Netscape cookies are covered. RFC 2965 handling is switched
2007-08-15 11:28:22 -03:00
off by default.
The easiest way to provide your own policy is to override this class and call
its methods in your overridden implementations before adding your own additional
checks::
2008-05-26 13:32:26 -03:00
import http.cookiejar
class MyCookiePolicy(http.cookiejar.DefaultCookiePolicy):
2007-08-15 11:28:22 -03:00
def set_ok(self, cookie, request):
2008-05-26 13:32:26 -03:00
if not http.cookiejar.DefaultCookiePolicy.set_ok(self, cookie, request):
2007-08-15 11:28:22 -03:00
return False
if i_dont_want_to_store_this_cookie(cookie):
return False
return True
In addition to the features required to implement the :class:`CookiePolicy`
interface, this class allows you to block and allow domains from setting and
receiving cookies. There are also some strictness switches that allow you to
tighten up the rather loose Netscape protocol rules a little bit (at the cost of
blocking some benign cookies).
A domain blocklist and allowlist is provided (both off by default). Only domains
not in the blocklist and present in the allowlist (if the allowlist is active)
2007-08-15 11:28:22 -03:00
participate in cookie setting and returning. Use the *blocked_domains*
constructor argument, and :meth:`blocked_domains` and
:meth:`set_blocked_domains` methods (and the corresponding argument and methods
for *allowed_domains*). If you set an allowlist, you can turn it off again by
2007-08-15 11:28:22 -03:00
setting it to :const:`None`.
Domains in block or allow lists that do not start with a dot must equal the
cookie domain to be matched. For example, ``"example.com"`` matches a blocklist
2007-08-15 11:28:22 -03:00
entry of ``"example.com"``, but ``"www.example.com"`` does not. Domains that do
start with a dot are matched by more specific domains too. For example, both
``"www.example.com"`` and ``"www.coyote.example.com"`` match ``".example.com"``
(but ``"example.com"`` itself does not). IP addresses are an exception, and
must match exactly. For example, if blocked_domains contains ``"192.168.1.2"``
and ``".168.1.2"``, 192.168.1.2 is blocked, but 193.168.1.2 is not.
:class:`DefaultCookiePolicy` implements the following additional methods:
.. method:: DefaultCookiePolicy.blocked_domains()
Return the sequence of blocked domains (as a tuple).
.. method:: DefaultCookiePolicy.set_blocked_domains(blocked_domains)
Set the sequence of blocked domains.
.. method:: DefaultCookiePolicy.is_blocked(domain)
Return ``True`` if *domain* is on the blocklist for setting or receiving
cookies.
2007-08-15 11:28:22 -03:00
.. method:: DefaultCookiePolicy.allowed_domains()
Return :const:`None`, or the sequence of allowed domains (as a tuple).
.. method:: DefaultCookiePolicy.set_allowed_domains(allowed_domains)
Set the sequence of allowed domains, or :const:`None`.
.. method:: DefaultCookiePolicy.is_not_allowed(domain)
Return ``True`` if *domain* is not on the allowlist for setting or receiving
2007-08-15 11:28:22 -03:00
cookies.
:class:`DefaultCookiePolicy` instances have the following attributes, which are
all initialised from the constructor arguments of the same name, and which may
all be assigned to.
.. attribute:: DefaultCookiePolicy.rfc2109_as_netscape
If true, request that the :class:`CookieJar` instance downgrade :rfc:`2109` cookies
2007-08-15 11:28:22 -03:00
(ie. cookies received in a :mailheader:`Set-Cookie` header with a version
cookie-attribute of 1) to Netscape cookies by setting the version attribute of
the :class:`Cookie` instance to 0. The default value is :const:`None`, in which
case RFC 2109 cookies are downgraded if and only if :rfc:`2965` handling is turned
2007-08-15 11:28:22 -03:00
off. Therefore, RFC 2109 cookies are downgraded by default.
General strictness switches:
.. attribute:: DefaultCookiePolicy.strict_domain
Don't allow sites to set two-component domains with country-code top-level
domains like ``.co.uk``, ``.gov.uk``, ``.co.nz``.etc. This is far from perfect
and isn't guaranteed to work!
:rfc:`2965` protocol strictness switches:
2007-08-15 11:28:22 -03:00
.. attribute:: DefaultCookiePolicy.strict_rfc2965_unverifiable
Follow :rfc:`2965` rules on unverifiable transactions (usually, an unverifiable
2007-08-15 11:28:22 -03:00
transaction is one resulting from a redirect or a request for an image hosted on
another site). If this is false, cookies are *never* blocked on the basis of
verifiability
Netscape protocol strictness switches:
2007-08-15 11:28:22 -03:00
.. attribute:: DefaultCookiePolicy.strict_ns_unverifiable
Apply :rfc:`2965` rules on unverifiable transactions even to Netscape cookies.
2007-08-15 11:28:22 -03:00
.. attribute:: DefaultCookiePolicy.strict_ns_domain
Flags indicating how strict to be with domain-matching rules for Netscape
cookies. See below for acceptable values.
.. attribute:: DefaultCookiePolicy.strict_ns_set_initial_dollar
Ignore cookies in Set-Cookie: headers that have names starting with ``'$'``.
.. attribute:: DefaultCookiePolicy.strict_ns_set_path
Don't allow setting cookies whose path doesn't path-match request URI.
:attr:`strict_ns_domain` is a collection of flags. Its value is constructed by
or-ing together (for example, ``DomainStrictNoDots|DomainStrictNonDomain`` means
both flags are set).
.. attribute:: DefaultCookiePolicy.DomainStrictNoDots
When setting cookies, the 'host prefix' must not contain a dot (eg.
``www.foo.bar.com`` can't set a cookie for ``.bar.com``, because ``www.foo``
contains a dot).
.. attribute:: DefaultCookiePolicy.DomainStrictNonDomain
Cookies that did not explicitly specify a ``domain`` cookie-attribute can only
be returned to a domain equal to the domain that set the cookie (eg.
``spam.example.com`` won't be returned cookies from ``example.com`` that had no
``domain`` cookie-attribute).
.. attribute:: DefaultCookiePolicy.DomainRFC2965Match
When setting cookies, require a full :rfc:`2965` domain-match.
2007-08-15 11:28:22 -03:00
The following attributes are provided for convenience, and are the most useful
combinations of the above flags:
.. attribute:: DefaultCookiePolicy.DomainLiberal
Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched
off).
.. attribute:: DefaultCookiePolicy.DomainStrict
Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``.
Cookie Objects
--------------
:class:`Cookie` instances have Python attributes roughly corresponding to the
standard cookie-attributes specified in the various cookie standards. The
correspondence is not one-to-one, because there are complicated rules for
assigning default values, because the ``max-age`` and ``expires``
cookie-attributes contain equivalent information, and because :rfc:`2109` cookies
2008-05-26 13:32:26 -03:00
may be 'downgraded' by :mod:`http.cookiejar` from version 1 to version 0 (Netscape)
2007-08-15 11:28:22 -03:00
cookies.
Assignment to these attributes should not be necessary other than in rare
circumstances in a :class:`CookiePolicy` method. The class does not enforce
internal consistency, so you should know what you're doing if you do that.
.. attribute:: Cookie.version
Integer or :const:`None`. Netscape cookies have :attr:`version` 0. :rfc:`2965` and
:rfc:`2109` cookies have a ``version`` cookie-attribute of 1. However, note that
2008-05-26 13:32:26 -03:00
:mod:`http.cookiejar` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which
2007-08-15 11:28:22 -03:00
case :attr:`version` is 0.
.. attribute:: Cookie.name
Cookie name (a string).
.. attribute:: Cookie.value
Cookie value (a string), or :const:`None`.
.. attribute:: Cookie.port
String representing a port or a set of ports (eg. '80', or '80,8080'), or
:const:`None`.
.. attribute:: Cookie.path
Cookie path (a string, eg. ``'/acme/rocket_launchers'``).
.. attribute:: Cookie.secure
``True`` if cookie should only be returned over a secure connection.
2007-08-15 11:28:22 -03:00
.. attribute:: Cookie.expires
Integer expiry date in seconds since epoch, or :const:`None`. See also the
:meth:`is_expired` method.
.. attribute:: Cookie.discard
``True`` if this is a session cookie.
2007-08-15 11:28:22 -03:00
.. attribute:: Cookie.comment
String comment from the server explaining the function of this cookie, or
:const:`None`.
.. attribute:: Cookie.comment_url
URL linking to a comment from the server explaining the function of this cookie,
or :const:`None`.
.. attribute:: Cookie.rfc2109
``True`` if this cookie was received as an :rfc:`2109` cookie (ie. the cookie
2007-08-15 11:28:22 -03:00
arrived in a :mailheader:`Set-Cookie` header, and the value of the Version
cookie-attribute in that header was 1). This attribute is provided because
2008-05-26 13:32:26 -03:00
:mod:`http.cookiejar` may 'downgrade' RFC 2109 cookies to Netscape cookies, in
2007-08-15 11:28:22 -03:00
which case :attr:`version` is 0.
.. attribute:: Cookie.port_specified
``True`` if a port or set of ports was explicitly specified by the server (in the
2007-08-15 11:28:22 -03:00
:mailheader:`Set-Cookie` / :mailheader:`Set-Cookie2` header).
.. attribute:: Cookie.domain_specified
``True`` if a domain was explicitly specified by the server.
2007-08-15 11:28:22 -03:00
.. attribute:: Cookie.domain_initial_dot
``True`` if the domain explicitly specified by the server began with a dot
2007-08-15 11:28:22 -03:00
(``'.'``).
Cookies may have additional non-standard cookie-attributes. These may be
accessed using the following methods:
.. method:: Cookie.has_nonstandard_attr(name)
Return ``True`` if cookie has the named cookie-attribute.
2007-08-15 11:28:22 -03:00
.. method:: Cookie.get_nonstandard_attr(name, default=None)
If cookie has the named cookie-attribute, return its value. Otherwise, return
*default*.
.. method:: Cookie.set_nonstandard_attr(name, value)
Set the value of the named cookie-attribute.
The :class:`Cookie` class also defines the following method:
.. method:: Cookie.is_expired(now=None)
2007-08-15 11:28:22 -03:00
``True`` if cookie has passed the time at which the server requested it should
2007-08-15 11:28:22 -03:00
expire. If *now* is given (in seconds since the epoch), return whether the
cookie has expired at the specified time.
Examples
--------
2008-05-26 13:32:26 -03:00
The first example shows the most common usage of :mod:`http.cookiejar`::
2007-08-15 11:28:22 -03:00
2008-06-23 08:44:14 -03:00
import http.cookiejar, urllib.request
2008-05-26 13:32:26 -03:00
cj = http.cookiejar.CookieJar()
2008-06-23 08:44:14 -03:00
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
2007-08-15 11:28:22 -03:00
r = opener.open("http://example.com/")
This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx
cookies (assumes Unix/Netscape convention for location of the cookies file)::
2008-06-23 08:44:14 -03:00
import os, http.cookiejar, urllib.request
2008-05-26 13:32:26 -03:00
cj = http.cookiejar.MozillaCookieJar()
cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))
2008-06-23 08:44:14 -03:00
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
2007-08-15 11:28:22 -03:00
r = opener.open("http://example.com/")
The next example illustrates the use of :class:`DefaultCookiePolicy`. Turn on
:rfc:`2965` cookies, be more strict about domains when setting and returning
2007-08-15 11:28:22 -03:00
Netscape cookies, and block some domains from setting cookies or having them
returned::
2008-06-23 08:44:14 -03:00
import urllib.request
2008-05-26 13:32:26 -03:00
from http.cookiejar import CookieJar, DefaultCookiePolicy
2007-08-15 11:28:22 -03:00
policy = DefaultCookiePolicy(
rfc2965=True, strict_ns_domain=Policy.DomainStrict,
blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
2008-06-23 08:44:14 -03:00
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
2007-08-15 11:28:22 -03:00
r = opener.open("http://example.com/")