Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3a2418a

Browse files
akuchlingakuchling
committed
[Patch #969900] Various corrections and updates to cookielib docs
1 parent ae40c2f commit 3a2418a

1 file changed

Lines changed: 41 additions & 35 deletions

File tree

‎Doc/lib/libcookielib.tex‎

Lines changed: 41 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -140,17 +140,18 @@ \section{\module{cookielib} ---
140140

141141
\subsection{CookieJar and FileCookieJar Objects \label{cookie-jar-objects}}
142142

143-
\class{CookieJar} objects support the iterator protocol.
143+
\class{CookieJar} objects support the iterator protocol for iterating
144+
over contained \class{Cookie} objects.
144145

145146
\class{CookieJar} has the following methods:
146147

147148
\begin{methoddesc}[CookieJar]{add_cookie_header}{request}
148149
Add correct \mailheader{Cookie} header to \var{request}.
149150

150-
If the CookiePolicy allows (ie. the \class{CookiePolicy} instance's
151-
\member{rfc2965} and \member{hide_cookie2} attributes are true and
152-
false respectively), the \mailheader{Cookie2} header is also added
153-
when appropriate.
151+
If policy allows (ie. the \member{rfc2965} and \member{hide_cookie2}
152+
attributes of the \class{CookieJar}'s \class{CookiePolicy} instance
153+
are true and false respectively), the \mailheader{Cookie2} header is
154+
also added when appropriate.
154155

155156
The \var{request} object (usually a \class{urllib2.Request} instance)
156157
must support the methods \method{get_full_url()}, \method{get_host()},
@@ -279,15 +280,17 @@ \subsection{CookieJar and FileCookieJar Objects \label{cookie-jar-objects}}
279280
\class{FileCookieJar} instances have the following public attributes:
280281

281282
\begin{memberdesc}{filename}
282-
Filename of default file in which to keep cookies.
283+
Filename of default file in which to keep cookies. This attribute may
284+
be assigned to.
283285
\end{memberdesc}
284286

285287
\begin{memberdesc}{delayload}
286-
If true, load cookies lazily from disk. This is only a hint, since
287-
this only affects performance, not behaviour (unless the cookies on
288-
disk are changing). A \class{CookieJar} object may ignore it. None
289-
of the \class{FileCookieJar} classes included in the standard library
290-
lazily loads cookies.
288+
If true, load cookies lazily from disk. This attribute should not be
289+
assigned to. This is only a hint, since this only affects
290+
performance, not behaviour (unless the cookies on disk are changing).
291+
A \class{CookieJar} object may ignore it. None of the
292+
\class{FileCookieJar} classes included in the standard library lazily
293+
loads cookies.
291294
\end{memberdesc}
292295

293296

@@ -303,7 +306,7 @@ \subsection{FileCookieJar subclasses and co-operation with web browsers
303306
policy=\constant{None}}
304307
A \class{FileCookieJar} that can load from and save cookies to disk in
305308
the Mozilla \code{cookies.txt} file format (which is also used by the
306-
lynx and Netscape browsers). \note{This loses information about RFC
309+
Lynx and Netscape browsers). \note{This loses information about RFC
307310
2965 cookies, and also about newer or non-standard cookie-attributes
308311
such as \code{port}.}
309312

@@ -351,9 +354,8 @@ \subsection{CookiePolicy Objects \label{cookie-policy-objects}}
351354

352355
This method is an optimization. It removes the need for checking
353356
every cookie with a particular domain (which might involve reading
354-
many files). The default implementations of
355-
\method{domain_return_ok()} and \method{path_return_ok()}
356-
(\samp{return True}) leave all the work to \method{return_ok()}.
357+
many files). Returning true from \method{domain_return_ok()} and
358+
\method{path_return_ok()} leaves all the work to \method{return_ok()}.
357359

358360
If \method{domain_return_ok()} returns true for the cookie domain,
359361
\method{path_return_ok()} is called for the cookie path. Otherwise,
@@ -386,20 +388,22 @@ \subsection{CookiePolicy Objects \label{cookie-policy-objects}}
386388
of these attributes may be assigned to.
387389

388390
\begin{memberdesc}{netscape}
389-
Implement netscape protocol.
391+
Implement Netscape protocol.
390392
\end{memberdesc}
391393
\begin{memberdesc}{rfc2965}
392394
Implement RFC 2965 protocol.
393395
\end{memberdesc}
394396
\begin{memberdesc}{hide_cookie2}
395-
Don't add Cookie2 header to requests (the presence of this header
396-
indicates to the server that we understand RFC 2965 cookies).
397+
Don't add \mailheader{Cookie2} header to requests (the presence of
398+
this header indicates to the server that we understand RFC 2965
399+
cookies).
397400
\end{memberdesc}
398401

399402
The most useful way to define a \class{CookiePolicy} class is by
400403
subclassing from \class{DefaultCookiePolicy} and overriding some or
401404
all of the methods above. \class{CookiePolicy} itself may be used as
402-
a 'null policy' to allow setting and receiving any and all cookies.
405+
a 'null policy' to allow setting and receiving any and all cookies
406+
(this is unlikely to be useful).
403407

