"""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/):
MozillaCookieJar | LWPCookieJar \ \
| / MSIEDBCookieJar BSDDBCookieJar
import sys
, re
, urlparse
, copy
, time
, urllib
, logging
from types
import StringTypes
import threading
as _threading
import dummy_threading
as _threading
import httplib
# only for the default HTTP port
from calendar
import timegm
debug
= logging
.getLogger("cookielib").debug
DEFAULT_HTTP_PORT
= str(httplib
.HTTP_PORT
)
MISSING_FILENAME_TEXT
= ("a filename was not supplied (nor was the CookieJar "
"instance initialised with one)")
def reraise_unmasked_exceptions(unmasked
=()):
# There are a few catch-all except: statements in this module, for
# catching input that's bad in unexpected ways.
# This function re-raises some exceptions we don't want to trap.
unmasked
= unmasked
+ (KeyboardInterrupt, SystemExit, MemoryError)
etype
= sys
.exc_info()[0]
if issubclass(etype
, unmasked
):
import warnings
, traceback
, StringIO
traceback
.print_exc(None, f
)
warnings
.warn("cookielib bug!\n%s" % msg
, stacklevel
=2)
# -----------------------------------------------------------------------------
year
, month
, mday
, hour
, min, sec
= tt
[:6]
if ((year
>= EPOCH_YEAR
) and (1 <= month
<= 12) and (1 <= mday
<= 31) and
(0 <= hour
<= 24) and (0 <= min <= 59) and (0 <= sec
<= 61)):
DAYS
= ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
MONTHS
= ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
for month
in MONTHS
: MONTHS_LOWER
.append(month
.lower())
"""Return a string representing time in seconds since epoch, t.
If the function is called without an argument, it will use the current
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:
if t
is None: t
= time
.time()
year
, mon
, mday
, hour
, min, sec
= time
.gmtime(t
)[:6]
return "%04d-%02d-%02d %02d:%02d:%02dZ" % (
year
, mon
, mday
, hour
, min, sec
)
def 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
The format of the returned string is like this:
Wed, DD-Mon-YYYY HH:MM:SS GMT
if t
is None: t
= time
.time()
year
, mon
, mday
, hour
, min, sec
, wday
= time
.gmtime(t
)[:7]
return "%s %02d-%s-%04d %02d:%02d:%02d GMT" % (
DAYS
[wday
], mday
, MONTHS
[mon
-1], year
, hour
, min, sec
)
UTC_ZONES
= {"GMT": None, "UTC": None, "UT": None, "Z": None}
TIMEZONE_RE
= re
.compile(r
"^([-+])?(\d\d?):?(\d\d)?$")
def offset_from_tz_string(tz
):
m
= TIMEZONE_RE
.search(tz
)
offset
= 3600 * int(m
.group(2))
offset
= offset
+ 60 * int(m
.group(3))
def _str2time(day
, mon
, yr
, hr
, min, sec
, tz
):
# translate month name to number
# month numbers start with 1 (January)
mon
= MONTHS_LOWER
.index(mon
.lower())+1
# maybe it's already a number
# make sure clock elements are defined
cur_yr
= time
.localtime(time
.time())[0]
# convert UTC time tuple to seconds since epoch (not timezone-adjusted)
t
= _timegm((yr
, mon
, day
, hr
, min, sec
, tz
))
# adjust time using timezone string, to get absolute time since epoch
offset
= offset_from_tz_string(tz
)
STRICT_DATE_RE
= re
.compile(
r
"^[SMTWF][a-z][a-z], (\d\d) ([JFMASOND][a-z][a-z]) "
"(\d\d\d\d) (\d\d):(\d\d):(\d\d) GMT$")
r
"^(?:Sun|Mon|Tue|Wed|Thu|Fri|Sat)[a-z]*,?\s*", re
.I
)
LOOSE_HTTP_DATE_RE
= re
.compile(
(?:\s+|:) # separator before clock
(\d\d?):(\d\d) # hour:min
(?::(\d\d))? # optional seconds
([-+]?\d{2,4}|(?![APap][Mm]\b)[A-Za-z]+)? # timezone
(?:\(\w+\))? # ASCII representation of timezone in parens.
"""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
If the year is given with only 2 digits, the function will select the
century that makes the year closest to the current date.
# fast exit for strictly conforming string
m
= STRICT_DATE_RE
.search(text
)
mon
= MONTHS_LOWER
.index(g
[1].lower()) + 1
tt
= (int(g
[2]), mon
, int(g
[0]),
int(g
[3]), int(g
[4]), float(g
[5]))
# No, we need some messy parsing...
text
= WEEKDAY_RE
.sub("", text
, 1) # Useless weekday
# tz is time zone specifier string
day
, mon
, yr
, hr
, min, sec
, tz
= [None]*7
m
= LOOSE_HTTP_DATE_RE
.search(text
)
day
, mon
, yr
, hr
, min, sec
, tz
= m
.groups()
return _str2time(day
, mon
, yr
, hr
, min, sec
, tz
)
ISO_DATE_RE
= re
.compile(
(\d\d?) # numerical month
(?:\s+|[-:Tt]) # separator before clock
(\d\d?):?(\d\d) # hour:min
(?::?(\d\d(?:\.\d*)?))? # optional seconds (and fractional)
|Z|z)? # timezone (Z is "zero meridian", i.e. GMT)
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-03T14:15:29 -- Use T as separator
19940203T141529Z -- ISO 8601 compact format
# tz is time zone specifier string
day
, mon
, yr
, hr
, min, sec
, tz
= [None]*7
m
= ISO_DATE_RE
.search(text
)
# XXX there's an extra bit of the timezone I'm ignoring here: is
# this the right thing to do?
yr
, mon
, day
, hr
, min, sec
, tz
, _
= m
.groups()
return _str2time(day
, mon
, yr
, hr
, min, sec
, tz
)
# -----------------------------------------------------------------------------
"""Return unmatched part of re.Match object."""
start
, end
= match
.span(0)
return match
.string
[:start
]+match
.string
[end
:]
HEADER_TOKEN_RE
= re
.compile(r
"^\s*([^=\s;,]+)")
HEADER_QUOTED_VALUE_RE
= re
.compile(r
"^\s*=\s*\"([^
\"\\]*(?
:\\.[^
\"\\]*)*)\"")
HEADER_VALUE_RE = re.compile(r"^\s
*=\s
*([^\s
;,]*)")
HEADER_ESCAPE_RE = re.compile(r"\\(.)")
def split_header_words(header_values):
r"""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
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).
header = (token | parameter) *( [";"] (token | parameter))
token = 1*<any CHAR except CTLs or separators>
separators = "(" | ")" | "<" | ">" | "@"
| "," | ";" | ":" | "\" |
<">
| "/" | "[" | "]" | "?
" | "="
quoted-string = ( <"> *(qdtext | quoted
-pair
) <"> )
qdtext = <any TEXT except <">>
parameter = attribute "=" value
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
"')]]
assert type(header_values) not in StringTypes
for text in header_values:
m = HEADER_TOKEN_RE.search(text)
m = HEADER_QUOTED_VALUE_RE.search(text)
value = HEADER_ESCAPE_RE.sub(r"\
1", value)
m = HEADER_VALUE_RE.search(text)
pairs.append((name, value))
elif text.lstrip().startswith(","):
# concatenated headers, as per RFC 2616 section 4.2
if pairs: result.append(pairs)
non_junk, nr_junk_chars = re.subn("^
[=\s
;]*", "", text)
assert nr_junk_chars > 0, (
"split_header_words bug
: '%s', '%s', %s" %
(orig_text, text, pairs))
if pairs: result.append(pairs)
HEADER_JOIN_ESCAPE_RE = re.compile(r"([\"\\])")
def 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"'
if not re.search(r"^\w
+$
", v):
v = HEADER_JOIN_ESCAPE_RE.sub(r"\\\
1", v) # escape " and \
if attr
: headers
.append("; ".join(attr
))
return ", ".join(headers
)
def 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.
known_attrs
= ("expires", "domain", "path", "secure",
# RFC 2109 attrs (may turn up in Netscape cookies, too)
for ns_header
in ns_headers
:
for ii
, param
in enumerate(re
.split(r
";\s*", ns_header
)):
k
, v
= re
.split(r
"\s*=\s*", param
, 1)
# This is an RFC 2109 cookie. Will be treated as RFC 2965
# cookie in rest of code.
# Probably it should be parsed with split_header_words, but
# that's too much hassle.
# convert expires date to seconds since epoch
if v
.startswith('"'): v
= v
[1:]
if v
.endswith('"'): v
= v
[:-1]
v
= http2time(v
) # None if invalid
pairs
.append(("version", "0"))
IPV4_RE
= re
.compile(r
"\.\d+$")
"""Return True if text is a host domain name."""
# This may well be wrong. Which RFC is HDN defined in, if any (for
# the purposes of RFC 2965)?
# For the current implementation, what about IPv6? Remember to look
# at other uses of IPV4_RE also, if change this.
if text
[0] == "." or text
[-1] == ".":
"""Return True if domain A domain-matches domain B, according to RFC 2965.
A and B may be host domain names or IP addresses.
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.
# Note that, if A or B are IP addresses, the only relevant part of the
# definition of the domain-match algorithm is the direct string-compare.
# A does not have form NB, or N is the empty string
if not B
.startswith("."):
def liberal_is_HDN(text
):
"""Return True if text is a sort-of-like a host domain name.
For accepting/blocking domains.
def user_domain_match(A
, B
):
"""For blocking/accepting domains.
A and B may be host domain names or IP addresses.
if not (liberal_is_HDN(A
) and liberal_is_HDN(B
)):
initial_dot
= B
.startswith(".")
if initial_dot
and A
.endswith(B
):
if not initial_dot
and A
== B
:
cut_port_re
= re
.compile(r
":\d+$")
def request_host(request
):
"""Return request-host, as defined by RFC 2965.
Variation from RFC: returned value is lowercased, for convenient
url
= request
.get_full_url()
host
= urlparse
.urlparse(url
)[1]
host
= request
.get_header("Host", "")
# remove port, if present
host
= cut_port_re
.sub("", host
, 1)
def eff_request_host(request
):
"""Return a tuple (request-host, effective request-host name).
As defined by RFC 2965, except both are lowercased.
erhn
= req_host
= request_host(request
)
if req_host
.find(".") == -1 and not IPV4_RE
.search(req_host
):
erhn
= req_host
+ ".local"
def request_path(request
):
"""request-URI, as defined by RFC 2965."""
url
= request
.get_full_url()
#scheme, netloc, path, parameters, query, frag = urlparse.urlparse(url)
#req_path = escape_path("".join(urlparse.urlparse(url)[2:]))
path
, parameters
, query
, frag
= urlparse
.urlparse(url
)[2:]
path
= "%s;%s" % (path
, parameters
)
req_path
= urlparse
.urlunparse(("", "", path
, "", query
, frag
))
if not req_path
.startswith("/"):
# fix bad RFC 2396 absoluteURI
def request_port(request
):
host
= request
.get_host()
debug("nonnumeric port: '%s'", port
)
# Characters in addition to A-Z, a-z, 0-9, '_', '.', and '-' that don't
# need to be escaped to form a valid HTTP URL (RFCs 2396 and 1738).
HTTP_PATH_SAFE
= "%/;:@&=+$,!~*'()"
ESCAPED_CHAR_RE
= re
.compile(r
"%([0-9a-fA-F][0-9a-fA-F])")
def uppercase_escaped_char(match
):
return "%%%s" % match
.group(1).upper()
"""Escape any invalid characters in HTTP URL, and uppercase all escapes."""
# There's no knowing what character encoding was used to create URLs
# containing %-escapes, but since we have to pick one to escape invalid
# path characters, we pick UTF-8, as recommended in the HTML 4.0
# http://www.w3.org/TR/REC-html40/appendix/notes.html#h-B.2.1
# And here, kind of: draft-fielding-uri-rfc2396bis-03
# (And in draft IRI specification: draft-duerst-iri-05)
# (And here, for new URI schemes: RFC 2718)
if isinstance(path
, unicode):
path
= path
.encode("utf-8")
path
= urllib
.quote(path
, HTTP_PATH_SAFE
)
path
= ESCAPED_CHAR_RE
.sub(uppercase_escaped_char
, path
)
"""Return reach of host h, as defined by RFC 2965, section 1.
The reach R of a host name H is defined as follows:
- 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")
#a = h[:i] # this line is only here to show what a is
if is_HDN(h
) and (i
>= 0 or b
== "local"):
def is_third_party(request
):
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
req_host
= request_host(request
)
if not domain_match(req_host
, reach(request
.get_origin_req_host())):
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.
def __init__(self
, version
, name
, value
,
domain
, domain_specified
, domain_initial_dot
,
if version
is not None: version
= int(version
)
if expires
is not None: expires
= int(expires
)
if port
is None and port_specified
is True:
raise ValueError("if port is None, port_specified must be false")
self
.port_specified
= port_specified
# normalise case, as per RFC 2965 section 3.3.3
self
.domain
= domain
.lower()
self
.domain_specified
= domain_specified
# Sigh. We need to know whether the domain given in the
# cookie-attribute had an initial dot, in order to follow RFC 2965
# (as clarified in draft errata). Needed for the returned $Domain
self
.domain_initial_dot
= domain_initial_dot
self
.path_specified
= path_specified
self
.comment_url
= comment_url
self
._rest
= copy
.copy(rest
)
def has_nonstandard_attr(self
, name
):
return name
in self
._rest
def get_nonstandard_attr(self
, name
, default
=None):
return self
._rest
.get(name
, default
)
def set_nonstandard_attr(self
, name
, value
):
def is_expired(self
, now
=None):
if now
is None: now
= time
.time()
if (self
.expires
is not None) and (self
.expires
<= now
):
if self
.port
is None: p
= ""
limit
= self
.domain
+ p
+ self
.path
if self
.value
is not None:
namevalue
= "%s=%s" % (self
.name
, self
.value
)
return "<Cookie %s for %s>" % (namevalue
, limit
)
for name
in ["version", "name", "value",
"port", "port_specified",
"domain", "domain_specified", "domain_initial_dot",
"path", "path_specified",
"secure", "expires", "discard", "comment", "comment_url",
attr
= getattr(self
, name
)
args
.append("%s=%s" % (name
, repr(attr
)))
args
.append("rest=%s" % repr(self
._rest
))
return "Cookie(%s)" % ", ".join(args
)
"""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.
def 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.
raise NotImplementedError()
def return_ok(self
, cookie
, request
):
"""Return true if (and only if) cookie should be returned to server."""
raise NotImplementedError()
def domain_return_ok(self
, domain
, request
):
"""Return false if cookies should not be returned, given cookie domain.
def path_return_ok(self
, path
, request
):
"""Return false if cookies should not be returned, given cookie path.
class DefaultCookiePolicy(CookiePolicy
):
"""Implements the standard rules for accepting and returning cookies."""
DomainStrictNonDomain
= 2
DomainStrict
= DomainStrictNoDots|DomainStrictNonDomain
blocked_domains
=None, allowed_domains
=None,
netscape
=True, rfc2965
=False,
strict_rfc2965_unverifiable
=True,
strict_ns_unverifiable
=False,
strict_ns_domain
=DomainLiberal
,
strict_ns_set_initial_dollar
=False,
strict_ns_set_path
=False,
"""Constructor arguments should be passed as keyword arguments only."""
self
.hide_cookie2
= hide_cookie2
self
.strict_domain
= strict_domain
self
.strict_rfc2965_unverifiable
= strict_rfc2965_unverifiable
self
.strict_ns_unverifiable
= strict_ns_unverifiable
self
.strict_ns_domain
= strict_ns_domain
self
.strict_ns_set_initial_dollar
= strict_ns_set_initial_dollar
self
.strict_ns_set_path
= strict_ns_set_path
if blocked_domains
is not None:
self
._blocked
_domains
= tuple(blocked_domains
)
self
._blocked
_domains
= ()
if allowed_domains
is not None:
allowed_domains
= tuple(allowed_domains
)
self
._allowed
_domains
= allowed_domains
def blocked_domains(self
):
"""Return the sequence of blocked domains (as a tuple)."""
return self
._blocked
_domains
def set_blocked_domains(self
, blocked_domains
):
"""Set the sequence of blocked domains."""
self
._blocked
_domains
= tuple(blocked_domains
)
def is_blocked(self
, domain
):
for blocked_domain
in self
._blocked
_domains
:
if user_domain_match(domain
, blocked_domain
):
def allowed_domains(self
):
"""Return None, or the sequence of allowed domains (as a tuple)."""
return self
._allowed
_domains
def set_allowed_domains(self
, allowed_domains
):
"""Set the sequence of allowed domains, or None."""
if allowed_domains
is not None:
allowed_domains
= tuple(allowed_domains
)
self
._allowed
_domains
= allowed_domains
def is_not_allowed(self
, domain
):
if self
._allowed
_domains
is None:
for allowed_domain
in self
._allowed
_domains
:
if user_domain_match(domain
, allowed_domain
):
def 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).
debug(" - checking cookie %s=%s", cookie
.name
, cookie
.value
)
assert cookie
.name
is not None
for n
in "version", "verifiability", "name", "path", "domain", "port":
fn
= getattr(self
, fn_name
)
if not fn(cookie
, request
):
def set_ok_version(self
, cookie
, request
):
if cookie
.version
is None:
# Version is always set to 0 by parse_ns_headers if it's a Netscape
# cookie, so this must be an invalid RFC 2965 cookie.
debug(" Set-Cookie2 without version attribute (%s=%s)",
cookie
.name
, cookie
.value
)
if cookie
.version
> 0 and not self
.rfc2965
:
debug(" RFC 2965 cookies are switched off")
elif cookie
.version
== 0 and not self
.netscape
:
debug(" Netscape cookies are switched off")
def set_ok_verifiability(self
, cookie
, request
):
if request
.is_unverifiable() and is_third_party(request
):
if cookie
.version
> 0 and self
.strict_rfc2965_unverifiable
:
debug(" third-party RFC 2965 cookie during "
"unverifiable transaction")
elif cookie
.version
== 0 and self
.strict_ns_unverifiable
:
debug(" third-party Netscape cookie during "
"unverifiable transaction")
def set_ok_name(self
, cookie
, request
):
# Try and stop servers setting V0 cookies designed to hack other
# servers that know both V0 and V1 protocols.
if (cookie
.version
== 0 and self
.strict_ns_set_initial_dollar
and
cookie
.name
.startswith("$")):
debug(" illegal name (starts with '$'): '%s'", cookie
.name
)
def set_ok_path(self
, cookie
, request
):
if cookie
.path_specified
:
req_path
= request_path(request
)
if ((cookie
.version
> 0 or
(cookie
.version
== 0 and self
.strict_ns_set_path
)) and
not req_path
.startswith(cookie
.path
)):
debug(" path attribute %s is not a prefix of request "
"path %s", cookie
.path
, req_path
)
def set_ok_domain(self
, cookie
, request
):
if self
.is_blocked(cookie
.domain
):
debug(" domain %s is in user block-list", cookie
.domain
)
if self
.is_not_allowed(cookie
.domain
):
debug(" domain %s is not in user allow-list", cookie
.domain
)
if cookie
.domain_specified
:
req_host
, erhn
= eff_request_host(request
)
if self
.strict_domain
and (domain
.count(".") >= 2):
j
= domain
.rfind(".", 0, i
)
if j
== 0: # domain like .foo.bar
"com", "edu", "org", "net", "gov", "mil", "int"] and
debug(" country-code second level domain %s", domain
)
if domain
.startswith("."):
undotted_domain
= domain
[1:]
embedded_dots
= (undotted_domain
.find(".") >= 0)
if not embedded_dots
and domain
!= ".local":
debug(" non-local domain %s contains no embedded dot",
if (not erhn
.endswith(domain
) and
(not erhn
.startswith(".") and
not ("."+erhn
).endswith(domain
))):
debug(" effective request-host %s (even with added "
"initial dot) does not end end with %s",
if (cookie
.version
> 0 or
(self
.strict_ns_domain
& self
.DomainRFC2965Match
)):
if not domain_match(erhn
, domain
):
debug(" effective request-host %s does not domain-match "
if (cookie
.version
> 0 or
(self
.strict_ns_domain
& self
.DomainStrictNoDots
)):
host_prefix
= req_host
[:-len(domain
)]
if (host_prefix
.find(".") >= 0 and
not IPV4_RE
.search(req_host
)):
debug(" host prefix %s for domain %s contains a dot",
def set_ok_port(self
, cookie
, request
):
if cookie
.port_specified
:
req_port
= request_port(request
)
for p
in cookie
.port
.split(","):
debug(" bad port %s (not numeric)", p
)
debug(" request port (%s) not found in %s",
def 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).
# Path has already been checked by .path_return_ok(), and domain
# blocking done by .domain_return_ok().
debug(" - checking cookie %s=%s", cookie
.name
, cookie
.value
)
for n
in "version", "verifiability", "secure", "expires", "port", "domain":
fn
= getattr(self
, fn_name
)
if not fn(cookie
, request
):
def return_ok_version(self
, cookie
, request
):
if cookie
.version
> 0 and not self
.rfc2965
:
debug(" RFC 2965 cookies are switched off")
elif cookie
.version
== 0 and not self
.netscape
:
debug(" Netscape cookies are switched off")
def return_ok_verifiability(self
, cookie
, request
):
if request
.is_unverifiable() and is_third_party(request
):
if cookie
.version
> 0 and self
.strict_rfc2965_unverifiable
:
debug(" third-party RFC 2965 cookie during unverifiable "
elif cookie
.version
== 0 and self
.strict_ns_unverifiable
:
debug(" third-party Netscape cookie during unverifiable "
def return_ok_secure(self
, cookie
, request
):
if cookie
.secure
and request
.get_type() != "https":
debug(" secure cookie with non-secure request")
def return_ok_expires(self
, cookie
, request
):
if cookie
.is_expired(self
._now
):
def return_ok_port(self
, cookie
, request
):
req_port
= request_port(request
)
for p
in cookie
.port
.split(","):
debug(" request port %s does not match cookie port %s",
def return_ok_domain(self
, cookie
, request
):
req_host
, erhn
= eff_request_host(request
)
# strict check of non-domain cookies: Mozilla does this, MSIE5 doesn't
if (cookie
.version
== 0 and
(self
.strict_ns_domain
& self
.DomainStrictNonDomain
) and
not cookie
.domain_specified
and domain
!= erhn
):
debug(" cookie with unspecified domain does not string-compare "
"equal to request domain")
if cookie
.version
> 0 and not domain_match(erhn
, domain
):
debug(" effective request-host name %s does not domain-match "
"RFC 2965 cookie domain %s", erhn
, domain
)
if cookie
.version
== 0 and not ("."+erhn
).endswith(domain
):
debug(" request-host %s does not match Netscape cookie domain "
def domain_return_ok(self
, domain
, request
):
# Liberal check of. This is here as an optimization to avoid
# having to load lots of MSIE cookie files unless necessary.
req_host
, erhn
= eff_request_host(request
)
if not req_host
.startswith("."):
if not erhn
.startswith("."):
if not (req_host
.endswith(domain
) or erhn
.endswith(domain
)):
#debug(" request domain %s does not match cookie domain %s",
if self
.is_blocked(domain
):
debug(" domain %s is in user block-list", domain
)
if self
.is_not_allowed(domain
):
debug(" domain %s is not in user allow-list", domain
)
def path_return_ok(self
, path
, request
):
debug("- checking cookie path=%s", path
)
req_path
= request_path(request
)
if not req_path
.startswith(path
):
debug(" %s does not path-match %s", req_path
, path
)
def vals_sorted_by_key(adict
):
return map(adict
.get
, keys
)
"""Iterates over nested mapping, depth-first, in sorted order by key."""
values
= vals_sorted_by_key(mapping
)
for subobj
in deepvalues(obj
):
# Used as second parameter to dict.get() method, to distinguish absent
# dict key from one with a None value.
"""Collection of HTTP cookies.
You may not need to know about this class: try
urllib2.build_opener(HTTPCookieProcessor).open(url).
non_word_re
= re
.compile(r
"\W")
quote_re
= re
.compile(r
"([\"\\])")
strict_domain_re = re.compile(r"\
.?
[^
.]*")
domain_re = re.compile(r"[^
.]*")
dots_re = re.compile(r"^\
.+")
magic_re = r"^\
#LWP-Cookies-(\d+\.\d+)"
def __init__(self
, policy
=None):
policy
= DefaultCookiePolicy()
self
._cookies
_lock
= _threading
.RLock()
def set_policy(self
, policy
):
def _cookies_for_domain(self
, domain
, request
):
if not self
._policy
.domain_return_ok(domain
, request
):
debug("Checking %s for cookies to return", domain
)
cookies_by_path
= self
._cookies
[domain
]
for path
in cookies_by_path
.keys():
if not self
._policy
.path_return_ok(path
, request
):
cookies_by_name
= cookies_by_path
[path
]
for cookie
in cookies_by_name
.values():
if not self
._policy
.return_ok(cookie
, request
):
debug(" not returning cookie")
def _cookies_for_request(self
, request
):
"""Return a list of cookies to be returned to server."""
for domain
in self
._cookies
.keys():
cookies
.extend(self
._cookies
_for
_domain
(domain
, request
))
def _cookie_attrs(self
, cookies
):
"""Return a list of cookie-attributes to be returned to server.
like ['foo="bar"; $Path="/"', ...]
The $Version attribute is also added when appropriate (currently only
# add cookies in order of most specific (ie. longest) path first
def decreasing_size(a
, b
): return cmp(len(b
.path
), len(a
.path
))
cookies
.sort(decreasing_size
)
# set version of Cookie header
# What should it be if multiple matching Set-Cookie headers have
# different versions themselves?
# Answer: there is no answer; was supposed to be settled by
# RFC 2965 errata, but that may never appear...
attrs
.append("$Version=%s" % version
)
# quote cookie value if necessary
# (not for Netscape protocol, which already has any quotes
# intact, due to the poorly-specified Netscape Cookie: syntax)
if ((cookie
.value
is not None) and
self
.non_word_re
.search(cookie
.value
) and version
> 0):
value
= self
.quote_re
.sub(r
"\\\1", cookie
.value
)
# add cookie-attributes to be returned in Cookie header
attrs
.append(cookie
.name
)
attrs
.append("%s=%s" % (cookie
.name
, value
))
if cookie
.path_specified
:
attrs
.append('$Path="%s"' % cookie
.path
)
if cookie
.domain
.startswith("."):
if (not cookie
.domain_initial_dot
and
attrs
.append('$Domain="%s"' % domain
)
if cookie
.port
is not None:
if cookie
.port_specified
:
p
= p
+ ('="%s"' % cookie
.port
)
def 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.
debug("add_cookie_header")
self
._cookies
_lock
.acquire()
self
._policy
._now
= self
._now
= int(time
.time())
req_host
, erhn
= eff_request_host(request
)
self
._policy
.strict_ns_domain
& self
._policy
.DomainStrictNonDomain
)
cookies
= self
._cookies
_for
_request
(request
)
attrs
= self
._cookie
_attrs
(cookies
)
if not request
.has_header("Cookie"):
request
.add_unredirected_header(
"Cookie", "; ".join(attrs
))
# if necessary, advertise that we know RFC 2965
if (self
._policy
.rfc2965
and not self
._policy
.hide_cookie2
and
not request
.has_header("Cookie2")):
request
.add_unredirected_header("Cookie2", '$Version="1"')
self
._cookies
_lock
.release()
self
.clear_expired_cookies()
def _normalized_cookie_tuples(self
, attrs_set
):
"""Return list of tuples containing normalised cookie information.
attrs_set is the list of lists of key,value pairs extracted from
the Set-Cookie or Set-Cookie2 headers.
Tuples are name, value, standard, rest, where name and value are the
cookie name and value, standard is a dictionary containing the standard
cookie-attributes (discard, secure, version, expires or max-age,
domain, path and port) and rest is a dictionary containing the rest of
boolean_attrs
= "discard", "secure"
value_attrs
= ("version",
"domain", "path", "port",
for cookie_attrs
in attrs_set
:
name
, value
= cookie_attrs
[0]
# Build dictionary of standard cookie-attributes (standard) and
# dictionary of other cookie-attributes (rest).
# Note: expiry time is normalised to seconds since epoch. V0
# cookies should have the Expires cookie-attribute, and V1 cookies
# should have Max-Age, but since V1 includes RFC 2109 cookies (and
# since V0 cookies may be a mish-mash of Netscape and RFC 2109), we
# accept either (but prefer Max-Age).
for k
, v
in cookie_attrs
[1:]:
# don't lose case distinction for unknown fields
if lc
in value_attrs
or lc
in boolean_attrs
:
if k
in boolean_attrs
and v
is None:
# boolean cookie-attribute is present, but has no value
# (like "discard", rather than "port=80")
# only first value is significant
debug(" missing value for domain attribute")
# Prefer max-age to expires (like Mozilla)
debug(" missing or invalid value for expires "
"attribute: treating as session cookie")
debug(" missing or invalid (non-numeric) value for "
# convert RFC 2965 Max-Age to seconds since epoch
# XXX Strictly you're supposed to follow RFC 2616
# age-calculation rules. Remember that zero Max-Age is a
# is a request to discard (old and new) cookie, though.
if (k
in value_attrs
) or (k
in boolean_attrs
):
k
not in ["port", "comment", "commenturl"]):
debug(" missing value for %s attribute" % k
)
cookie_tuples
.append((name
, value
, standard
, rest
))
def _cookie_from_cookie_tuple(self
, tup
, request
):
# standard is dict of standard cookie-attributes, rest is dict of the
name
, value
, standard
, rest
= tup
domain
= standard
.get("domain", Absent
)
path
= standard
.get("path", Absent
)
port
= standard
.get("port", Absent
)
expires
= standard
.get("expires", Absent
)
version
= standard
.get("version", None)
if version
is not None: version
= int(version
)
secure
= standard
.get("secure", False)
# (discard is also set if expires is Absent)
discard
= standard
.get("discard", False)
comment
= standard
.get("comment", None)
comment_url
= standard
.get("commenturl", None)
if path
is not Absent
and path
!= "":
path
= request_path(request
)
# Netscape spec parts company from reality here
if len(path
) == 0: path
= "/"
domain_specified
= domain
is not Absent
# but first we have to remember whether it starts with a dot
domain_initial_dot
= False
domain_initial_dot
= bool(domain
.startswith("."))
req_host
, erhn
= eff_request_host(request
)
elif not domain
.startswith("."):
# Port attr present, but has no value: default to request port.
# Cookie should then only be sent back on that port.
port
= request_port(request
)
port
= re
.sub(r
"\s+", "", port
)
# No port attr present. Cookie can be sent back on any port.
# set default expires and discard
elif expires
<= self
._now
:
# Expiry date in past is request to delete cookie. This can't be
# in DefaultCookiePolicy, because can't delete cookies there.
self
.clear(domain
, path
, name
)
debug("Expiring cookie, domain='%s', path='%s', name='%s'",
domain
, domain_specified
, domain_initial_dot
,
def _cookies_from_attrs_set(self
, attrs_set
, request
):
cookie_tuples
= self
._normalized
_cookie
_tuples
(attrs_set
)
for tup
in cookie_tuples
:
cookie
= self
._cookie
_from
_cookie
_tuple
(tup
, request
)
if cookie
: cookies
.append(cookie
)
def make_cookies(self
, response
, request
):
"""Return sequence of Cookie objects extracted from response object."""
# get cookie-attributes for RFC 2965 and Netscape protocols
headers
= response
.info()
rfc2965_hdrs
= headers
.getheaders("Set-Cookie2")
ns_hdrs
= headers
.getheaders("Set-Cookie")
rfc2965
= self
._policy
.rfc2965
netscape
= self
._policy
.netscape
if ((not rfc2965_hdrs
and not ns_hdrs
) or
(not ns_hdrs
and not rfc2965
) or
(not rfc2965_hdrs
and not netscape
) or
(not netscape
and not rfc2965
)):
return [] # no relevant cookie headers: quick exit
cookies
= self
._cookies
_from
_attrs
_set
(
split_header_words(rfc2965_hdrs
), request
)
reraise_unmasked_exceptions()
ns_cookies
= self
._cookies
_from
_attrs
_set
(
parse_ns_headers(ns_hdrs
), request
)
reraise_unmasked_exceptions()
# Look for Netscape cookies (from Set-Cookie headers) that match
# corresponding RFC 2965 cookies (from Set-Cookie2 headers).
# For each match, keep the RFC 2965 cookie and ignore the Netscape
# cookie (RFC 2965 section 9.1). Actually, RFC 2109 cookies are
# bundled in with the Netscape cookies for this purpose, which is
lookup
[(cookie
.domain
, cookie
.path
, cookie
.name
)] = None
def no_matching_rfc2965(ns_cookie
, lookup
=lookup
):
key
= ns_cookie
.domain
, ns_cookie
.path
, ns_cookie
.name
ns_cookies
= filter(no_matching_rfc2965
, ns_cookies
)
cookies
.extend(ns_cookies
)
def set_cookie_if_ok(self
, cookie
, request
):
"""Set a cookie if policy says it's OK to do so."""
self
._cookies
_lock
.acquire()
self
._policy
._now
= self
._now
= int(time
.time())
if self
._policy
.set_ok(cookie
, request
):
self
._cookies
_lock
.release()
def set_cookie(self
, cookie
):
"""Set a cookie, without checking whether or not it should be set."""
self
._cookies
_lock
.acquire()
if cookie
.domain
not in c
: c
[cookie
.domain
] = {}
if cookie
.path
not in c2
: c2
[cookie
.path
] = {}
self
._cookies
_lock
.release()
def extract_cookies(self
, response
, request
):
"""Extract cookies from response, where allowable given the request."""
debug("extract_cookies: %s", response
.info())
self
._cookies
_lock
.acquire()
self
._policy
._now
= self
._now
= int(time
.time())
for cookie
in self
.make_cookies(response
, request
):
if self
._policy
.set_ok(cookie
, request
):
debug(" setting cookie: %s", cookie
)
self
._cookies
_lock
.release()
def clear(self
, domain
=None, path
=None, name
=None):
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.
if (domain
is None) or (path
is None):
"domain and path must be given to remove a cookie by name")
del self
._cookies
[domain
][path
][name
]
"domain must be given to remove cookies by path")
del self
._cookies
[domain
][path
]
del self
._cookies
[domain
]
def 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.
self
._cookies
_lock
.acquire()
self
.clear(cookie
.domain
, cookie
.path
, cookie
.name
)
self
._cookies
_lock
.release()
def 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).
self
._cookies
_lock
.acquire()
if cookie
.is_expired(now
):
self
.clear(cookie
.domain
, cookie
.path
, cookie
.name
)
self
._cookies
_lock
.release()
return deepvalues(self
._cookies
)
"""Return number of contained cookies."""
for cookie
in self
: i
= i
+ 1
for cookie
in self
: r
.append(repr(cookie
))
return "<%s[%s]>" % (self
.__class
__, ", ".join(r
))
for cookie
in self
: r
.append(str(cookie
))
return "<%s[%s]>" % (self
.__class
__, ", ".join(r
))
class LoadError(Exception): pass
class FileCookieJar(CookieJar
):
"""CookieJar that can be loaded from and saved to a file."""
def __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.
CookieJar
.__init
__(self
, policy
)
raise ValueError("filename must be string-like")
self
.delayload
= bool(delayload
)
def save(self
, filename
=None, ignore_discard
=False, ignore_expires
=False):
"""Save cookies to a file."""
raise NotImplementedError()
def load(self
, filename
=None, ignore_discard
=False, ignore_expires
=False):
"""Load cookies from a file."""
if self
.filename
is not None: filename
= self
.filename
else: raise ValueError(MISSING_FILENAME_TEXT
)
self
._really
_load
(f
, filename
, ignore_discard
, ignore_expires
)
def 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.
if self
.filename
is not None: filename
= self
.filename
else: raise ValueError(MISSING_FILENAME_TEXT
)
self
._cookies
_lock
.acquire()
old_state
= copy
.deepcopy(self
._cookies
)
self
.load(filename
, ignore_discard
, ignore_expires
)
except (LoadError
, IOError):
self
._cookies
= old_state
self
._cookies
_lock
.release()
from _LWPCookieJar
import LWPCookieJar
, lwp_cookie_str
from _MozillaCookieJar
import MozillaCookieJar