\subsection{CookieJar and FileCookieJar Objects \label{cookie-jar-objects}}
-\class{CookieJar} objects support the iterator protocol.
+\class{CookieJar} objects support the iterator protocol for iterating
+over contained \class{Cookie} objects.
\class{CookieJar} has the following methods:
\begin{methoddesc}[CookieJar]{add_cookie_header}{request}
Add correct \mailheader{Cookie} header to \var{request}.
-If the CookiePolicy allows (ie. the \class{CookiePolicy} instance's
-\member{rfc2965} and \member{hide_cookie2} attributes are true and
-false respectively), the \mailheader{Cookie2} header is also added
-when appropriate.
+If policy allows (ie. the \member{rfc2965} and \member{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 \var{request} object (usually a \class{urllib2.Request} instance)
must support the methods \method{get_full_url()}, \method{get_host()},
\class{FileCookieJar} instances have the following public attributes:
\begin{memberdesc}{filename}
-Filename of default file in which to keep cookies.
+Filename of default file in which to keep cookies. This attribute may
+be assigned to.
\end{memberdesc}
\begin{memberdesc}{delayload}
-If true, load cookies lazily from disk. 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.
+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.
\end{memberdesc}
policy=\constant{None}}
A \class{FileCookieJar} that can load from and save cookies to disk in
the Mozilla \code{cookies.txt} file format (which is also used by the
-lynx and Netscape browsers). \note{This loses information about RFC
+Lynx and Netscape browsers). \note{This loses information about RFC
2965 cookies, and also about newer or non-standard cookie-attributes
such as \code{port}.}
This method is an optimization. It removes the need for checking
every cookie with a particular domain (which might involve reading
-many files). The default implementations of
-\method{domain_return_ok()} and \method{path_return_ok()}
-(\samp{return True}) leave all the work to \method{return_ok()}.
+many files). Returning true from \method{domain_return_ok()} and
+\method{path_return_ok()} leaves all the work to \method{return_ok()}.
If \method{domain_return_ok()} returns true for the cookie domain,
\method{path_return_ok()} is called for the cookie path. Otherwise,
of these attributes may be assigned to.
\begin{memberdesc}{netscape}
-Implement netscape protocol.
+Implement Netscape protocol.
\end{memberdesc}
\begin{memberdesc}{rfc2965}
Implement RFC 2965 protocol.
\end{memberdesc}
\begin{memberdesc}{hide_cookie2}
-Don't add Cookie2 header to requests (the presence of this header
-indicates to the server that we understand RFC 2965 cookies).
+Don't add \mailheader{Cookie2} header to requests (the presence of
+this header indicates to the server that we understand RFC 2965
+cookies).
\end{memberdesc}
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.
+a 'null policy' to allow setting and receiving any and all cookies
+(this is unlikely to be useful).
\subsection{DefaultCookiePolicy Objects \label{default-cookie-policy-objects}}
\var{allowed_domains}). If you set a whitelist, you can turn it off
again by setting it to \constant{None}.
-Domains in block or allow lists that do not start with a dot must be
-equal. For example, \code{"example.com"} matches a blacklist entry of
+Domains in block or allow lists that do not start with a dot must
+equal the cookie domain to be matched. For example,
+\code{"example.com"} matches a blacklist entry of
\code{"example.com"}, but \code{"www.example.com"} does not. Domains
that do start with a dot are matched by more specific domains too.
For example, both \code{"www.example.com"} and
\end{memberdesc}
\begin{memberdesc}{DomainStrictNonDomain}
Cookies that did not explicitly specify a \code{domain}
-cookie-attribute can only be returned to a domain that string-compares
-equal to the domain that set the cookie (eg. \code{spam.example.com}
-won't be returned cookies from \code{example.com} that had no
-\code{domain} cookie-attribute).
+cookie-attribute can only be returned to a domain equal to the domain
+that set the cookie (eg. \code{spam.example.com} won't be returned
+cookies from \code{example.com} that had no \code{domain}
+cookie-attribute).
\end{memberdesc}
\begin{memberdesc}{DomainRFC2965Match}
When setting cookies, require a full RFC 2965 domain-match.
2965 and RFC 2109 cookies have version 1.
\end{memberdesc}
\begin{memberdesc}[Cookie]{name}
-Cookie name (a string), or \constant{None}.
+Cookie name (a string).
\end{memberdesc}
\begin{memberdesc}[Cookie]{value}
-Cookie value (a string).
+Cookie value (a string), or \constant{None}.
\end{memberdesc}
\begin{memberdesc}[Cookie]{port}
String representing a port or a set of ports (eg. '80', or '80,8080'),
or \constant{None}.
\end{memberdesc}
\begin{memberdesc}[Cookie]{path}
-Cookie path (a string, eg. '/acme/rocket_launchers').
+Cookie path (a string, eg. \code{'/acme/rocket_launchers'}).
\end{memberdesc}
\begin{memberdesc}[Cookie]{secure}
True if cookie should only be returned over a secure connection.
\end{memberdesc}
\begin{memberdesc}[Cookie]{domain_initial_dot}
True if the domain explicitly specified by the server began with a
-dot ('.').
+dot (\code{'.'}).
\end{memberdesc}
Cookies may have additional non-standard cookie-attributes. These may
\end{verbatim}
This example illustrates how to open a URL using your Netscape,
-Mozilla, or lynx cookies (assumes \UNIX{} convention for location of
-the cookies file):
+Mozilla, or Lynx cookies (assumes \UNIX{}/Netscape convention for
+location of the cookies file):
\begin{verbatim}
import os, cookielib, urllib2
cj = cookielib.MozillaCookieJar()
-cj.load(os.path.join(os.environ["HOME"], "/.netscape/cookies.txt"))
+cj.load(os.path.join(os.environ["HOME"], ".netscape/cookies.txt"))
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
\end{verbatim}
\begin{verbatim}
import urllib2
-from cookielib import CookieJar, DefaultCookiePolicy as Policy
-policy = Policy(rfc2965=True, strict_ns_domain=Policy.DomainStrict,
- blocked_domains=["ads.net", ".ads.net"])
+from cookielib import CookieJar, DefaultCookiePolicy
+policy = DefaultCookiePolicy(
+ rfc2965=True, strict_ns_domain=Policy.DomainStrict,
+ blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
projects / python / commitdiff