404408

405409
\subsection{DefaultCookiePolicy Objects \label{default-cookie-policy-objects}}
@@ -440,8 +444,9 @@ \subsection{DefaultCookiePolicy Objects \label{default-cookie-policy-objects}}
440444
\var{allowed_domains}). If you set a whitelist, you can turn it off
441445
again by setting it to \constant{None}.
442446

443-
Domains in block or allow lists that do not start with a dot must be
444-
equal. For example, \code{"example.com"} matches a blacklist entry of
447+
Domains in block or allow lists that do not start with a dot must
448+
equal the cookie domain to be matched. For example,
449+
\code{"example.com"} matches a blacklist entry of
445450
\code{"example.com"}, but \code{"www.example.com"} does not. Domains
446451
that do start with a dot are matched by more specific domains too.
447452
For example, both \code{"www.example.com"} and
@@ -534,10 +539,10 @@ \subsection{DefaultCookiePolicy Objects \label{default-cookie-policy-objects}}
534539
\end{memberdesc}
535540
\begin{memberdesc}{DomainStrictNonDomain}
536541
Cookies that did not explicitly specify a \code{domain}
537-
cookie-attribute can only be returned to a domain that string-compares
538-
equal to the domain that set the cookie (eg. \code{spam.example.com}
539-
won't be returned cookies from \code{example.com} that had no
540-
\code{domain} cookie-attribute).
542+
cookie-attribute can only be returned to a domain equal to the domain
543+
that set the cookie (eg. \code{spam.example.com} won't be returned
544+
cookies from \code{example.com} that had no \code{domain}
545+
cookie-attribute).
541546
\end{memberdesc}
542547
\begin{memberdesc}{DomainRFC2965Match}
543548
When setting cookies, require a full RFC 2965 domain-match.
@@ -574,17 +579,17 @@ \subsection{Cookie Objects \label{cookie-jar-objects}}
574579
2965 and RFC 2109 cookies have version 1.
575580
\end{memberdesc}
576581
\begin{memberdesc}[Cookie]{name}
577-
Cookie name (a string), or \constant{None}.
582+
Cookie name (a string).
578583
\end{memberdesc}
579584
\begin{memberdesc}[Cookie]{value}
580-
Cookie value (a string).
585+
Cookie value (a string), or \constant{None}.
581586
\end{memberdesc}
582587
\begin{memberdesc}[Cookie]{port}
583588
String representing a port or a set of ports (eg. '80', or '80,8080'),
584589
or \constant{None}.
585590
\end{memberdesc}
586591
\begin{memberdesc}[Cookie]{path}
587-
Cookie path (a string, eg. '/acme/rocket_launchers').
592+
Cookie path (a string, eg. \code{'/acme/rocket_launchers'}).
588593
\end{memberdesc}
589594
\begin{memberdesc}[Cookie]{secure}
590595
True if cookie should only be returned over a secure connection.
@@ -614,7 +619,7 @@ \subsection{Cookie Objects \label{cookie-jar-objects}}
614619
\end{memberdesc}
615620
\begin{memberdesc}[Cookie]{domain_initial_dot}
616621
True if the domain explicitly specified by the server began with a
617-
dot ('.').
622+
dot (\code{'.'}).
618623
\end{memberdesc}
619624

620625
Cookies may have additional non-standard cookie-attributes. These may
@@ -652,13 +657,13 @@ \subsection{Examples \label{cookielib-examples}}
652657
\end{verbatim}
653658

654659
This example illustrates how to open a URL using your Netscape,
655-
Mozilla, or lynx cookies (assumes \UNIX{} convention for location of
656-
the cookies file):
660+
Mozilla, or Lynx cookies (assumes \UNIX{}/Netscape convention for
661+
location of the cookies file):
657662

658663
\begin{verbatim}
659664
import os, cookielib, urllib2
660665
cj = cookielib.MozillaCookieJar()
661-
cj.load(os.path.join(os.environ["HOME"], "/.netscape/cookies.txt"))
666+
cj.load(os.path.join(os.environ["HOME"], ".netscape/cookies.txt"))
662667
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
663668
r = opener.open("http://example.com/")
664669
\end{verbatim}
@@ -670,9 +675,10 @@ \subsection{Examples \label{cookielib-examples}}
670675

671676
\begin{verbatim}
672677
import urllib2
673-
from cookielib import CookieJar, DefaultCookiePolicy as Policy
674-
policy = Policy(rfc2965=True, strict_ns_domain=Policy.DomainStrict,
675-
blocked_domains=["ads.net", ".ads.net"])
678+
from cookielib import CookieJar, DefaultCookiePolicy
679+
policy = DefaultCookiePolicy(
680+
rfc2965=True, strict_ns_domain=Policy.DomainStrict,
681+
blocked_domains=["ads.net", ".ads.net"])
676682
cj = CookieJar(policy)
677683
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
678684
r = opener.open("http://example.com/")

0 commit comments

Comments
 (0)