[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / module-Cookie.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="module-xmlrpclib.html" />
<link rel="prev" href="module-cookielib.html" />
<link rel="parent" href="internet.html" />
<link rel="next" href="cookie-objects.html" />
<meta name='aesop' content='information' />
<title>11.21 Cookie -- HTTP state management</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="11.20.6 Examples"
  href="cookielib-examples.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="11. Internet Protocols and"
  href="internet.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="11.21.1 Cookie Objects"
  href="cookie-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="cookielib-examples.html">11.20.6 Examples</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="internet.html">11. Internet Protocols and</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="cookie-objects.html">11.21.1 Cookie Objects</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION00132100000000000000000">
11.21 <tt class="module">Cookie</tt> --
         HTTP state management</A>
</H1>

<P>
<A NAME="module-Cookie"></A>

<P>
The <tt class="module">Cookie</tt> module defines classes for abstracting the concept of 
cookies, an HTTP state management mechanism. It supports both simple
string-only cookies, and provides an abstraction for having any serializable
data-type as cookie value.

<P>
The module formerly strictly applied the parsing rules described in
the <a class="rfc" id='rfcref-90561' xml:id='rfcref-90561'
href="http://www.faqs.org/rfcs/rfc2109.html">RFC 2109</a> and <a class="rfc" id='rfcref-90563' xml:id='rfcref-90563'
href="http://www.faqs.org/rfcs/rfc2068.html">RFC 2068</a> specifications.  It has since been discovered
that MSIE 3.0x doesn't follow the character rules outlined in those
specs.  As a result, the parsing rules used are a bit less strict.

<P>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-3678' xml:id='l2h-3678' class="exception">CookieError</tt></b></dt>
<dd>
Exception failing because of <a class="rfc" id='rfcref-90565' xml:id='rfcref-90565'
href="http://www.faqs.org/rfcs/rfc2109.html">RFC 2109</a> invalidity: incorrect
attributes, incorrect <span class="mailheader">Set-Cookie:</span> header, etc.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-3679' xml:id='l2h-3679' class="class">BaseCookie</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>input</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This class is a dictionary-like object whose keys are strings and
whose values are <tt class="class">Morsel</tt> instances. Note that upon setting a key to
a value, the value is first converted to a <tt class="class">Morsel</tt> containing
the key and the value.

<P>
If <var>input</var> is given, it is passed to the <tt class="method">load()</tt> method.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-3680' xml:id='l2h-3680' class="class">SimpleCookie</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>input</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This class derives from <tt class="class">BaseCookie</tt> and overrides
<tt class="method">value_decode()</tt> and <tt class="method">value_encode()</tt> to be the identity
and <tt class="function">str()</tt> respectively.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-3681' xml:id='l2h-3681' class="class">SerialCookie</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>input</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This class derives from <tt class="class">BaseCookie</tt> and overrides
<tt class="method">value_decode()</tt> and <tt class="method">value_encode()</tt> to be the
<tt class="function">pickle.loads()</tt> and <tt class="function">pickle.dumps()</tt>.

<P>
<div class="versionnote"><b>Deprecated since release 2.3.</b>
Reading pickled values from untrusted
cookie data is a huge security hole, as pickle strings can be crafted
to cause arbitrary code to execute on your server.  It is supported
for backwards compatibility only, and may eventually go away.</div><p></p>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-3682' xml:id='l2h-3682' class="class">SmartCookie</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>input</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
This class derives from <tt class="class">BaseCookie</tt>. It overrides
<tt class="method">value_decode()</tt> to be <tt class="function">pickle.loads()</tt> if it is a
valid pickle, and otherwise the value itself. It overrides
<tt class="method">value_encode()</tt> to be <tt class="function">pickle.dumps()</tt> unless it is a
string, in which case it returns the value itself.

<P>
<div class="versionnote"><b>Deprecated since release 2.3.</b>
The same security warning from <tt class="class">SerialCookie</tt>
applies here.</div><p></p>
</dl>

<P>
A further security note is warranted.  For backwards compatibility,
the <tt class="module">Cookie</tt> module exports a class named <tt class="class">Cookie</tt> which
is just an alias for <tt class="class">SmartCookie</tt>.  This is probably a mistake
and will likely be removed in a future version.  You should not use
the <tt class="class">Cookie</tt> class in your applications, for the same reason why
you should not use the <tt class="class">SerialCookie</tt> class.

<P>
<div class="seealso">
  <p class="heading">See Also:</p>

  <dl compact="compact" class="seemodule">
    <dt>Module <b><tt class="module"><a href="module-cookielib.html">cookielib</a></tt>:</b>
    <dd>HTTP cookie handling for for web
    <em>clients</em>.  The <tt class="module">cookielib</tt> and <tt class="module">Cookie</tt>
    modules do not depend on each other.
  </dl>

<P>
<dl compact="compact" class="seerfc">
    <dt><a href="http://www.faqs.org/rfcs/rfc2109.html"
        title="HTTP State Management Mechanism"
        >RFC 2109, <em>HTTP State Management Mechanism</em></a>
    <dd>This is the state
                management specification implemented by this module.
  </dl>
</div>

<P>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="cookie-objects.html">11.21.1 Cookie Objects</a>
<LI><A href="morsel-objects.html">11.21.2 Morsel Objects</a>
<LI><A href="cookie-example.html">11.21.3 Example</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="11.20.6 Examples"
  href="cookielib-examples.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="11. Internet Protocols and"
  href="internet.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="11.21.1 Cookie Objects"
  href="cookie-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="cookielib-examples.html">11.20.6 Examples</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="internet.html">11. Internet Protocols and</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="cookie-objects.html">11.21.1 Cookie Objects</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
86530b38 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="module-xmlrpclib.html" />
	13	<link rel="prev" href="module-cookielib.html" />
	14	<link rel="parent" href="internet.html" />
	15	<link rel="next" href="cookie-objects.html" />
	16	<meta name='aesop' content='information' />
	17	<title>11.21 Cookie -- HTTP state management</title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="11.20.6 Examples"
	25	href="cookielib-examples.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="11. Internet Protocols and"
	28	href="internet.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="11.21.1 Cookie Objects"
	31	href="cookie-objects.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Library Reference</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="cookielib-examples.html">11.20.6 Examples</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="internet.html">11. Internet Protocols and</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="cookie-objects.html">11.21.1 Cookie Objects</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H1><A NAME="SECTION00132100000000000000000">
	56	11.21 <tt class="module">Cookie</tt> --
	57	HTTP state management</A>
	58	</H1>
	59
	60	<P>
	61	<A NAME="module-Cookie"></A>
	62
	63	<P>
	64	The <tt class="module">Cookie</tt> module defines classes for abstracting the concept of
65	cookies, an HTTP state management mechanism. It supports both simple
66	string-only cookies, and provides an abstraction for having any serializable
67	data-type as cookie value.
68
69	<P>
70	The module formerly strictly applied the parsing rules described in
71	the <a class="rfc" id='rfcref-90561' xml:id='rfcref-90561'
72	href="http://www.faqs.org/rfcs/rfc2109.html">RFC 2109</a> and <a class="rfc" id='rfcref-90563' xml:id='rfcref-90563'
73	href="http://www.faqs.org/rfcs/rfc2068.html">RFC 2068</a> specifications. It has since been discovered
74	that MSIE 3.0x doesn't follow the character rules outlined in those
75	specs. As a result, the parsing rules used are a bit less strict.
76
77	<P>
78	<dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-3678' xml:id='l2h-3678' class="exception">CookieError</tt></b></dt>
79	<dd>
80	Exception failing because of <a class="rfc" id='rfcref-90565' xml:id='rfcref-90565'
81	href="http://www.faqs.org/rfcs/rfc2109.html">RFC 2109</a> invalidity: incorrect
82	attributes, incorrect <span class="mailheader">Set-Cookie:</span> header, etc.
83	</dd></dl>
84
85	<P>
86	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
87	<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3679' xml:id='l2h-3679' class="class">BaseCookie</tt></b>(</nobr></td>
88	<td><var></var><big>[</big><var>input</var><big>]</big><var></var>)</td></tr></table></dt>
89	<dd>
90	This class is a dictionary-like object whose keys are strings and
91	whose values are <tt class="class">Morsel</tt> instances. Note that upon setting a key to
92	a value, the value is first converted to a <tt class="class">Morsel</tt> containing
93	the key and the value.
94
95	<P>
96	If <var>input</var> is given, it is passed to the <tt class="method">load()</tt> method.
97	</dl>
98
99	<P>
100	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
101	<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3680' xml:id='l2h-3680' class="class">SimpleCookie</tt></b>(</nobr></td>
102	<td><var></var><big>[</big><var>input</var><big>]</big><var></var>)</td></tr></table></dt>
103	<dd>
104	This class derives from <tt class="class">BaseCookie</tt> and overrides
105	<tt class="method">value_decode()</tt> and <tt class="method">value_encode()</tt> to be the identity
106	and <tt class="function">str()</tt> respectively.
107	</dl>
108
109	<P>
110	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
111	<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3681' xml:id='l2h-3681' class="class">SerialCookie</tt></b>(</nobr></td>
112	<td><var></var><big>[</big><var>input</var><big>]</big><var></var>)</td></tr></table></dt>
113	<dd>
114	This class derives from <tt class="class">BaseCookie</tt> and overrides
115	<tt class="method">value_decode()</tt> and <tt class="method">value_encode()</tt> to be the
116	<tt class="function">pickle.loads()</tt> and <tt class="function">pickle.dumps()</tt>.
117
118	<P>
119	<div class="versionnote"><b>Deprecated since release 2.3.</b>
120	Reading pickled values from untrusted
121	cookie data is a huge security hole, as pickle strings can be crafted
122	to cause arbitrary code to execute on your server. It is supported
123	for backwards compatibility only, and may eventually go away.</div><p></p>
124	</dl>
125
126	<P>
127	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
128	<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-3682' xml:id='l2h-3682' class="class">SmartCookie</tt></b>(</nobr></td>
129	<td><var></var><big>[</big><var>input</var><big>]</big><var></var>)</td></tr></table></dt>
130	<dd>
131	This class derives from <tt class="class">BaseCookie</tt>. It overrides
132	<tt class="method">value_decode()</tt> to be <tt class="function">pickle.loads()</tt> if it is a
133	valid pickle, and otherwise the value itself. It overrides
134	<tt class="method">value_encode()</tt> to be <tt class="function">pickle.dumps()</tt> unless it is a
135	string, in which case it returns the value itself.
136
137	<P>
138	<div class="versionnote"><b>Deprecated since release 2.3.</b>
139	The same security warning from <tt class="class">SerialCookie</tt>
140	applies here.</div><p></p>
141	</dl>
142
143	<P>
144	A further security note is warranted. For backwards compatibility,
145	the <tt class="module">Cookie</tt> module exports a class named <tt class="class">Cookie</tt> which
146	is just an alias for <tt class="class">SmartCookie</tt>. This is probably a mistake
147	and will likely be removed in a future version. You should not use
148	the <tt class="class">Cookie</tt> class in your applications, for the same reason why
149	you should not use the <tt class="class">SerialCookie</tt> class.
150
151	<P>
152	<div class="seealso">
153	<p class="heading">See Also:</p>
154
155	<dl compact="compact" class="seemodule">
156	<dt>Module <b><tt class="module"><a href="module-cookielib.html">cookielib</a></tt>:</b>
157	<dd>HTTP cookie handling for for web
158	<em>clients</em>. The <tt class="module">cookielib</tt> and <tt class="module">Cookie</tt>
159	modules do not depend on each other.
160	</dl>
161
162	<P>
163	<dl compact="compact" class="seerfc">
164	<dt><a href="http://www.faqs.org/rfcs/rfc2109.html"
165	title="HTTP State Management Mechanism"
166	>RFC 2109, <em>HTTP State Management Mechanism</em></a>
167	<dd>This is the state
168	management specification implemented by this module.
169	</dl>
170	</div>
171
172	<P>
173
174	<p><br /></p><hr class='online-navigation' />
175	<div class='online-navigation'>
176	<!--Table of Child-Links-->
177	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
178
179	<UL CLASS="ChildLinks">
180	<LI><A href="cookie-objects.html">11.21.1 Cookie Objects</a>
181	<LI><A href="morsel-objects.html">11.21.2 Morsel Objects</a>
182	<LI><A href="cookie-example.html">11.21.3 Example</a>
183	</ul>
184	<!--End of Table of Child-Links-->
185	</div>
186
187	<DIV CLASS="navigation">
188	<div class='online-navigation'>
189	<p></p><hr />
190	<table align="center" width="100%" cellpadding="0" cellspacing="2">
191	<tr>
192	<td class='online-navigation'><a rel="prev" title="11.20.6 Examples"
193	href="cookielib-examples.html"><img src='../icons/previous.png'
194	border='0' height='32' alt='Previous Page' width='32' /></A></td>
195	<td class='online-navigation'><a rel="parent" title="11. Internet Protocols and"
196	href="internet.html"><img src='../icons/up.png'
197	border='0' height='32' alt='Up One Level' width='32' /></A></td>
198	<td class='online-navigation'><a rel="next" title="11.21.1 Cookie Objects"
199	href="cookie-objects.html"><img src='../icons/next.png'
200	border='0' height='32' alt='Next Page' width='32' /></A></td>
201	<td align="center" width="100%">Python Library Reference</td>
202	<td class='online-navigation'><a rel="contents" title="Table of Contents"
203	href="contents.html"><img src='../icons/contents.png'
204	border='0' height='32' alt='Contents' width='32' /></A></td>
205	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
206	border='0' height='32' alt='Module Index' width='32' /></a></td>
207	<td class='online-navigation'><a rel="index" title="Index"
208	href="genindex.html"><img src='../icons/index.png'
209	border='0' height='32' alt='Index' width='32' /></A></td>
210	</tr></table>
211	<div class='online-navigation'>
212	<b class="navlabel">Previous:</b>
213	<a class="sectref" rel="prev" href="cookielib-examples.html">11.20.6 Examples</A>
214	<b class="navlabel">Up:</b>
215	<a class="sectref" rel="parent" href="internet.html">11. Internet Protocols and</A>
216	<b class="navlabel">Next:</b>
217	<a class="sectref" rel="next" href="cookie-objects.html">11.21.1 Cookie Objects</A>
218	</div>
219	</div>
220	<hr />
221	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
222	</DIV>
223	<!--End of Navigation Panel-->
224	<ADDRESS>
225	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
226	</ADDRESS>
227	</BODY>
228	</HTML>