rest25/library/cookie.rst => rest262/library/cookie.rst
n1- 
2:mod:`Cookie` --- HTTP state management
3=======================================
4
5.. module:: Cookie
6   :synopsis: Support for HTTP state management (cookies).
7.. moduleauthor:: Timothy O'Malley <timo@alum.mit.edu>
8.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
9
n9+.. note::
10+   The :mod:`Cookie` module has been renamed to :mod:`http.cookies` in Python
11+   3.0.  The :term:`2to3` tool will automatically adapt imports when converting
12+   your sources to 3.0.
13+ 
10
11The :mod:`Cookie` module defines classes for abstracting the concept of
12cookies, an HTTP state management mechanism. It supports both simple string-only
13cookies, and provides an abstraction for having any serializable data-type as
14cookie value.
15
16The module formerly strictly applied the parsing rules described in the
17:rfc:`2109` and :rfc:`2068` specifications.  It has since been discovered that
18MSIE 3.0x doesn't follow the character rules outlined in those specs.  As a
19result, the parsing rules used are a bit less strict.
n24+ 
25+.. note::
26+ 
27+   On encountering an invalid cookie, :exc:`CookieError` is raised, so if your
28+   cookie data comes from a browser you should always prepare for invalid data
29+   and catch :exc:`CookieError` on parsing.
20
21
22.. exception:: CookieError
23
24   Exception failing because of :rfc:`2109` invalidity: incorrect attributes,
25   incorrect :mailheader:`Set-Cookie` header, etc.
26
27
133
134
135.. _morsel-objects:
136
137Morsel Objects
138--------------
139
140
n141-.. class:: Morsel()
n151+.. class:: Morsel
142
143   Abstract a key/value pair, which has some :rfc:`2109` attributes.
144
145   Morsels are dictionary-like objects, whose set of keys is constant --- the valid
146   :rfc:`2109` attributes, which are
147
n148-* ``expires``
n158+   * ``expires``
149- 
150-* ``path``
159+   * ``path``
151- 
152-* ``comment``
160+   * ``comment``
153- 
154-* ``domain``
161+   * ``domain``
155- 
156-* ``max-age``
162+   * ``max-age``
157- 
158-* ``secure``
163+   * ``secure``
159- 
160-* ``version``
164+   * ``version``
165+   * ``httponly``
166+ 
167+   The attribute :attr:`httponly` specifies that the cookie is only transfered
168+   in HTTP requests, and is not accessible through JavaScript. This is intended
169+   to mitigate some forms of cross-site scripting.
161
162   The keys are case-insensitive.
n172+ 
173+   .. versionadded:: 2.6
174+      The :attr:`httponly` attribute was added.
163
164
165.. attribute:: Morsel.value
166
167   The value of the cookie.
168
169
170.. attribute:: Morsel.coded_value
211   The meaning for *attrs* is the same as in :meth:`output`.
212
213
214.. _cookie-example:
215
216Example
217-------
218
n219-The following example demonstrates how to use the :mod:`Cookie` module. ::
n231+The following example demonstrates how to use the :mod:`Cookie` module.
232+ 
233+.. doctest::
234+   :options: +NORMALIZE_WHITESPACE
220
221   >>> import Cookie
222   >>> C = Cookie.SimpleCookie()
223   >>> C = Cookie.SerialCookie()
224   >>> C = Cookie.SmartCookie()
225   >>> C["fig"] = "newton"
226   >>> C["sugar"] = "wafer"
227   >>> print C # generate HTTP headers
n243+   Set-Cookie: fig=newton
228   Set-Cookie: sugar=wafer
n245+   >>> print C.output() # same thing
229   Set-Cookie: fig=newton
n230-   >>> print C.output() # same thing
231   Set-Cookie: sugar=wafer
n232-   Set-Cookie: fig=newton
233   >>> C = Cookie.SmartCookie()
234   >>> C["rocky"] = "road"
235   >>> C["rocky"]["path"] = "/cookie"
236   >>> print C.output(header="Cookie:")
237   Cookie: rocky=road; Path=/cookie
238   >>> print C.output(attrs=[], header="Cookie:")
239   Cookie: rocky=road
240   >>> C = Cookie.SmartCookie()
241   >>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
242   >>> print C
n258+   Set-Cookie: chips=ahoy
243   Set-Cookie: vienna=finger
t244-   Set-Cookie: chips=ahoy
245   >>> C = Cookie.SmartCookie()
246   >>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
247   >>> print C
248   Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
249   >>> C = Cookie.SmartCookie()
250   >>> C["oreo"] = "doublestuff"
251   >>> C["oreo"]["path"] = "/"
252   >>> print C
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op