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

Skip to content

Commit 1b07f2b

Browse files
author
Moshe Zadka
committed
Initial revision. Markup unchecked.
1 parent 52ea872 commit 1b07f2b

1 file changed

Lines changed: 232 additions & 0 deletions

File tree

‎Doc/lib/libcookie.tex‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
\section{\module{Cookie} ---
2+
RFC2109 HTTP State Management (AKA Cookies) Support}
3+
\declaremodule{standard}{Cookie}
4+
5+
\moduleauthor{Timothy O'Malley}{[email protected]}
6+
\sectionauthor{Moshe Zadka}{[email protected]}
7+
8+
\modulesynopsis{Support HTTP State Management (Cookies)}
9+
10+
The \module{Cookie} module defines classes for abstracting the concept of
11+
Cookies, an HTTP state management mechanism. It supports both simplistic
12+
string-only cookies, and provides an abstraction for having any serializable
13+
data-type as cookie value.
14+
15+
\subsection{Example \label{cookie-example}}
16+
17+
The following example demonstrates how to open a can of spam using the
18+
\module{spam} module.
19+
20+
\begin{verbatim}
21+
>>> import Cookie
22+
>>> C = Cookie.SimpleCookie()
23+
>>> C = Cookie.SerialCookie()
24+
>>> C = Cookie.SmartCookie()
25+
>>> C = Cookie.Cookie() # backwards compatible alias for SmartCookie
26+
>>> C = Cookie.SmartCookie()
27+
>>> C["fig"] = "newton"
28+
>>> C["sugar"] = "wafer"
29+
>>> C # generate HTTP headers
30+
Set-Cookie: sugar=wafer;
31+
Set-Cookie: fig=newton;
32+
>>> C = Cookie.SmartCookie()
33+
>>> C["rocky"] = "road"
34+
>>> C["rocky"]["path"] = "/cookie"
35+
>>> print C.output(header="Cookie:")
36+
Cookie: rocky=road; Path=/cookie;
37+
>>> print C.output(attrs=[], header="Cookie:")
38+
Cookie: rocky=road;
39+
>>> C = Cookie.SmartCookie()
40+
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
41+
>>> C
42+
Set-Cookie: vienna=finger;
43+
Set-Cookie: chips=ahoy;
44+
>>> C = Cookie.SmartCookie()
45+
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
46+
>>> C
47+
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;";
48+
>>> C = Cookie.SmartCookie()
49+
>>> C["oreo"] = "doublestuff"
50+
>>> C["oreo"]["path"] = "/"
51+
>>> C
52+
Set-Cookie: oreo="doublestuff"; Path=/;
53+
>>> C = Cookie.SmartCookie()
54+
>>> C["twix"] = "none for you"
55+
>>> C["twix"].value
56+
'none for you'
57+
>>> C = Cookie.SimpleCookie()
58+
>>> C["number"] = 7 # equivalent to C["number"] = str(7)
59+
>>> C["string"] = "seven"
60+
>>> C["number"].value
61+
'7'
62+
>>> C["string"].value
63+
'seven'
64+
>>> C
65+
Set-Cookie: number=7;
66+
Set-Cookie: string=seven;
67+
>>> C = Cookie.SerialCookie()
68+
>>> C["number"] = 7
69+
>>> C["string"] = "seven"
70+
>>> C["number"].value
71+
7
72+
>>> C["string"].value
73+
'seven'
74+
>>> C
75+
Set-Cookie: number="I7\012.";
76+
Set-Cookie: string="S'seven'\012p1\012.";
77+
>>> C = Cookie.SmartCookie()
78+
>>> C["number"] = 7
79+
>>> C["string"] = "seven"
80+
>>> C["number"].value
81+
7
82+
>>> C["string"].value
83+
'seven'
84+
>>> C
85+
Set-Cookie: number="I7\012.";
86+
Set-Cookie: string=seven;
87+
\end{verbatim}
88+
89+
\begin{excdesc}{CookieError}
90+
Exception failing because of RFC2109 invalidity: incorrect attributes,
91+
incorrect \code{Set-Cookie} header, etc.
92+
\end{excdesc}
93+
94+
%\subsection{Morsel Objects}
95+
%\label{morsel-objects}
96+
97+
\begin{classdesc}{Morsel}{}
98+
Abstract a key/value pair, which has some RFC2109 attributes.
99+
100+
Morsels are dictionary-like objects, whose set of keys is constant ---
101+
the valid RFC2109 attributes, which are
102+
103+
\begin{itemize}
104+
\item \code{expires}
105+
\item \code{path}
106+
\item \code{comment}
107+
\item \code{domain}
108+
\item \code{max-age}
109+
\item \code{secure}
110+
\item \code{version}
111+
\end{itemize}
112+
\end{itemize}
113+
114+
The keys are case-insensitive.
115+
\end{classdesc}
116+
117+
\begin{memberdesc}[Morsel]{value}
118+
The value of the cookie.
119+
\end{methoddesc}
120+
121+
\begin{memberdesc}[Morsel]{coded_value}
122+
The encoded value of the cookie --- this is what should be sent.
123+
\end{methoddesc}
124+
125+
126+
\begin{memberdesc}[Morsel]{key}
127+
The name of the cookie.
128+
\end{methoddesc}
129+
130+
\begin{methodesc}[Morsel]{set}{key, value, coded_value}
131+
Set the \var{key}, \var{value} and \var{coded_value} members.
132+
\end{methoddesc}
133+
134+
\begin{methoddesc}[Morsel]{isReservedKey}{K}
135+
Whether \var{K} is a member of the set of keys of a \class{Morsel}.
136+
\end{methoddesc}
137+
138+
\begin{methoddesc}[Morsel]{output}{\opt{attrs, \opt{header}}
139+
Return a string representation of the Morsel, suitable
140+
to be sent as an HTTP header. By default, all the attributes are included,
141+
unless \var{attrs} is given, in which case it should be a list of attributes
142+
to use. \var{header} is by default \code{"Set-Cookie:"}.
143+
\end{methoddesc}
144+
145+
\begin{methoddesc}[Morsel]{js_output}{\opt{attrs}}
146+
Return an embeddable JavaScript snippet, which, if run on a browser which
147+
supports JavaScript, will act the same as if the HTTP header was sent.
148+
149+
The meaning for \var{attrs} is the same as in \method{output()}.
150+
\end{methoddesc}.
151+
152+
\begin{methoddesc}[Morsel]{OutputString}{\opt{attrs}}
153+
Return a string representing the Morsel, without any surrounding HTTP
154+
or JavaScript.
155+
156+
The meaning for \var{attrs} is the same as in \method{output()}.
157+
\end{methoddesc}
158+
159+
# This used to be strict parsing based on the RFC2109 and RFC2068
160+
# specifications. I have since discovered that MSIE 3.0x doesn't
161+
# follow the character rules outlined in those specs. As a
162+
# result, the parsing rules here are less strict.
163+
164+
\begin{classdesc}{BaseCookie}{\opt{input}}
165+
This class is a dictionary-like object whose keys are strings and
166+
whose values are \class{Morsel}s. Note that upon setting a key to
167+
a value, the value is first converted to a \class{Morsel} containing
168+
the key and the value.
169+
170+
If \var{input} is given, it is passed to the \method{load} method.
171+
\end{classdesc}
172+
173+
\begin{methoddesc}[BaseCookie]{value_decode}{val}
174+
Return a decoded value from a string representation. Return value can
175+
be any type. This method does nothing in \class{BaseCookie} --- it exists
176+
so it can be overridden.
177+
\end{methoddesc}
178+
179+
\begin{methoddesc}[BaseCookie]{value_encode}{val}
180+
Return an encoded value. \var{val} can be any type, but return value
181+
must be a string. This method does nothing in \class{BaseCookie} --- it exists
182+
so it can be overridden
183+
184+
In general, it should be the case that \method{value_encode} and
185+
\method{value_decode} are inverses on the range of \var{value_decode}.
186+
\end{methoddesc}.
187+
188+
\begin{methoddesc}[BaseCookie]{output}{\opt{attrs\opt{, header\opt{, sep}}}}
189+
Return a string representation suitable to be sent as HTTP headers.
190+
\var{attrs} and \var{header} are sent to each \class{Morsel}'s \method{output}
191+
method. \var{sep} is used to join the headers together, and is by default
192+
a newline.
193+
\end{methoddesc}
194+
195+
\begin{methoddesc}[BaseCookie]{js_output}{\opt{attrs}}
196+
Return an embeddable JavaScript snippet, which, if run on a browser which
197+
supports JavaScript, will act the same as if the HTTP headers was sent.
198+
199+
The meaning for \var{attrs} is the same as in \method{output()}.
200+
\end{methoddesc}
201+
202+
\begin{methoddesc}[BaseCookie]{load}{rawdata}
203+
If \var{rawdata} is a string, parse it as an \code{HTTP_COOKIE} and add
204+
the values found there as \class{Morsel}s. If it is a dictionary, it
205+
is equivalent to calling
206+
207+
\begin{verbatim}
208+
map(BaseCookie.__setitem__, rawdata.keys(), rawdata.values())
209+
\end{varbatim}
210+
\end{methoddesc}
211+
212+
\begin{classdesc}{SimpleCookie}{\opt{input}}
213+
This class derives from \class{BaseCookie} and overrides \method{value_decode}
214+
and \method{value_encode} to be the identity and \function{str()} respectively.
215+
\end{classdesc}
216+
217+
\begin{classdesc}{SerialCookie}{\opt{input}}
218+
This class derives from \class{BaseCookie} and overrides \method{value_decode}
219+
and \method{value_encode} to be the \function{pickle.loads()} and
220+
\function{pickle.dumps}. Note that using this class is a security hole,
221+
as arbitrary client-code can be run on \function{pickle.loads()}.
222+
\end{classdesc}
223+
224+
\begin{classdesc}{SmartCookie}{\opt{input}}
225+
This class derives from \class{BaseCookie}. It overrides \method{value_decode}
226+
to be \function{pickle.loads()} if it is a valid pickle, and otherwise
227+
the value itself. It overrides \method{value_encode} to be
228+
\function{pickle.dumps()} unless it is a string, in which case it returns
229+
the value itself.
230+
231+
The same security warning from \class{SerialCookie} applies here.
232+
\end{classdesc}

0 commit comments

Comments
 (0)