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 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 \code{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}s. 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 \strong{Do not use this class!}  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 \strong{Note:} 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   \seerfc{2109}{HTTP State Management Mechanism}{This is the state
  72                 management specification implemented by this module.}
  73 \end{seealso}
  74
  75
  76 \subsection{Cookie Objects \label{cookie-objects}}
  77
  78 \begin{methoddesc}[BaseCookie]{value_decode}{val}
  79 Return a decoded value from a string representation. Return value can
  80 be any type. This method does nothing in \class{BaseCookie} --- it exists
  81 so it can be overridden.
  82 \end{methoddesc}
  83
  84 \begin{methoddesc}[BaseCookie]{value_encode}{val}
  85 Return an encoded value. \var{val} can be any type, but return value
  86 must be a string. This method does nothing in \class{BaseCookie} --- it exists
  87 so it can be overridden
  88
  89 In general, it should be the case that \method{value_encode()} and
  90 \method{value_decode()} are inverses on the range of \var{value_decode}.
  91 \end{methoddesc}
  92
  93 \begin{methoddesc}[BaseCookie]{output}{\optional{attrs\optional{, header\optional{, sep}}}}
  94 Return a string representation suitable to be sent as HTTP headers.
  95 \var{attrs} and \var{header} are sent to each \class{Morsel}'s
  96 \method{output()} method. \var{sep} is used to join the headers
  97 together, and is by default a newline.
  98 \end{methoddesc}
  99
 100 \begin{methoddesc}[BaseCookie]{js_output}{\optional{attrs}}
 101 Return an embeddable JavaScript snippet, which, if run on a browser which
 102 supports JavaScript, will act the same as if the HTTP headers was sent.
 103
 104 The meaning for \var{attrs} is the same as in \method{output()}.
 105 \end{methoddesc}
 106
 107 \begin{methoddesc}[BaseCookie]{load}{rawdata}
 108 If \var{rawdata} is a string, parse it as an \code{HTTP_COOKIE} and add
 109 the values found there as \class{Morsel}s. If it is a dictionary, it
 110 is equivalent to:
 111
 112 \begin{verbatim}
 113 for k, v in rawdata.items():
 114     cookie[k] = v
 115 \end{verbatim}
 116 \end{methoddesc}
 117
 118
 119 \subsection{Morsel Objects \label{morsel-objects}}
 120
 121 \begin{classdesc}{Morsel}{}
 122 Abstract a key/value pair, which has some \rfc{2109} attributes.
 123
 124 Morsels are dictionary-like objects, whose set of keys is constant ---
 125 the valid \rfc{2109} attributes, which are
 126
 127 \begin{itemize}
 128 \item \code{expires}
 129 \item \code{path}
 130 \item \code{comment}
 131 \item \code{domain}
 132 \item \code{max-age}
 133 \item \code{secure}
 134 \item \code{version}
 135 \end{itemize}
 136
 137 The keys are case-insensitive.
 138 \end{classdesc}
 139
 140 \begin{memberdesc}[Morsel]{value}
 141 The value of the cookie.
 142 \end{memberdesc}
 143
 144 \begin{memberdesc}[Morsel]{coded_value}
 145 The encoded value of the cookie --- this is what should be sent.
 146 \end{memberdesc}
 147
 148 \begin{memberdesc}[Morsel]{key}
 149 The name of the cookie.
 150 \end{memberdesc}
 151
 152 \begin{methoddesc}[Morsel]{set}{key, value, coded_value}
 153 Set the \var{key}, \var{value} and \var{coded_value} members.
 154 \end{methoddesc}
 155
 156 \begin{methoddesc}[Morsel]{isReservedKey}{K}
 157 Whether \var{K} is a member of the set of keys of a \class{Morsel}.
 158 \end{methoddesc}
 159
 160 \begin{methoddesc}[Morsel]{output}{\optional{attrs\optional{, header}}}
 161 Return a string representation of the Morsel, suitable
 162 to be sent as an HTTP header. By default, all the attributes are included,
 163 unless \var{attrs} is given, in which case it should be a list of attributes
 164 to use. \var{header} is by default \code{"Set-Cookie:"}.
 165 \end{methoddesc}
 166
 167 \begin{methoddesc}[Morsel]{js_output}{\optional{attrs}}
 168 Return an embeddable JavaScript snippet, which, if run on a browser which
 169 supports JavaScript, will act the same as if the HTTP header was sent.
 170
 171 The meaning for \var{attrs} is the same as in \method{output()}.
 172 \end{methoddesc}
 173
 174 \begin{methoddesc}[Morsel]{OutputString}{\optional{attrs}}
 175 Return a string representing the Morsel, without any surrounding HTTP
 176 or JavaScript.
 177
 178 The meaning for \var{attrs} is the same as in \method{output()}.
 179 \end{methoddesc}
 180
 181
 182 \subsection{Example \label{cookie-example}}
 183
 184 The following example demonstrates how to use the \module{Cookie} module.
 185
 186 \begin{verbatim}
 187 >>> import Cookie
 188 >>> C = Cookie.SimpleCookie()
 189 >>> C = Cookie.SerialCookie()
 190 >>> C = Cookie.SmartCookie()
 191 >>> C["fig"] = "newton"
 192 >>> C["sugar"] = "wafer"
 193 >>> print C # generate HTTP headers
 194 Set-Cookie: sugar=wafer;
 195 Set-Cookie: fig=newton;
 196 >>> print C.output() # same thing
 197 Set-Cookie: sugar=wafer;
 198 Set-Cookie: fig=newton;
 199 >>> C = Cookie.SmartCookie()
 200 >>> C["rocky"] = "road"
 201 >>> C["rocky"]["path"] = "/cookie"
 202 >>> print C.output(header="Cookie:")
 203 Cookie: rocky=road; Path=/cookie;
 204 >>> print C.output(attrs=[], header="Cookie:")
 205 Cookie: rocky=road;
 206 >>> C = Cookie.SmartCookie()
 207 >>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
 208 >>> print C
 209 Set-Cookie: vienna=finger;
 210 Set-Cookie: chips=ahoy;
 211 >>> C = Cookie.SmartCookie()
 212 >>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
 213 >>> print C
 214 Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;";
 215 >>> C = Cookie.SmartCookie()
 216 >>> C["oreo"] = "doublestuff"
 217 >>> C["oreo"]["path"] = "/"
 218 >>> print C
 219 Set-Cookie: oreo=doublestuff; Path=/;
 220 >>> C = Cookie.SmartCookie()
 221 >>> C["twix"] = "none for you"
 222 >>> C["twix"].value
 223 'none for you'
 224 >>> C = Cookie.SimpleCookie()
 225 >>> C["number"] = 7 # equivalent to C["number"] = str(7)
 226 >>> C["string"] = "seven"
 227 >>> C["number"].value
 228 '7'
 229 >>> C["string"].value
 230 'seven'
 231 >>> print C
 232 Set-Cookie: number=7;
 233 Set-Cookie: string=seven;
 234 >>> C = Cookie.SerialCookie()
 235 >>> C["number"] = 7
 236 >>> C["string"] = "seven"
 237 >>> C["number"].value
 238 7
 239 >>> C["string"].value
 240 'seven'
 241 >>> print C
 242 Set-Cookie: number="I7\012.";
 243 Set-Cookie: string="S'seven'\012p1\012.";
 244 >>> C = Cookie.SmartCookie()
 245 >>> C["number"] = 7
 246 >>> C["string"] = "seven"
 247 >>> C["number"].value
 248 7
 249 >>> C["string"].value
 250 'seven'
 251 >>> print C
 252 Set-Cookie: number="I7\012.";
 253 Set-Cookie: string=seven;
 254 \end{verbatim}