Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 1 | \section{\module{Cookie} --- |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 2 | HTTP state management} |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 3 | |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{Cookie} |
| 5 | \modulesynopsis{Support for HTTP state management (cookies).} |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 6 | \moduleauthor{Timothy O'Malley}{timo@alum.mit.edu} |
| 7 | \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} |
| 8 | |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 9 | |
| 10 | The \module{Cookie} module defines classes for abstracting the concept of |
Eric S. Raymond | 8321026 | 2001-01-10 19:34:52 +0000 | [diff] [blame] | 11 | cookies, an HTTP state management mechanism. It supports both simple |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 12 | string-only cookies, and provides an abstraction for having any serializable |
| 13 | data-type as cookie value. |
| 14 | |
Raymond Hettinger | 999b57c | 2003-08-25 04:28:05 +0000 | [diff] [blame] | 15 | The module formerly strictly applied the parsing rules described in |
Andrew M. Kuchling | 120beb6 | 2000-08-20 23:33:50 +0000 | [diff] [blame] | 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. |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 19 | |
| 20 | \begin{excdesc}{CookieError} |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 21 | Exception failing because of \rfc{2109} invalidity: incorrect |
Fred Drake | f91b461 | 2002-12-31 15:23:09 +0000 | [diff] [blame] | 22 | attributes, incorrect \mailheader{Set-Cookie} header, etc. |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 23 | \end{excdesc} |
| 24 | |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 25 | \begin{classdesc}{BaseCookie}{\optional{input}} |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 26 | This class is a dictionary-like object whose keys are strings and |
Fred Drake | f14730a | 2002-12-31 15:10:49 +0000 | [diff] [blame] | 27 | whose values are \class{Morsel} instances. Note that upon setting a key to |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 28 | a value, the value is first converted to a \class{Morsel} containing |
| 29 | the key and the value. |
| 30 | |
Fred Drake | 58c9539 | 2001-06-29 16:21:47 +0000 | [diff] [blame] | 31 | If \var{input} is given, it is passed to the \method{load()} method. |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 32 | \end{classdesc} |
| 33 | |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 34 | \begin{classdesc}{SimpleCookie}{\optional{input}} |
Fred Drake | 58c9539 | 2001-06-29 16:21:47 +0000 | [diff] [blame] | 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. |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 38 | \end{classdesc} |
| 39 | |
| 40 | \begin{classdesc}{SerialCookie}{\optional{input}} |
Fred Drake | 58c9539 | 2001-06-29 16:21:47 +0000 | [diff] [blame] | 41 | This class derives from \class{BaseCookie} and overrides |
| 42 | \method{value_decode()} and \method{value_encode()} to be the |
Fred Drake | f14730a | 2002-12-31 15:10:49 +0000 | [diff] [blame] | 43 | \function{pickle.loads()} and \function{pickle.dumps()}. |
Andrew M. Kuchling | 120beb6 | 2000-08-20 23:33:50 +0000 | [diff] [blame] | 44 | |
Fred Drake | f14730a | 2002-12-31 15:10:49 +0000 | [diff] [blame] | 45 | \deprecated{2.3}{Reading pickled values from untrusted |
Barry Warsaw | 0c0565d | 2001-11-16 22:28:17 +0000 | [diff] [blame] | 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 |
Fred Drake | f14730a | 2002-12-31 15:10:49 +0000 | [diff] [blame] | 48 | for backwards compatibility only, and may eventually go away.} |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 49 | \end{classdesc} |
| 50 | |
| 51 | \begin{classdesc}{SmartCookie}{\optional{input}} |
Fred Drake | 58c9539 | 2001-06-29 16:21:47 +0000 | [diff] [blame] | 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. |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 57 | |
Fred Drake | f14730a | 2002-12-31 15:10:49 +0000 | [diff] [blame] | 58 | \deprecated{2.3}{The same security warning from \class{SerialCookie} |
| 59 | applies here.} |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 60 | \end{classdesc} |
| 61 | |
Barry Warsaw | 0c0565d | 2001-11-16 22:28:17 +0000 | [diff] [blame] | 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 | |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 69 | |
| 70 | \begin{seealso} |
Martin v. Löwis | 2a6ba90 | 2004-05-31 18:22:40 +0000 | [diff] [blame] | 71 | \seemodule{cookielib}{HTTP cookie handling for for web |
| 72 | \emph{clients}. The \module{cookielib} and \module{Cookie} |
| 73 | modules do not depend on each other.} |
| 74 | |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 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 | |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 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 | |
Fred Drake | 58c9539 | 2001-06-29 16:21:47 +0000 | [diff] [blame] | 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} |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 96 | |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 97 | \begin{methoddesc}[BaseCookie]{output}{\optional{attrs\optional{, header\optional{, sep}}}} |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 98 | Return a string representation suitable to be sent as HTTP headers. |
Fred Drake | 58c9539 | 2001-06-29 16:21:47 +0000 | [diff] [blame] | 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 a newline. |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 102 | \end{methoddesc} |
| 103 | |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 104 | \begin{methoddesc}[BaseCookie]{js_output}{\optional{attrs}} |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 105 | Return an embeddable JavaScript snippet, which, if run on a browser which |
| 106 | supports JavaScript, will act the same as if the HTTP headers was sent. |
| 107 | |
| 108 | The meaning for \var{attrs} is the same as in \method{output()}. |
| 109 | \end{methoddesc} |
| 110 | |
| 111 | \begin{methoddesc}[BaseCookie]{load}{rawdata} |
| 112 | If \var{rawdata} is a string, parse it as an \code{HTTP_COOKIE} and add |
| 113 | the values found there as \class{Morsel}s. If it is a dictionary, it |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 114 | is equivalent to: |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 115 | |
| 116 | \begin{verbatim} |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 117 | for k, v in rawdata.items(): |
| 118 | cookie[k] = v |
| 119 | \end{verbatim} |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 120 | \end{methoddesc} |
| 121 | |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 122 | |
| 123 | \subsection{Morsel Objects \label{morsel-objects}} |
| 124 | |
| 125 | \begin{classdesc}{Morsel}{} |
| 126 | Abstract a key/value pair, which has some \rfc{2109} attributes. |
| 127 | |
| 128 | Morsels are dictionary-like objects, whose set of keys is constant --- |
| 129 | the valid \rfc{2109} attributes, which are |
| 130 | |
| 131 | \begin{itemize} |
| 132 | \item \code{expires} |
| 133 | \item \code{path} |
| 134 | \item \code{comment} |
| 135 | \item \code{domain} |
| 136 | \item \code{max-age} |
| 137 | \item \code{secure} |
| 138 | \item \code{version} |
| 139 | \end{itemize} |
| 140 | |
| 141 | The keys are case-insensitive. |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 142 | \end{classdesc} |
| 143 | |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 144 | \begin{memberdesc}[Morsel]{value} |
| 145 | The value of the cookie. |
| 146 | \end{memberdesc} |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 147 | |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 148 | \begin{memberdesc}[Morsel]{coded_value} |
| 149 | The encoded value of the cookie --- this is what should be sent. |
| 150 | \end{memberdesc} |
Moshe Zadka | 1b07f2b | 2000-08-19 14:11:41 +0000 | [diff] [blame] | 151 | |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 152 | \begin{memberdesc}[Morsel]{key} |
| 153 | The name of the cookie. |
| 154 | \end{memberdesc} |
| 155 | |
| 156 | \begin{methoddesc}[Morsel]{set}{key, value, coded_value} |
| 157 | Set the \var{key}, \var{value} and \var{coded_value} members. |
| 158 | \end{methoddesc} |
| 159 | |
| 160 | \begin{methoddesc}[Morsel]{isReservedKey}{K} |
| 161 | Whether \var{K} is a member of the set of keys of a \class{Morsel}. |
| 162 | \end{methoddesc} |
| 163 | |
| 164 | \begin{methoddesc}[Morsel]{output}{\optional{attrs\optional{, header}}} |
| 165 | Return a string representation of the Morsel, suitable |
| 166 | to be sent as an HTTP header. By default, all the attributes are included, |
| 167 | unless \var{attrs} is given, in which case it should be a list of attributes |
| 168 | to use. \var{header} is by default \code{"Set-Cookie:"}. |
| 169 | \end{methoddesc} |
| 170 | |
| 171 | \begin{methoddesc}[Morsel]{js_output}{\optional{attrs}} |
| 172 | Return an embeddable JavaScript snippet, which, if run on a browser which |
| 173 | supports JavaScript, will act the same as if the HTTP header was sent. |
| 174 | |
| 175 | The meaning for \var{attrs} is the same as in \method{output()}. |
Fred Drake | 58c9539 | 2001-06-29 16:21:47 +0000 | [diff] [blame] | 176 | \end{methoddesc} |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 177 | |
| 178 | \begin{methoddesc}[Morsel]{OutputString}{\optional{attrs}} |
| 179 | Return a string representing the Morsel, without any surrounding HTTP |
| 180 | or JavaScript. |
| 181 | |
| 182 | The meaning for \var{attrs} is the same as in \method{output()}. |
| 183 | \end{methoddesc} |
| 184 | |
| 185 | |
| 186 | \subsection{Example \label{cookie-example}} |
| 187 | |
Ka-Ping Yee | 3a9582f | 2001-01-18 07:50:17 +0000 | [diff] [blame] | 188 | The following example demonstrates how to use the \module{Cookie} module. |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 189 | |
| 190 | \begin{verbatim} |
| 191 | >>> import Cookie |
| 192 | >>> C = Cookie.SimpleCookie() |
| 193 | >>> C = Cookie.SerialCookie() |
| 194 | >>> C = Cookie.SmartCookie() |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 195 | >>> C["fig"] = "newton" |
| 196 | >>> C["sugar"] = "wafer" |
Ka-Ping Yee | 3a9582f | 2001-01-18 07:50:17 +0000 | [diff] [blame] | 197 | >>> print C # generate HTTP headers |
| 198 | Set-Cookie: sugar=wafer; |
| 199 | Set-Cookie: fig=newton; |
| 200 | >>> print C.output() # same thing |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 201 | Set-Cookie: sugar=wafer; |
| 202 | Set-Cookie: fig=newton; |
| 203 | >>> C = Cookie.SmartCookie() |
| 204 | >>> C["rocky"] = "road" |
| 205 | >>> C["rocky"]["path"] = "/cookie" |
| 206 | >>> print C.output(header="Cookie:") |
| 207 | Cookie: rocky=road; Path=/cookie; |
| 208 | >>> print C.output(attrs=[], header="Cookie:") |
| 209 | Cookie: rocky=road; |
| 210 | >>> C = Cookie.SmartCookie() |
| 211 | >>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header) |
Ka-Ping Yee | 3a9582f | 2001-01-18 07:50:17 +0000 | [diff] [blame] | 212 | >>> print C |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 213 | Set-Cookie: vienna=finger; |
| 214 | Set-Cookie: chips=ahoy; |
| 215 | >>> C = Cookie.SmartCookie() |
Ka-Ping Yee | 3a9582f | 2001-01-18 07:50:17 +0000 | [diff] [blame] | 216 | >>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";') |
| 217 | >>> print C |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 218 | Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"; |
| 219 | >>> C = Cookie.SmartCookie() |
| 220 | >>> C["oreo"] = "doublestuff" |
| 221 | >>> C["oreo"]["path"] = "/" |
Ka-Ping Yee | 3a9582f | 2001-01-18 07:50:17 +0000 | [diff] [blame] | 222 | >>> print C |
| 223 | Set-Cookie: oreo=doublestuff; Path=/; |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 224 | >>> C = Cookie.SmartCookie() |
| 225 | >>> C["twix"] = "none for you" |
| 226 | >>> C["twix"].value |
| 227 | 'none for you' |
| 228 | >>> C = Cookie.SimpleCookie() |
| 229 | >>> C["number"] = 7 # equivalent to C["number"] = str(7) |
| 230 | >>> C["string"] = "seven" |
| 231 | >>> C["number"].value |
| 232 | '7' |
| 233 | >>> C["string"].value |
| 234 | 'seven' |
Ka-Ping Yee | 3a9582f | 2001-01-18 07:50:17 +0000 | [diff] [blame] | 235 | >>> print C |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 236 | Set-Cookie: number=7; |
| 237 | Set-Cookie: string=seven; |
| 238 | >>> C = Cookie.SerialCookie() |
| 239 | >>> C["number"] = 7 |
| 240 | >>> C["string"] = "seven" |
| 241 | >>> C["number"].value |
| 242 | 7 |
| 243 | >>> C["string"].value |
| 244 | 'seven' |
Ka-Ping Yee | 3a9582f | 2001-01-18 07:50:17 +0000 | [diff] [blame] | 245 | >>> print C |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 246 | Set-Cookie: number="I7\012."; |
| 247 | Set-Cookie: string="S'seven'\012p1\012."; |
| 248 | >>> C = Cookie.SmartCookie() |
| 249 | >>> C["number"] = 7 |
| 250 | >>> C["string"] = "seven" |
| 251 | >>> C["number"].value |
| 252 | 7 |
| 253 | >>> C["string"].value |
| 254 | 'seven' |
Ka-Ping Yee | 3a9582f | 2001-01-18 07:50:17 +0000 | [diff] [blame] | 255 | >>> print C |
Fred Drake | e5c7352 | 2000-08-19 16:54:57 +0000 | [diff] [blame] | 256 | Set-Cookie: number="I7\012."; |
| 257 | Set-Cookie: string=seven; |
| 258 | \end{verbatim} |