cookielib
index
/usr/local/lib/python2.5/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 BSDDBCookieJar and the MSIE* classes 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
re
time
urllib
urlparse

 
Classes
       
Cookie
CookieJar
FileCookieJar
_MozillaCookieJar.MozillaCookieJar
CookiePolicy
DefaultCookiePolicy
FileCookieJar(CookieJar)
_LWPCookieJar.LWPCookieJar
exceptions.IOError(exceptions.EnvironmentError)
LoadError

 
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, rfc2109=False)
__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 at 0xb6dbe3e0>
dots_re = <_sre.SRE_Pattern object at 0xb6d74d90>
magic_re = r'^\#LWP-Cookies-(\d+\.\d+)'
non_word_re = <_sre.SRE_Pattern object at 0xb6d81848>
quote_re = <_sre.SRE_Pattern object at 0xb6ecff20>
strict_domain_re = <_sre.SRE_Pattern object at 0xb6d74d40>

 
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, rfc2109_as_netscape=None, 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 at 0xb6dbe3e0>
dots_re = <_sre.SRE_Pattern object at 0xb6d74d90>
magic_re = r'^\#LWP-Cookies-(\d+\.\d+)'
non_word_re = <_sre.SRE_Pattern object at 0xb6d81848>
quote_re = <_sre.SRE_Pattern object at 0xb6ecff20>
strict_domain_re = <_sre.SRE_Pattern object at 0xb6d74d40>

 
class LWPCookieJar(cookielib.FileCookieJar)
    The LWPCookieJar saves a sequence of"Set-Cookie3" lines.
"Set-Cookie3" is the format used by the libwww-perl libary, not known
to be compatible with any browser, but which is easy to read and
doesn't lose information about RFC 2965 cookies.
 
Additional methods
 
as_lwp_str(ignore_discard=True, ignore_expired=True)
 
 
Method resolution order:
LWPCookieJar
cookielib.FileCookieJar
cookielib.CookieJar

Methods defined here:
as_lwp_str(self, ignore_discard=True, ignore_expires=True)
Return cookies as a string of "
"-separated "Set-Cookie3" headers.
 
        ignore_discard and ignore_expires: see docstring for FileCookieJar.save
save(self, filename=None, ignore_discard=False, ignore_expires=False)

Methods inherited from cookielib.FileCookieJar:
__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.

Methods inherited from cookielib.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 cookielib.CookieJar:
domain_re = <_sre.SRE_Pattern object at 0xb709dde0>
dots_re = <_sre.SRE_Pattern object at 0xb7031390>
magic_re = r'^\#LWP-Cookies-(\d+\.\d+)'
non_word_re = <_sre.SRE_Pattern object at 0xb709f9f8>
quote_re = <_sre.SRE_Pattern object at 0xb7031110>
strict_domain_re = <_sre.SRE_Pattern object at 0xb70312a0>

 
class LoadError(exceptions.IOError)
    # derives from IOError for backwards-compatibility with Python 2.4.0
 
 
Method resolution order:
LoadError
exceptions.IOError
exceptions.EnvironmentError
exceptions.StandardError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Methods inherited from exceptions.IOError:
__init__(...)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Data and other attributes inherited from exceptions.IOError:
__new__ = <built-in method __new__ of type object at 0x8125d00>
T.__new__(S, ...) -> a new object with type S, a subtype of T

Methods inherited from exceptions.EnvironmentError:
__reduce__(...)
__str__(...)
x.__str__() <==> str(x)

Data descriptors inherited from exceptions.EnvironmentError:
errno
exception errno
filename
exception filename
message
exception message
strerror
exception strerror

Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)

Data descriptors inherited from exceptions.BaseException:
__dict__
args

 
class MozillaCookieJar(cookielib.FileCookieJar)
    WARNING: you may want to backup your browser's cookies file if you use
this class to save cookies.  I *think* it works, but there have been
bugs in the past!
 
This class differs from CookieJar only in the format it uses to save and
load cookies to and from a file.  This class uses the Mozilla/Netscape
`cookies.txt' format.  lynx uses this file format, too.
 
Don't expect cookies saved while the browser is running to be noticed by
the browser (in fact, Mozilla on unix will overwrite your saved cookies if
you change them on disk while it's running; on Windows, you probably can't
save at all while the browser is running).
 
Note that the Mozilla/Netscape format will downgrade RFC2965 cookies to
Netscape cookies on saving.
 
In particular, the cookie version and port number information is lost,
together with information about whether or not Path, Port and Discard were
specified by the Set-Cookie2 (or Set-Cookie) header, and whether or not the
domain as set in the HTTP header started with a dot (yes, I'm aware some
domains in Netscape files start with a dot and some don't -- trust me, you
really don't want to know any more about this).
 
Note that though Mozilla and Netscape use the same format, they use
slightly different headers.  The class saves cookies using the Netscape
header by default (Mozilla can cope with that).
 
 
Method resolution order:
MozillaCookieJar
cookielib.FileCookieJar
cookielib.CookieJar

Methods defined here:
save(self, filename=None, ignore_discard=False, ignore_expires=False)

Data and other attributes defined here:
header = ' # Netscape HTTP Cookie File\n # http://www...l\n # This is a generated file! Do not edit.\n\n'
magic_re = '#( Netscape)? HTTP Cookie File'

Methods inherited from cookielib.FileCookieJar:
__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.

Methods inherited from cookielib.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 cookielib.CookieJar:
domain_re = <_sre.SRE_Pattern object at 0xb6dbe3e0>
dots_re = <_sre.SRE_Pattern object at 0xb6d74d90>
non_word_re = <_sre.SRE_Pattern object at 0xb6d81848>
quote_re = <_sre.SRE_Pattern object at 0xb6ecff20>
strict_domain_re = <_sre.SRE_Pattern object at 0xb6d74d40>

 
Data
        __all__ = ['Cookie', 'CookieJar', 'CookiePolicy', 'DefaultCookiePolicy', 'FileCookieJar', 'LWPCookieJar', 'LoadError', 'MozillaCookieJar']