mirror of https://github.com/python/cpython
[Patch #969900] Various corrections and updates to cookielib docs
This commit is contained in:
Andrew M. Kuchling
parent
ae40c2f795
commit
3a2418a1d6
|
|
@ -140,17 +140,18 @@ RFC 2965.}
|
|||
|
||||
\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()},
|
||||
|
|
@ -279,15 +280,17 @@ this happens.
|
|||
\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}
|
||||
|
||||
|
||||
|
|
@ -303,7 +306,7 @@ that reads Microsoft Internet Explorer cookies, are available at
|
|||
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}.}
|
||||
|
||||
|
|
@ -351,9 +354,8 @@ Return false if cookies should not be returned, given cookie domain.
|
|||
|
||||
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,
|
||||
|
|
@ -386,20 +388,22 @@ attributes, indicating which protocols should be used, and how. All
|
|||
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}}
|
||||
|
|
@ -440,8 +444,9 @@ the \var{blocked_domains} constructor argument, and
|
|||
\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
|
||||
|
|
@ -534,10 +539,10 @@ because \code{www.foo} contains a dot).
|
|||
\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.
|
||||
|
|
@ -574,17 +579,17 @@ Integer or \constant{None}. Netscape cookies have version 0. RFC
|
|||
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.
|
||||
|
|
@ -614,7 +619,7 @@ True if a domain was explicitly specified by the server.
|
|||
\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
|
||||
|
|
@ -652,13 +657,13 @@ r = opener.open("http://example.com/")
|
|||
\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}
|
||||
|
|
@ -670,9 +675,10 @@ cookies or having them returned:
|
|||
|
||||
\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/")
|
||||
|
|
|
|||
Loading…
Reference in New Issue