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