diff options
Diffstat (limited to 'Doc/lib/libcookielib.tex')
| -rw-r--r-- | Doc/lib/libcookielib.tex | 720 |
1 files changed, 0 insertions, 720 deletions
diff --git a/Doc/lib/libcookielib.tex b/Doc/lib/libcookielib.tex deleted file mode 100644 index 2ea3554..0000000 --- a/Doc/lib/libcookielib.tex +++ /dev/null @@ -1,720 +0,0 @@ -\section{\module{cookielib} --- - Cookie handling for HTTP clients} - -\declaremodule{standard}{cookielib} -\moduleauthor{John J. Lee}{jjl@pobox.com} -\sectionauthor{John J. Lee}{jjl@pobox.com} - -\versionadded{2.4} - -\modulesynopsis{Cookie handling for HTTP clients} - -The \module{cookielib} module defines classes for automatic handling -of HTTP cookies. It is useful for accessing web sites that require -small pieces of data -- \dfn{cookies} -- to be set on the client -machine by an HTTP response from a web server, and then returned to -the server in later HTTP requests. - -Both the regular Netscape cookie protocol and the protocol defined by -\rfc{2965} are handled. RFC 2965 handling is switched off by default. -\rfc{2109} cookies are parsed as Netscape cookies and subsequently -treated either as Netscape or RFC 2965 cookies according to the -'policy' in effect. Note that the great majority of cookies on the -Internet are Netscape cookies. \module{cookielib} attempts to follow -the de-facto Netscape cookie protocol (which differs substantially -from that set out in the original Netscape specification), including -taking note of the \code{max-age} and \code{port} cookie-attributes -introduced with RFC 2965. \note{The various named parameters found in -\mailheader{Set-Cookie} and \mailheader{Set-Cookie2} headers -(eg. \code{domain} and \code{expires}) are conventionally referred to -as \dfn{attributes}. To distinguish them from Python attributes, the -documentation for this module uses the term \dfn{cookie-attribute} -instead}. - - -The module defines the following exception: - -\begin{excdesc}{LoadError} -Instances of \class{FileCookieJar} raise this exception on failure to -load cookies from a file. \note{For backwards-compatibility -with Python 2.4 (which raised an \exception{IOError}), -\exception{LoadError} is a subclass of \exception{IOError}}. -\end{excdesc} - - -The following classes are provided: - -\begin{classdesc}{CookieJar}{policy=\constant{None}} -\var{policy} is an object implementing the \class{CookiePolicy} -interface. - -The \class{CookieJar} class stores HTTP cookies. It extracts cookies -from HTTP requests, and returns them in HTTP responses. -\class{CookieJar} instances automatically expire contained cookies -when necessary. Subclasses are also responsible for storing and -retrieving cookies from a file or database. -\end{classdesc} - -\begin{classdesc}{FileCookieJar}{filename, delayload=\constant{None}, - policy=\constant{None}} -\var{policy} is an object implementing the \class{CookiePolicy} -interface. For the other arguments, see the documentation for the -corresponding attributes. - -A \class{CookieJar} which can load cookies from, and perhaps save -cookies to, a file on disk. Cookies are \strong{NOT} loaded from the -named file until either the \method{load()} or \method{revert()} -method is called. Subclasses of this class are documented in section -\ref{file-cookie-jar-classes}. -\end{classdesc} - -\begin{classdesc}{CookiePolicy}{} -This class is responsible for deciding whether each cookie should be -accepted from / returned to the server. -\end{classdesc} - -\begin{classdesc}{DefaultCookiePolicy}{ - blocked_domains=\constant{None}, - allowed_domains=\constant{None}, - netscape=\constant{True}, rfc2965=\constant{False}, - rfc2109_as_netscape=\constant{None}, - hide_cookie2=\constant{False}, - strict_domain=\constant{False}, - strict_rfc2965_unverifiable=\constant{True}, - strict_ns_unverifiable=\constant{False}, - strict_ns_domain=\constant{DefaultCookiePolicy.DomainLiberal}, - strict_ns_set_initial_dollar=\constant{False}, - strict_ns_set_path=\constant{False} - } - -Constructor arguments should be passed as keyword arguments only. -\var{blocked_domains} is a sequence of domain names that we never -accept cookies from, nor return cookies to. \var{allowed_domains} if -not \constant{None}, this is a sequence of the only domains for which -we accept and return cookies. For all other arguments, see the -documentation for \class{CookiePolicy} and \class{DefaultCookiePolicy} -objects. - -\class{DefaultCookiePolicy} implements the standard accept / reject -rules for Netscape and RFC 2965 cookies. By default, RFC 2109 cookies -(ie. cookies received in a \mailheader{Set-Cookie} header with a -version cookie-attribute of 1) are treated according to the RFC 2965 -rules. However, if RFC 2965 handling is turned off or -\member{rfc2109_as_netscape} is True, RFC 2109 cookies are -'downgraded' by the \class{CookieJar} instance to Netscape cookies, by -setting the \member{version} attribute of the \class{Cookie} instance -to 0. \class{DefaultCookiePolicy} also provides some parameters to -allow some fine-tuning of policy. -\end{classdesc} - -\begin{classdesc}{Cookie}{} -This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is -not expected that users of \module{cookielib} construct their own -\class{Cookie} instances. Instead, if necessary, call -\method{make_cookies()} on a \class{CookieJar} instance. -\end{classdesc} - -\begin{seealso} - -\seemodule{urllib2}{URL opening with automatic cookie handling.} - -\seemodule{Cookie}{HTTP cookie classes, principally useful for -server-side code. The \module{cookielib} and \module{Cookie} modules -do not depend on each other.} - -\seeurl{http://wwwsearch.sf.net/ClientCookie/}{Extensions to this -module, including a class for reading Microsoft Internet Explorer -cookies on Windows.} - -\seeurl{http://www.netscape.com/newsref/std/cookie_spec.html}{The -specification of the original Netscape cookie protocol. Though this -is still the dominant protocol, the 'Netscape cookie protocol' -implemented by all the major browsers (and \module{cookielib}) only -bears a passing resemblance to the one sketched out in -\code{cookie_spec.html}.} - -\seerfc{2109}{HTTP State Management Mechanism}{Obsoleted by RFC 2965. -Uses \mailheader{Set-Cookie} with version=1.} - -\seerfc{2965}{HTTP State Management Mechanism}{The Netscape protocol -with the bugs fixed. Uses \mailheader{Set-Cookie2} in place of -\mailheader{Set-Cookie}. Not widely used.} - -\seeurl{http://kristol.org/cookie/errata.html}{Unfinished errata to -RFC 2965.} - -\seerfc{2964}{Use of HTTP State Management}{} - -\end{seealso} - - -\subsection{CookieJar and FileCookieJar Objects \label{cookie-jar-objects}} - -\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 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()}, -\method{get_type()}, \method{unverifiable()}, -\method{get_origin_req_host()}, \method{has_header()}, -\method{get_header()}, \method{header_items()}, and -\method{add_unredirected_header()},as documented by \module{urllib2}. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{extract_cookies}{response, request} -Extract cookies from HTTP \var{response} and store them in the -\class{CookieJar}, where allowed by policy. - -The \class{CookieJar} will look for allowable \mailheader{Set-Cookie} -and \mailheader{Set-Cookie2} headers in the \var{response} argument, -and store cookies as appropriate (subject to the -\method{CookiePolicy.set_ok()} method's approval). - -The \var{response} object (usually the result of a call to -\method{urllib2.urlopen()}, or similar) should support an -\method{info()} method, which returns an object with a -\method{getallmatchingheaders()} method (usually a -\class{mimetools.Message} instance). - -The \var{request} object (usually a \class{urllib2.Request} instance) -must support the methods \method{get_full_url()}, \method{get_host()}, -\method{unverifiable()}, and \method{get_origin_req_host()}, as -documented by \module{urllib2}. The request is used to set default -values for cookie-attributes as well as for checking that the cookie -is allowed to be set. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{set_policy}{policy} -Set the \class{CookiePolicy} instance to be used. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{make_cookies}{response, request} -Return sequence of \class{Cookie} objects extracted from -\var{response} object. - -See the documentation for \method{extract_cookies} for the interfaces -required of the \var{response} and \var{request} arguments. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{set_cookie_if_ok}{cookie, request} -Set a \class{Cookie} if policy says it's OK to do so. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{set_cookie}{cookie} -Set a \class{Cookie}, without checking with policy to see whether or -not it should be set. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{clear}{\optional{domain\optional{, - path\optional{, name}}}} -Clear some cookies. - -If invoked without arguments, clear all cookies. If given a single -argument, only cookies belonging to that \var{domain} will be removed. -If given two arguments, cookies belonging to the specified -\var{domain} and URL \var{path} are removed. If given three -arguments, then the cookie with the specified \var{domain}, \var{path} -and \var{name} is removed. - -Raises \exception{KeyError} if no matching cookie exists. -\end{methoddesc} - -\begin{methoddesc}[CookieJar]{clear_session_cookies}{} -Discard all session cookies. - -Discards all contained cookies that have a true \member{discard} -attribute (usually because they had either no \code{max-age} or -\code{expires} cookie-attribute, or an explicit \code{discard} -cookie-attribute). For interactive browsers, the end of a session -usually corresponds to closing the browser window. - -Note that the \method{save()} method won't save session cookies -anyway, unless you ask otherwise by passing a true -\var{ignore_discard} argument. -\end{methoddesc} - -\class{FileCookieJar} implements the following additional methods: - -\begin{methoddesc}[FileCookieJar]{save}{filename=\constant{None}, - ignore_discard=\constant{False}, ignore_expires=\constant{False}} -Save cookies to a file. - -This base class raises \exception{NotImplementedError}. Subclasses may -leave this method unimplemented. - -\var{filename} is the name of file in which to save cookies. If -\var{filename} is not specified, \member{self.filename} is used (whose -default is the value passed to the constructor, if any); if -\member{self.filename} is \constant{None}, \exception{ValueError} is -raised. - -\var{ignore_discard}: save even cookies set to be discarded. -\var{ignore_expires}: save even cookies that have expired - -The file is overwritten if it already exists, thus wiping all the -cookies it contains. Saved cookies can be restored later using the -\method{load()} or \method{revert()} methods. -\end{methoddesc} - -\begin{methoddesc}[FileCookieJar]{load}{filename=\constant{None}, - ignore_discard=\constant{False}, ignore_expires=\constant{False}} -Load cookies from a file. - -Old cookies are kept unless overwritten by newly loaded ones. - -Arguments are as for \method{save()}. - -The named file must be in the format understood by the class, or -\exception{LoadError} will be raised. Also, \exception{IOError} may -be raised, for example if the file does not exist. \note{For -backwards-compatibility with Python 2.4 (which raised -an \exception{IOError}), \exception{LoadError} is a subclass -of \exception{IOError}.} -\end{methoddesc} - -\begin{methoddesc}[FileCookieJar]{revert}{filename=\constant{None}, - ignore_discard=\constant{False}, ignore_expires=\constant{False}} -Clear all cookies and reload cookies from a saved file. - -\method{revert()} can raise the same exceptions as \method{load()}. -If there is a failure, the object's state will not be altered. -\end{methoddesc} - -\class{FileCookieJar} instances have the following public attributes: - -\begin{memberdesc}[FileCookieJar]{filename} -Filename of default file in which to keep cookies. This attribute may -be assigned to. -\end{memberdesc} - -\begin{memberdesc}[FileCookieJar]{delayload} -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} - - -\subsection{FileCookieJar subclasses and co-operation with web browsers - \label{file-cookie-jar-classes}} - -The following \class{CookieJar} subclasses are provided for reading -and writing . Further \class{CookieJar} subclasses, including one -that reads Microsoft Internet Explorer cookies, are available at -\url{http://wwwsearch.sf.net/ClientCookie/}. - -\begin{classdesc}{MozillaCookieJar}{filename, delayload=\constant{None}, - 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 -2965 cookies, and also about newer or non-standard cookie-attributes -such as \code{port}.} - -\warning{Back up your cookies before saving if you have cookies whose -loss / corruption would be inconvenient (there are some subtleties -which may lead to slight changes in the file over a load / save -round-trip).} - -Also note that cookies saved while Mozilla is running will get -clobbered by Mozilla. -\end{classdesc} - -\begin{classdesc}{LWPCookieJar}{filename, delayload=\constant{None}, - policy=\constant{None}} -A \class{FileCookieJar} that can load from and save cookies to disk in -format compatible with the libwww-perl library's \code{Set-Cookie3} -file format. This is convenient if you want to store cookies in a -human-readable file. -\end{classdesc} - - -\subsection{CookiePolicy Objects \label{cookie-policy-objects}} - -Objects implementing the \class{CookiePolicy} interface have the -following methods: - -\begin{methoddesc}[CookiePolicy]{set_ok}{cookie, request} -Return boolean value indicating whether cookie should be accepted from server. - -\var{cookie} is a \class{cookielib.Cookie} instance. \var{request} is -an object implementing the interface defined by the documentation for -\method{CookieJar.extract_cookies()}. -\end{methoddesc} - -\begin{methoddesc}[CookiePolicy]{return_ok}{cookie, request} -Return boolean value indicating whether cookie should be returned to server. - -\var{cookie} is a \class{cookielib.Cookie} instance. \var{request} is -an object implementing the interface defined by the documentation for -\method{CookieJar.add_cookie_header()}. -\end{methoddesc} - -\begin{methoddesc}[CookiePolicy]{domain_return_ok}{domain, request} -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). 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, -\method{path_return_ok()} and \method{return_ok()} are never called -for that cookie domain. If \method{path_return_ok()} returns true, -\method{return_ok()} is called with the \class{Cookie} object itself -for a full check. Otherwise, \method{return_ok()} is never called for -that cookie path. - -Note that \method{domain_return_ok()} is called for every -\emph{cookie} domain, not just for the \emph{request} domain. For -example, the function might be called with both \code{".example.com"} -and \code{"www.example.com"} if the request domain is -\code{"www.example.com"}. The same goes for -\method{path_return_ok()}. - -The \var{request} argument is as documented for \method{return_ok()}. -\end{methoddesc} - -\begin{methoddesc}[CookiePolicy]{path_return_ok}{path, request} -Return false if cookies should not be returned, given cookie path. - -See the documentation for \method{domain_return_ok()}. -\end{methoddesc} - - -In addition to implementing the methods above, implementations of the -\class{CookiePolicy} interface must also supply the following -attributes, indicating which protocols should be used, and how. All -of these attributes may be assigned to. - -\begin{memberdesc}[CookiePolicy]{netscape} -Implement Netscape protocol. -\end{memberdesc} -\begin{memberdesc}[CookiePolicy]{rfc2965} -Implement RFC 2965 protocol. -\end{memberdesc} -\begin{memberdesc}[CookiePolicy]{hide_cookie2} -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 -(this is unlikely to be useful). - - -\subsection{DefaultCookiePolicy Objects \label{default-cookie-policy-objects}} - -Implements the standard rules for accepting and returning cookies. - -Both RFC 2965 and Netscape cookies are covered. RFC 2965 handling is -switched off by default. - -The easiest way to provide your own policy is to override this class -and call its methods in your overridden implementations before adding -your own additional checks: - -\begin{verbatim} -import cookielib -class MyCookiePolicy(cookielib.DefaultCookiePolicy): - def set_ok(self, cookie, request): - if not cookielib.DefaultCookiePolicy.set_ok(self, cookie, request): - return False - if i_dont_want_to_store_this_cookie(cookie): - return False - return True -\end{verbatim} - -In addition to the features required to implement the -\class{CookiePolicy} interface, this class allows you to block and -allow domains from setting and receiving cookies. There are also some -strictness switches that allow you to tighten up the rather loose -Netscape protocol rules a little bit (at the cost of blocking some -benign cookies). - -A domain blacklist and whitelist is provided (both off by default). -Only domains not in the blacklist and present in the whitelist (if the -whitelist is active) participate in cookie setting and returning. Use -the \var{blocked_domains} constructor argument, and -\method{blocked_domains()} and \method{set_blocked_domains()} methods -(and the corresponding argument and methods for -\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 -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 -\code{"www.coyote.example.com"} match \code{".example.com"} (but -\code{"example.com"} itself does not). IP addresses are an exception, -and must match exactly. For example, if blocked_domains contains -\code{"192.168.1.2"} and \code{".168.1.2"}, 192.168.1.2 is blocked, -but 193.168.1.2 is not. - -\class{DefaultCookiePolicy} implements the following additional -methods: - -\begin{methoddesc}[DefaultCookiePolicy]{blocked_domains}{} -Return the sequence of blocked domains (as a tuple). -\end{methoddesc} - -\begin{methoddesc}[DefaultCookiePolicy]{set_blocked_domains} - {blocked_domains} -Set the sequence of blocked domains. -\end{methoddesc} - -\begin{methoddesc}[DefaultCookiePolicy]{is_blocked}{domain} -Return whether \var{domain} is on the blacklist for setting or -receiving cookies. -\end{methoddesc} - -\begin{methoddesc}[DefaultCookiePolicy]{allowed_domains}{} -Return \constant{None}, or the sequence of allowed domains (as a tuple). -\end{methoddesc} - -\begin{methoddesc}[DefaultCookiePolicy]{set_allowed_domains} - {allowed_domains} -Set the sequence of allowed domains, or \constant{None}. -\end{methoddesc} - -\begin{methoddesc}[DefaultCookiePolicy]{is_not_allowed}{domain} -Return whether \var{domain} is not on the whitelist for setting or -receiving cookies. -\end{methoddesc} - -\class{DefaultCookiePolicy} instances have the following attributes, -which are all initialised from the constructor arguments of the same -name, and which may all be assigned to. - -\begin{memberdesc}[DefaultCookiePolicy]{rfc2109_as_netscape} -If true, request that the \class{CookieJar} instance downgrade RFC -2109 cookies (ie. cookies received in a \mailheader{Set-Cookie} header -with a version cookie-attribute of 1) to Netscape cookies by setting -the version attribute of the \class{Cookie} instance to 0. The -default value is \constant{None}, in which case RFC 2109 cookies are -downgraded if and only if RFC 2965 handling is turned off. Therefore, -RFC 2109 cookies are downgraded by default. -\versionadded{2.5} -\end{memberdesc} - -General strictness switches: - -\begin{memberdesc}[DefaultCookiePolicy]{strict_domain} -Don't allow sites to set two-component domains with country-code -top-level domains like \code{.co.uk}, \code{.gov.uk}, -\code{.co.nz}.etc. This is far from perfect and isn't guaranteed to -work! -\end{memberdesc} - -RFC 2965 protocol strictness switches: - -\begin{memberdesc}[DefaultCookiePolicy]{strict_rfc2965_unverifiable} -Follow RFC 2965 rules on unverifiable transactions (usually, an -unverifiable transaction is one resulting from a redirect or a request -for an image hosted on another site). If this is false, cookies are -\emph{never} blocked on the basis of verifiability -\end{memberdesc} - -Netscape protocol strictness switches: - -\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_unverifiable} -apply RFC 2965 rules on unverifiable transactions even to Netscape -cookies -\end{memberdesc} -\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_domain} -Flags indicating how strict to be with domain-matching rules for -Netscape cookies. See below for acceptable values. -\end{memberdesc} -\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_set_initial_dollar} -Ignore cookies in Set-Cookie: headers that have names starting with -\code{'\$'}. -\end{memberdesc} -\begin{memberdesc}[DefaultCookiePolicy]{strict_ns_set_path} -Don't allow setting cookies whose path doesn't path-match request URI. -\end{memberdesc} - -\member{strict_ns_domain} is a collection of flags. Its value is -constructed by or-ing together (for example, -\code{DomainStrictNoDots|DomainStrictNonDomain} means both flags are -set). - -\begin{memberdesc}[DefaultCookiePolicy]{DomainStrictNoDots} -When setting cookies, the 'host prefix' must not contain a dot -(eg. \code{www.foo.bar.com} can't set a cookie for \code{.bar.com}, -because \code{www.foo} contains a dot). -\end{memberdesc} -\begin{memberdesc}[DefaultCookiePolicy]{DomainStrictNonDomain} -Cookies that did not explicitly specify a \code{domain} -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}[DefaultCookiePolicy]{DomainRFC2965Match} -When setting cookies, require a full RFC 2965 domain-match. -\end{memberdesc} - -The following attributes are provided for convenience, and are the -most useful combinations of the above flags: - -\begin{memberdesc}[DefaultCookiePolicy]{DomainLiberal} -Equivalent to 0 (ie. all of the above Netscape domain strictness flags -switched off). -\end{memberdesc} -\begin{memberdesc}[DefaultCookiePolicy]{DomainStrict} -Equivalent to \code{DomainStrictNoDots|DomainStrictNonDomain}. -\end{memberdesc} - - -\subsection{Cookie Objects \label{cookie-objects}} - -\class{Cookie} instances have Python attributes roughly corresponding -to the standard cookie-attributes specified in the various cookie -standards. The correspondence is not one-to-one, because there are -complicated rules for assigning default values, because the -\code{max-age} and \code{expires} cookie-attributes contain equivalent -information, and because RFC 2109 cookies may be 'downgraded' by -\module{cookielib} from version 1 to version 0 (Netscape) cookies. - -Assignment to these attributes should not be necessary other than in -rare circumstances in a \class{CookiePolicy} method. The class does -not enforce internal consistency, so you should know what you're -doing if you do that. - -\begin{memberdesc}[Cookie]{version} -Integer or \constant{None}. Netscape cookies have \member{version} 0. -RFC 2965 and RFC 2109 cookies have a \code{version} cookie-attribute -of 1. However, note that \module{cookielib} may 'downgrade' RFC 2109 -cookies to Netscape cookies, in which case \member{version} is 0. -\end{memberdesc} -\begin{memberdesc}[Cookie]{name} -Cookie name (a string). -\end{memberdesc} -\begin{memberdesc}[Cookie]{value} -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. \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]{expires} -Integer expiry date in seconds since epoch, or \constant{None}. See -also the \method{is_expired()} method. -\end{memberdesc} -\begin{memberdesc}[Cookie]{discard} -True if this is a session cookie. -\end{memberdesc} -\begin{memberdesc}[Cookie]{comment} -String comment from the server explaining the function of this cookie, -or \constant{None}. -\end{memberdesc} -\begin{memberdesc}[Cookie]{comment_url} -URL linking to a comment from the server explaining the function of -this cookie, or \constant{None}. -\end{memberdesc} -\begin{memberdesc}[Cookie]{rfc2109} -True if this cookie was received as an RFC 2109 cookie (ie. the cookie -arrived in a \mailheader{Set-Cookie} header, and the value of the -Version cookie-attribute in that header was 1). This attribute is -provided because \module{cookielib} may 'downgrade' RFC 2109 cookies -to Netscape cookies, in which case \member{version} is 0. -\versionadded{2.5} -\end{memberdesc} - -\begin{memberdesc}[Cookie]{port_specified} -True if a port or set of ports was explicitly specified by the server -(in the \mailheader{Set-Cookie} / \mailheader{Set-Cookie2} header). -\end{memberdesc} -\begin{memberdesc}[Cookie]{domain_specified} -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 (\code{'.'}). -\end{memberdesc} - -Cookies may have additional non-standard cookie-attributes. These may -be accessed using the following methods: - -\begin{methoddesc}[Cookie]{has_nonstandard_attr}{name} -Return true if cookie has the named cookie-attribute. -\end{methoddesc} -\begin{methoddesc}[Cookie]{get_nonstandard_attr}{name, default=\constant{None}} -If cookie has the named cookie-attribute, return its value. -Otherwise, return \var{default}. -\end{methoddesc} -\begin{methoddesc}[Cookie]{set_nonstandard_attr}{name, value} -Set the value of the named cookie-attribute. -\end{methoddesc} - -The \class{Cookie} class also defines the following method: - -\begin{methoddesc}[Cookie]{is_expired}{\optional{now=\constant{None}}} -True if cookie has passed the time at which the server requested it -should expire. If \var{now} is given (in seconds since the epoch), -return whether the cookie has expired at the specified time. -\end{methoddesc} - - -\subsection{Examples \label{cookielib-examples}} - -The first example shows the most common usage of \module{cookielib}: - -\begin{verbatim} -import cookielib, urllib2 -cj = cookielib.CookieJar() -opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj)) -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{}/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")) -opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj)) -r = opener.open("http://example.com/") -\end{verbatim} - -The next example illustrates the use of \class{DefaultCookiePolicy}. -Turn on RFC 2965 cookies, be more strict about domains when setting -and returning Netscape cookies, and block some domains from setting -cookies or having them returned: - -\begin{verbatim} -import urllib2 -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/") -\end{verbatim} |