11.20 cookielib -- Cookie handling for HTTP clients

# 11.20 `cookielib` -- Cookie handling for HTTP clients

The `cookielib` module defines classes for automatic handling of HTTP cookies. It is useful for accessing web sites that require small pieces of data - 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 as RFC 2965 cookies. Note that the great majority of cookies on the Internet are Netscape cookies. `cookielib` attempts to follow the de-facto Netscape cookie protocol (which 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 2109. Note: The various named parameters found in Set-Cookie: and Set-Cookie2: headers (eg. `domain` and `expires`) are conventionally referred to as attributes. To distinguish them from Python attributes, the documentation for this module uses the term cookie-attribute instead.

The module defines the following exception:

exception `LoadError`
  Instances of `FileCookieJar` raise this exception on failure to load cookies from a file.

The following classes are provided:

class `CookieJar`( | policy=`None`)

  policy is an object implementing the `CookiePolicy` interface.

  The `CookieJar` class stores HTTP cookies. It extracts cookies from HTTP requests, and returns them in HTTP responses. `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, delayload=`None`, policy=`None`)

  policy is an object implementing the `CookiePolicy` interface. For the other arguments, see the documentation for the corresponding attributes.

  A `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 `load()` or `revert()` method is called. Subclasses of this class are documented in section 11.20.2.

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`, 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` )

  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 `None`, this is a sequence of the only domains for which we accept and return cookies. For all other arguments, see the documentation for `CookiePolicy` and `DefaultCookiePolicy` objects.

  `DefaultCookiePolicy` implements the standard accept / reject rules for Netscape and RFC 2965 cookies. RFC 2109 cookies (ie. cookies received in a Set-Cookie: header with a version cookie-attribute of 1) are treated according to the RFC 2965 rules. `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 expected that users of `cookielib` construct their own `Cookie` instances. Instead, if necessary, call `make_cookies()` on a `CookieJar` instance.

See Also:

Module `urllib2`:
  URL opening with automatic cookie handling.

Module `Cookie`:
  HTTP cookie classes, principally useful for server-side code. The `cookielib` and `Cookie` modules do not depend on each other.

http://wwwsearch.sf.net/ClientCookie/
  Extensions to this module, including a class for reading Microsoft Internet Explorer cookies on Windows.

http://www.netscape.com/newsref/std/cookie_spec.html
  The specification of the original Netscape cookie protocol. Though this is still the dominant protocol, the 'Netscape cookie protocol' implemented by all the major browsers (and `cookielib`) only bears a passing resemblance to the one sketched out in `cookie_spec.html`.

RFC 2109, HTTP State Management Mechanism
  Obsoleted by RFC 2965. Uses Set-Cookie: with version=1.

RFC 2965, HTTP State Management Mechanism
  The Netscape protocol with the bugs fixed. Uses Set-Cookie2: in place of Set-Cookie:. Not widely used.

http://kristol.org/cookie/errata.html
  Unfinished errata to RFC 2965.

RFC 2964, Use of HTTP State Management