Doc/lib/libcookie.tex

   1 \section{\module{Cookie} ---
   2          HTTP state management}
   3
   4 \declaremodule{standard}{Cookie}
   5 \modulesynopsis{Support for HTTP state management (cookies).}
   6 \moduleauthor{Timothy O'Malley}{timo@alum.mit.edu}
   7 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   8
   9
  10 The \module{Cookie} module defines classes for abstracting the concept of
  11 cookies, an HTTP state management mechanism. It supports both simple
  12 string-only cookies, and provides an abstraction for having any serializable
  13 data-type as cookie value.
  14
  15 The module formerly strictly applied the parsing rules described in
  16 the \rfc{2109} and \rfc{2068} specifications.  It has since been discovered
  17 that MSIE 3.0x doesn't follow the character rules outlined in those
  18 specs.  As a result, the parsing rules used are a bit less strict.
  19
  20 \begin{excdesc}{CookieError}
  21 Exception failing because of \rfc{2109} invalidity: incorrect
  22 attributes, incorrect \mailheader{Set-Cookie} header, etc.
  23 \end{excdesc}
  24
  25 \begin{classdesc}{BaseCookie}{\optional{input}}
  26 This class is a dictionary-like object whose keys are strings and
  27 whose values are \class{Morsel} instances. Note that upon setting a key to
  28 a value, the value is first converted to a \class{Morsel} containing
  29 the key and the value.
  30
  31 If \var{input} is given, it is passed to the \method{load()} method.
  32 \end{classdesc}
  33
  34 \begin{classdesc}{SimpleCookie}{\optional{input}}
  35 This class derives from \class{BaseCookie} and overrides
  36 \method{value_decode()} and \method{value_encode()} to be the identity
  37 and \function{str()} respectively.
  38 \end{classdesc}
  39
  40 \begin{classdesc}{SerialCookie}{\optional{input}}
  41 This class derives from \class{BaseCookie} and overrides
  42 \method{value_decode()} and \method{value_encode()} to be the
  43 \function{pickle.loads()} and \function{pickle.dumps()}.
  44
  45 \deprecated{2.3}{Reading pickled values from untrusted
  46 cookie data is a huge security hole, as pickle strings can be crafted
  47 to cause arbitrary code to execute on your server.  It is supported
  48 for backwards compatibility only, and may eventually go away.}
  49 \end{classdesc}
  50
  51 \begin{classdesc}{SmartCookie}{\optional{input}}
  52 This class derives from \class{BaseCookie}. It overrides
  53 \method{value_decode()} to be \function{pickle.loads()} if it is a
  54 valid pickle, and otherwise the value itself. It overrides
  55 \method{value_encode()} to be \function{pickle.dumps()} unless it is a
  56 string, in which case it returns the value itself.
  57
  58 \deprecated{2.3}{The same security warning from \class{SerialCookie}
  59 applies here.}
  60 \end{classdesc}
  61
  62 A further security note is warranted.  For backwards compatibility,
  63 the \module{Cookie} module exports a class named \class{Cookie} which
  64 is just an alias for \class{SmartCookie}.  This is probably a mistake
  65 and will likely be removed in a future version.  You should not use
  66 the \class{Cookie} class in your applications, for the same reason why
  67 you should not use the \class{SerialCookie} class.
  68
  69
  70 \begin{seealso}
  71   \seemodule{cookielib}{HTTP cookie handling for web
  72     \emph{clients}.  The \module{cookielib} and \module{Cookie}
  73     modules do not depend on each other.}
  74
  75   \seerfc{2109}{HTTP State Management Mechanism}{This is the state
  76                 management specification implemented by this module.}
  77 \end{seealso}
  78
  79
  80 \subsection{Cookie Objects \label{cookie-objects}}
  81
  82 \begin{methoddesc}[BaseCookie]{value_decode}{val}
  83 Return a decoded value from a string representation. Return value can
  84 be any type. This method does nothing in \class{BaseCookie} --- it exists
  85 so it can be overridden.
  86 \end{methoddesc}
  87
  88 \begin{methoddesc}[BaseCookie]{value_encode}{val}
  89 Return an encoded value. \var{val} can be any type, but return value
  90 must be a string. This method does nothing in \class{BaseCookie} --- it exists
  91 so it can be overridden
  92
  93 In general, it should be the case that \method{value_encode()} and
  94 \method{value_decode()} are inverses on the range of \var{value_decode}.
  95 \end{methoddesc}
  96
  97 \begin{methoddesc}[BaseCookie]{output}{\optional{attrs\optional{, header\optional{, sep}}}}
  98 Return a string representation suitable to be sent as HTTP headers.
  99 \var{attrs} and \var{header} are sent to each \class{Morsel}'s
 100 \method{output()} method. \var{sep} is used to join the headers
 101 together, and is by default the combination \code{'\e r\e n'} (CRLF).
 102 \versionchanged[The default separator has been changed from \code{'\e n'}
 103 to match the cookie specification]{2.5}
 104 \end{methoddesc}
 105
 106 \begin{methoddesc}[BaseCookie]{js_output}{\optional{attrs}}
 107 Return an embeddable JavaScript snippet, which, if run on a browser which
 108 supports JavaScript, will act the same as if the HTTP headers was sent.
 109
 110 The meaning for \var{attrs} is the same as in \method{output()}.
 111 \end{methoddesc}
 112
 113 \begin{methoddesc}[BaseCookie]{load}{rawdata}
 114 If \var{rawdata} is a string, parse it as an \code{HTTP_COOKIE} and add
 115 the values found there as \class{Morsel}s. If it is a dictionary, it
 116 is equivalent to:
 117
 118 \begin{verbatim}
 119 for k, v in rawdata.items():
 120     cookie[k] = v
 121 \end{verbatim}
 122 \end{methoddesc}
 123
 124
 125 \subsection{Morsel Objects \label{morsel-objects}}
 126
 127 \begin{classdesc}{Morsel}{}
 128 Abstract a key/value pair, which has some \rfc{2109} attributes.
 129
 130 Morsels are dictionary-like objects, whose set of keys is constant ---
 131 the valid \rfc{2109} attributes, which are
 132
 133 \begin{itemize}
 134 \item \code{expires}
 135 \item \code{path}
 136 \item \code{comment}
 137 \item \code{domain}
 138 \item \code{max-age}
 139 \item \code{secure}
 140 \item \code{version}
 141 \end{itemize}
 142
 143 The keys are case-insensitive.
 144 \end{classdesc}
 145
 146 \begin{memberdesc}[Morsel]{value}
 147 The value of the cookie.
 148 \end{memberdesc}
 149
 150 \begin{memberdesc}[Morsel]{coded_value}
 151 The encoded value of the cookie --- this is what should be sent.
 152 \end{memberdesc}
 153
 154 \begin{memberdesc}[Morsel]{key}
 155 The name of the cookie.
 156 \end{memberdesc}
 157
 158 \begin{methoddesc}[Morsel]{set}{key, value, coded_value}
 159 Set the \var{key}, \var{value} and \var{coded_value} members.
 160 \end{methoddesc}
 161
 162 \begin{methoddesc}[Morsel]{isReservedKey}{K}
 163 Whether \var{K} is a member of the set of keys of a \class{Morsel}.
 164 \end{methoddesc}
 165
 166 \begin{methoddesc}[Morsel]{output}{\optional{attrs\optional{, header}}}
 167 Return a string representation of the Morsel, suitable
 168 to be sent as an HTTP header. By default, all the attributes are included,
 169 unless \var{attrs} is given, in which case it should be a list of attributes
 170 to use. \var{header} is by default \code{"Set-Cookie:"}.
 171 \end{methoddesc}
 172
 173 \begin{methoddesc}[Morsel]{js_output}{\optional{attrs}}
 174 Return an embeddable JavaScript snippet, which, if run on a browser which
 175 supports JavaScript, will act the same as if the HTTP header was sent.
 176
 177 The meaning for \var{attrs} is the same as in \method{output()}.
 178 \end{methoddesc}
 179
 180 \begin{methoddesc}[Morsel]{OutputString}{\optional{attrs}}
 181 Return a string representing the Morsel, without any surrounding HTTP
 182 or JavaScript.
 183
 184 The meaning for \var{attrs} is the same as in \method{output()}.
 185 \end{methoddesc}
 186
 187
 188 \subsection{Example \label{cookie-example}}
 189
 190 The following example demonstrates how to use the \module{Cookie} module.
 191
 192 \begin{verbatim}
 193 >>> import Cookie
 194 >>> C = Cookie.SimpleCookie()
 195 >>> C = Cookie.SerialCookie()
 196 >>> C = Cookie.SmartCookie()
 197 >>> C["fig"] = "newton"
 198 >>> C["sugar"] = "wafer"
 199 >>> print C # generate HTTP headers
 200 Set-Cookie: sugar=wafer
 201 Set-Cookie: fig=newton
 202 >>> print C.output() # same thing
 203 Set-Cookie: sugar=wafer
 204 Set-Cookie: fig=newton
 205 >>> C = Cookie.SmartCookie()
 206 >>> C["rocky"] = "road"
 207 >>> C["rocky"]["path"] = "/cookie"
 208 >>> print C.output(header="Cookie:")
 209 Cookie: rocky=road; Path=/cookie
 210 >>> print C.output(attrs=[], header="Cookie:")
 211 Cookie: rocky=road
 212 >>> C = Cookie.SmartCookie()
 213 >>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
 214 >>> print C
 215 Set-Cookie: vienna=finger
 216 Set-Cookie: chips=ahoy
 217 >>> C = Cookie.SmartCookie()
 218 >>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
 219 >>> print C
 220 Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
 221 >>> C = Cookie.SmartCookie()
 222 >>> C["oreo"] = "doublestuff"
 223 >>> C["oreo"]["path"] = "/"
 224 >>> print C
 225 Set-Cookie: oreo=doublestuff; Path=/
 226 >>> C = Cookie.SmartCookie()
 227 >>> C["twix"] = "none for you"
 228 >>> C["twix"].value
 229 'none for you'
 230 >>> C = Cookie.SimpleCookie()
 231 >>> C["number"] = 7 # equivalent to C["number"] = str(7)
 232 >>> C["string"] = "seven"
 233 >>> C["number"].value
 234 '7'
 235 >>> C["string"].value
 236 'seven'
 237 >>> print C
 238 Set-Cookie: number=7
 239 Set-Cookie: string=seven
 240 >>> C = Cookie.SerialCookie()
 241 >>> C["number"] = 7
 242 >>> C["string"] = "seven"
 243 >>> C["number"].value
 244 7
 245 >>> C["string"].value
 246 'seven'
 247 >>> print C
 248 Set-Cookie: number="I7\012."
 249 Set-Cookie: string="S'seven'\012p1\012."
 250 >>> C = Cookie.SmartCookie()
 251 >>> C["number"] = 7
 252 >>> C["string"] = "seven"
 253 >>> C["number"].value
 254 7
 255 >>> C["string"].value
 256 'seven'
 257 >>> print C
 258 Set-Cookie: number="I7\012."
 259 Set-Cookie: string=seven
 260 \end{verbatim}