cookielib
index
/usr/local/lib/python2.4/cookielib.py
Module Docs

HTTP cookie handling for web clients.
 
This module has (now fairly distant) origins in Gisle Aas' Perl module
HTTP::Cookies, from the libwww-perl library.
 
Docstrings, comments and debug strings in this code refer to the
attributes of the HTTP cookie system as cookie-attributes, to distinguish
them clearly from Python attributes.
 
Class diagram (note that the classes which do not derive from
FileCookieJar are not distributed with the Python standard library, but
are available from http://wwwsearch.sf.net/):
 
                        CookieJar____
                        /     \                  FileCookieJar      \                   /    |   \         \       MozillaCookieJar | LWPCookieJar \                        |               |                        |   ---MSIEBase |                         |  /      |     |                          | /   MSIEDBCookieJar BSDDBCookieJar
                  |/
               MSIECookieJar

 
Modules
       
threading
copy
httplib
logging
re
sys
time
urllib
urlparse

 
Classes
       
Absent
Cookie
CookieJar
FileCookieJar
CookiePolicy
DefaultCookiePolicy
exceptions.Exception
LoadError

 
class Absent
    # Used as second parameter to dict.get() method, to distinguish absent
# dict key from one with a None value.
 
 

 
class Cookie
    HTTP Cookie.
 
This class represents both Netscape and RFC 2965 cookies.
 
This is deliberately a very simple class.  It just holds attributes.  It's
possible to construct Cookie instances that don't comply with the cookie
standards.  CookieJar.make_cookies is the factory function for Cookie
objects -- it deals with cookie parsing, supplying defaults, and
normalising to the representation used in this class.  CookiePolicy is
responsible for checking them to see whether they should be accepted from
and returned to the server.
 
Note that the port may be present in the headers, but unspecified ("Port"
rather than"Port=80", for example); if this is the case, port is None.
 
  Methods defined here:
__init__(self, version, name, value, port, port_specified, domain, domain_specified, domain_initial_dot, path, path_specified, secure, expires, discard, comment, comment_url, rest)
__repr__(self)
__str__(self)
get_nonstandard_attr(self, name, default=None)
has_nonstandard_attr(self, name)
is_expired(self, now=None)
set_nonstandard_attr(self, name, value)

 
class CookieJar
    Collection of HTTP cookies.
 
You may not need to know about this class: try
urllib2.build_opener(HTTPCookieProcessor).open(url).
 
  Methods defined here:
__init__(self, policy=None)
__iter__(self)
__len__(self)
Return number of contained cookies.
__repr__(self)
__str__(self)
add_cookie_header(self, request)
Add correct Cookie: header to request (urllib2.Request object).
 
The Cookie2 header is also added unless policy.hide_cookie2 is true.
clear(self, domain=None, path=None, name=None)
Clear some cookies.
 
Invoking this method without arguments will 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
path within that domain are removed.  If given three arguments, then
the cookie with the specified name, path and domain is removed.
 
Raises KeyError if no matching cookie exists.
clear_expired_cookies(self)
Discard all expired cookies.
 
You probably don't need to call this method: expired cookies are never
sent back to the server (provided you're using DefaultCookiePolicy),
this method is called by CookieJar itself every so often, and the
.save() method won't save expired cookies anyway (unless you ask
otherwise by passing a true ignore_expires argument).
clear_session_cookies(self)
Discard all session cookies.
 
Note that the .save() method won't save session cookies anyway, unless
you ask otherwise by passing a true ignore_discard argument.
extract_cookies(self, response, request)
Extract cookies from response, where allowable given the request.
make_cookies(self, response, request)
Return sequence of Cookie objects extracted from response object.
set_cookie(self, cookie)
Set a cookie, without checking whether or not it should be set.
set_cookie_if_ok(self, cookie, request)
Set a cookie if policy says it's OK to do so.
set_policy(self, policy)

Data and other attributes defined here:
domain_re = <_sre.SRE_Pattern object>
dots_re = <_sre.SRE_Pattern object>
magic_re = r'^\#LWP-Cookies-(\d+\.\d+)'
non_word_re = <_sre.SRE_Pattern object>
quote_re = <_sre.SRE_Pattern object>
strict_domain_re = <_sre.SRE_Pattern object>

 
class CookiePolicy
    Defines which cookies get accepted from and returned to server.
 
May also modify cookies, though this is probably a bad idea.
 
The subclass DefaultCookiePolicy defines the standard rules for Netscape
and RFC 2965 cookies -- override that if you want a customised policy.
 
  Methods defined here:
domain_return_ok(self, domain, request)
Return false if cookies should not be returned, given cookie domain.
path_return_ok(self, path, request)
Return false if cookies should not be returned, given cookie path.
return_ok(self, cookie, request)
Return true if (and only if) cookie should be returned to server.
set_ok(self, cookie, request)
Return true if (and only if) cookie should be accepted from server.
 
Currently, pre-expired cookies never get this far -- the CookieJar
class deletes such cookies itself.

 
class DefaultCookiePolicy(CookiePolicy)
    Implements the standard rules for accepting and returning cookies.
 
  Methods defined here:
__init__(self, 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=0, strict_ns_set_initial_dollar=False, strict_ns_set_path=False)
Constructor arguments should be passed as keyword arguments only.
allowed_domains(self)
Return None, or the sequence of allowed domains (as a tuple).
blocked_domains(self)
Return the sequence of blocked domains (as a tuple).
domain_return_ok(self, domain, request)
is_blocked(self, domain)
is_not_allowed(self, domain)
path_return_ok(self, path, request)
return_ok(self, cookie, request)
If you override .return_ok(), be sure to call this method.  If it
returns false, so should your subclass (assuming your subclass wants to
be more strict about which cookies to return).
return_ok_domain(self, cookie, request)
return_ok_expires(self, cookie, request)
return_ok_port(self, cookie, request)
return_ok_secure(self, cookie, request)
return_ok_verifiability(self, cookie, request)
return_ok_version(self, cookie, request)
set_allowed_domains(self, allowed_domains)
Set the sequence of allowed domains, or None.
set_blocked_domains(self, blocked_domains)
Set the sequence of blocked domains.
set_ok(self, cookie, request)
If you override .set_ok(), be sure to call this method.  If it returns
false, so should your subclass (assuming your subclass wants to be more
strict about which cookies to accept).
set_ok_domain(self, cookie, request)
set_ok_name(self, cookie, request)
set_ok_path(self, cookie, request)
set_ok_port(self, cookie, request)
set_ok_verifiability(self, cookie, request)
set_ok_version(self, cookie, request)

Data and other attributes defined here:
DomainLiberal = 0
DomainRFC2965Match = 4
DomainStrict = 3
DomainStrictNoDots = 1
DomainStrictNonDomain = 2

 
class FileCookieJar(CookieJar)
    CookieJar that can be loaded from and saved to a file.
 
  Methods defined here:
__init__(self, filename=None, delayload=False, policy=None)
Cookies are NOT loaded from the named file until either the .load() or
.revert() method is called.
load(self, filename=None, ignore_discard=False, ignore_expires=False)
Load cookies from a file.
revert(self, filename=None, ignore_discard=False, ignore_expires=False)
Clear all cookies and reload cookies from a saved file.
 
Raises LoadError (or IOError) if reversion is not successful; the
object's state will not be altered if this happens.
save(self, filename=None, ignore_discard=False, ignore_expires=False)
Save cookies to a file.

Methods inherited from CookieJar:
__iter__(self)
__len__(self)
Return number of contained cookies.
__repr__(self)
__str__(self)
add_cookie_header(self, request)
Add correct Cookie: header to request (urllib2.Request object).
 
The Cookie2 header is also added unless policy.hide_cookie2 is true.
clear(self, domain=None, path=None, name=None)
Clear some cookies.
 
Invoking this method without arguments will 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
path within that domain are removed.  If given three arguments, then
the cookie with the specified name, path and domain is removed.
 
Raises KeyError if no matching cookie exists.
clear_expired_cookies(self)
Discard all expired cookies.
 
You probably don't need to call this method: expired cookies are never
sent back to the server (provided you're using DefaultCookiePolicy),
this method is called by CookieJar itself every so often, and the
.save() method won't save expired cookies anyway (unless you ask
otherwise by passing a true ignore_expires argument).
clear_session_cookies(self)
Discard all session cookies.
 
Note that the .save() method won't save session cookies anyway, unless
you ask otherwise by passing a true ignore_discard argument.
extract_cookies(self, response, request)
Extract cookies from response, where allowable given the request.
make_cookies(self, response, request)
Return sequence of Cookie objects extracted from response object.
set_cookie(self, cookie)
Set a cookie, without checking whether or not it should be set.
set_cookie_if_ok(self, cookie, request)
Set a cookie if policy says it's OK to do so.
set_policy(self, policy)

Data and other attributes inherited from CookieJar:
domain_re = <_sre.SRE_Pattern object>
dots_re = <_sre.SRE_Pattern object>
magic_re = r'^\#LWP-Cookies-(\d+\.\d+)'
non_word_re = <_sre.SRE_Pattern object>
quote_re = <_sre.SRE_Pattern object>
strict_domain_re = <_sre.SRE_Pattern object>

 
class LoadError(exceptions.Exception)
     Methods inherited from exceptions.Exception:
__getitem__(...)
__init__(...)
__str__(...)

 
Functions
       
deepvalues(mapping)
Iterates over nested mapping, depth-first, in sorted order by key.
domain_match(A, B)
Return True if domain A domain-matches domain B, according to RFC 2965.
 
A and B may be host domain names or IP addresses.
 
RFC 2965, section 1:
 
Host names can be specified either as an IP address or a HDN string.
Sometimes we compare one host name with another.  (Such comparisons SHALL
be case-insensitive.)  Host A's name domain-matches host B's if
 
     *  their host name strings string-compare equal; or
 
     * A is a HDN string and has the form NB, where N is a non-empty
        name string, B has the form .B', and B' is a HDN string.  (So,
        x.y.com domain-matches .Y.com but not Y.com.)
 
Note that domain-match is not a commutative operation: a.b.c.com
domain-matches .c.com, but not the reverse.
eff_request_host(request)
Return a tuple (request-host, effective request-host name).
 
As defined by RFC 2965, except both are lowercased.
escape_path(path)
Escape any invalid characters in HTTP URL, and uppercase all escapes.
http2time(text)
Returns time in seconds since epoch of time represented by a string.
 
Return value is an integer.
 
None is returned if the format of str is unrecognized, the time is outside
the representable range, or the timezone string is not recognized.  If the
string contains no timezone, UTC is assumed.
 
The timezone in the string may be numerical (like "-0800" or "+0100") or a
string timezone (like "UTC", "GMT", "BST" or "EST").  Currently, only the
timezone strings equivalent to UTC (zero offset) are known to the function.
 
The function loosely parses the following formats:
 
Wed, 09 Feb 1994 22:23:32 GMT       -- HTTP format
Tuesday, 08-Feb-94 14:15:29 GMT     -- old rfc850 HTTP format
Tuesday, 08-Feb-1994 14:15:29 GMT   -- broken rfc850 HTTP format
09 Feb 1994 22:23:32 GMT            -- HTTP format (no weekday)
08-Feb-94 14:15:29 GMT              -- rfc850 format (no weekday)
08-Feb-1994 14:15:29 GMT            -- broken rfc850 format (no weekday)
 
The parser ignores leading and trailing whitespace.  The time may be
absent.
 
If the year is given with only 2 digits, the function will select the
century that makes the year closest to the current date.
is_HDN(text)
Return True if text is a host domain name.
is_third_party(request)
RFC 2965, section 3.3.6:
 
    An unverifiable transaction is to a third-party host if its request-
    host U does not domain-match the reach R of the request-host O in the
    origin transaction.
iso2time(text)
As for http2time, but parses the ISO 8601 formats:
 
1994-02-03 14:15:29 -0100    -- ISO 8601 format
1994-02-03 14:15:29          -- zone is optional
1994-02-03                   -- only date
1994-02-03T14:15:29          -- Use T as separator
19940203T141529Z             -- ISO 8601 compact format
19940203                     -- only date
join_header_words(lists)
Do the inverse (almost) of the conversion done by split_header_words.
 
Takes a list of lists of (key, value) pairs and produces a single header
value.  Attribute values are quoted if needed.
 
>>> join_header_words([[("text/plain", None), ("charset", "iso-8859/1")]])
'text/plain; charset="iso-8859/1"'
>>> join_header_words([[("text/plain", None)], [("charset", "iso-8859/1")]])
'text/plain, charset="iso-8859/1"'
liberal_is_HDN(text)
Return True if text is a sort-of-like a host domain name.
 
For accepting/blocking domains.
offset_from_tz_string(tz)
parse_ns_headers(ns_headers)
Ad-hoc parser for Netscape protocol cookie-attributes.
 
The old Netscape cookie format for Set-Cookie can for instance contain
an unquoted "," in the expires field, so we have to use this ad-hoc
parser instead of split_header_words.
 
XXX This may not make the best possible effort to parse all the crap
that Netscape Cookie headers contain.  Ronald Tschalar's HTTPClient
parser is probably better, so could do worse than following that if
this ever gives any trouble.
 
Currently, this is also used for parsing RFC 2109 cookies.
reach(h)
Return reach of host h, as defined by RFC 2965, section 1.
 
The reach R of a host name H is defined as follows:
 
   *  If
 
      -  H is the host domain name of a host; and,
 
      -  H has the form A.B; and
 
      -  A has no embedded (that is, interior) dots; and
 
      -  B has at least one embedded dot, or B is the string "local".
         then the reach of H is .B.
 
   *  Otherwise, the reach of H is H.
 
>>> reach("www.acme.com")
'.acme.com'
>>> reach("acme.com")
'acme.com'
>>> reach("acme.local")
'.local'
request_host(request)
Return request-host, as defined by RFC 2965.
 
Variation from RFC: returned value is lowercased, for convenient
comparison.
request_path(request)
request-URI, as defined by RFC 2965.
request_port(request)
reraise_unmasked_exceptions(unmasked=())
split_header_words(header_values)
Parse header values into a list of lists containing key,value pairs.
 
The function knows how to deal with ",", ";" and "=" as well as quoted
values after "=".  A list of space separated tokens are parsed as if they
were separated by ";".
 
If the header_values passed as argument contains multiple values, then they
are treated as if they were a single value separated by comma ",".
 
This means that this function is useful for parsing header fields that
follow this syntax (BNF as from the HTTP/1.1 specification, but we relax
the requirement for tokens).
 
  headers           = #header
  header            = (token | parameter) *( [";"] (token | parameter))
 
  token             = 1*<any CHAR except CTLs or separators>
  separators        = "(" | ")" | "<" | ">" | "@"
                    | "," | ";" | ":" | "\" | <">
                    | "/" | "[" | "]" | "?" | "="
                    | "{" | "}" | SP | HT
 
  quoted-string     = ( <"> *(qdtext | quoted-pair ) <"> )
  qdtext            = <any TEXT except <">>
  quoted-pair       = "\" CHAR
 
  parameter         = attribute "=" value
  attribute         = token
  value             = token | quoted-string
 
Each header is represented by a list of key/value pairs.  The value for a
simple token (not part of a parameter) is None.  Syntactically incorrect
headers will not necessarily be parsed as you would want.
 
This is easier to describe with some examples:
 
>>> split_header_words(['foo="bar"; port="80,81"; discard, bar=baz'])
[[('foo', 'bar'), ('port', '80,81'), ('discard', None)], [('bar', 'baz')]]
>>> split_header_words(['text/html; charset="iso-8859-1"'])
[[('text/html', None), ('charset', 'iso-8859-1')]]
>>> split_header_words([r'Basic realm="\"foo\bar\""'])
[[('Basic', None), ('realm', '"foobar"')]]
time2isoz(t=None)
Return a string representing time in seconds since epoch, t.
 
If the function is called without an argument, it will use the current
time.
 
The format of the returned string is like "YYYY-MM-DD hh:mm:ssZ",
representing Universal Time (UTC, aka GMT).  An example of this format is:
 
1994-11-24 08:49:37Z
time2netscape(t=None)
Return a string representing time in seconds since epoch, t.
 
If the function is called without an argument, it will use the current
time.
 
The format of the returned string is like this:
 
Wed, DD-Mon-YYYY HH:MM:SS GMT
unmatched(match)
Return unmatched part of re.Match object.
uppercase_escaped_char(match)
user_domain_match(A, B)
For blocking/accepting domains.
 
A and B may be host domain names or IP addresses.
vals_sorted_by_key(adict)

 
Data
        DAYS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
DEFAULT_HTTP_PORT = '80'
EPOCH_YEAR = 1970
ESCAPED_CHAR_RE = <_sre.SRE_Pattern object>
HEADER_ESCAPE_RE = <_sre.SRE_Pattern object>
HEADER_JOIN_ESCAPE_RE = <_sre.SRE_Pattern object>
HEADER_QUOTED_VALUE_RE = <_sre.SRE_Pattern object>
HEADER_TOKEN_RE = <_sre.SRE_Pattern object>
HEADER_VALUE_RE = <_sre.SRE_Pattern object>
HTTP_PATH_SAFE = "%/;:@&=+$,!~*'()"
IPV4_RE = <_sre.SRE_Pattern object>
ISO_DATE_RE = <_sre.SRE_Pattern object>
LOOSE_HTTP_DATE_RE = <_sre.SRE_Pattern object>
MISSING_FILENAME_TEXT = 'a filename was not supplied (nor was the CookieJar instance initialised with one)'
MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
MONTHS_LOWER = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec']
STRICT_DATE_RE = <_sre.SRE_Pattern object>
StringTypes = (<type 'str'>, <type 'unicode'>)
TIMEZONE_RE = <_sre.SRE_Pattern object>
UTC_ZONES = {'GMT': None, 'UT': None, 'UTC': None, 'Z': None}
WEEKDAY_RE = <_sre.SRE_Pattern object>
cut_port_re = <_sre.SRE_Pattern object>
month = 'Dec'