| \section{\module{Cookie} --- |
| HTTP state management} |
| |
| \declaremodule{standard}{Cookie} |
| \modulesynopsis{Support for HTTP state management (cookies).} |
| \moduleauthor{Timothy O'Malley}{timo@alum.mit.edu} |
| \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} |
| |
| |
| The \module{Cookie} module defines classes for abstracting the concept of |
| cookies, an HTTP state management mechanism. It supports both simple |
| string-only cookies, and provides an abstraction for having any serializable |
| data-type as cookie value. |
| |
| The module formerly strictly applied the parsing rules described in |
| the \rfc{2109} and \rfc{2068} specifications. It has since been discovered |
| that MSIE 3.0x doesn't follow the character rules outlined in those |
| specs. As a result, the parsing rules used are a bit less strict. |
| |
| \begin{excdesc}{CookieError} |
| Exception failing because of \rfc{2109} invalidity: incorrect |
| attributes, incorrect \mailheader{Set-Cookie} header, etc. |
| \end{excdesc} |
| |
| \begin{classdesc}{BaseCookie}{\optional{input}} |
| This class is a dictionary-like object whose keys are strings and |
| whose values are \class{Morsel} instances. Note that upon setting a key to |
| a value, the value is first converted to a \class{Morsel} containing |
| the key and the value. |
| |
| If \var{input} is given, it is passed to the \method{load()} method. |
| \end{classdesc} |
| |
| \begin{classdesc}{SimpleCookie}{\optional{input}} |
| This class derives from \class{BaseCookie} and overrides |
| \method{value_decode()} and \method{value_encode()} to be the identity |
| and \function{str()} respectively. |
| \end{classdesc} |
| |
| \begin{classdesc}{SerialCookie}{\optional{input}} |
| This class derives from \class{BaseCookie} and overrides |
| \method{value_decode()} and \method{value_encode()} to be the |
| \function{pickle.loads()} and \function{pickle.dumps()}. |
| |
| \deprecated{2.3}{Reading pickled values from untrusted |
| cookie data is a huge security hole, as pickle strings can be crafted |
| to cause arbitrary code to execute on your server. It is supported |
| for backwards compatibility only, and may eventually go away.} |
| \end{classdesc} |
| |
| \begin{classdesc}{SmartCookie}{\optional{input}} |
| This class derives from \class{BaseCookie}. It overrides |
| \method{value_decode()} to be \function{pickle.loads()} if it is a |
| valid pickle, and otherwise the value itself. It overrides |
| \method{value_encode()} to be \function{pickle.dumps()} unless it is a |
| string, in which case it returns the value itself. |
| |
| \deprecated{2.3}{The same security warning from \class{SerialCookie} |
| applies here.} |
| \end{classdesc} |
| |
| A further security note is warranted. For backwards compatibility, |
| the \module{Cookie} module exports a class named \class{Cookie} which |
| is just an alias for \class{SmartCookie}. This is probably a mistake |
| and will likely be removed in a future version. You should not use |
| the \class{Cookie} class in your applications, for the same reason why |
| you should not use the \class{SerialCookie} class. |
| |
| |
| \begin{seealso} |
| \seemodule{cookielib}{HTTP cookie handling for web |
| \emph{clients}. The \module{cookielib} and \module{Cookie} |
| modules do not depend on each other.} |
| |
| \seerfc{2109}{HTTP State Management Mechanism}{This is the state |
| management specification implemented by this module.} |
| \end{seealso} |
| |
| |
| \subsection{Cookie Objects \label{cookie-objects}} |
| |
| \begin{methoddesc}[BaseCookie]{value_decode}{val} |
| Return a decoded value from a string representation. Return value can |
| be any type. This method does nothing in \class{BaseCookie} --- it exists |
| so it can be overridden. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[BaseCookie]{value_encode}{val} |
| Return an encoded value. \var{val} can be any type, but return value |
| must be a string. This method does nothing in \class{BaseCookie} --- it exists |
| so it can be overridden |
| |
| In general, it should be the case that \method{value_encode()} and |
| \method{value_decode()} are inverses on the range of \var{value_decode}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[BaseCookie]{output}{\optional{attrs\optional{, header\optional{, sep}}}} |
| Return a string representation suitable to be sent as HTTP headers. |
| \var{attrs} and \var{header} are sent to each \class{Morsel}'s |
| \method{output()} method. \var{sep} is used to join the headers |
| together, and is by default the combination \code{'\e r\e n'} (CRLF). |
| \versionchanged[The default separator has been changed from \code{'\e n'} |
| to match the cookie specification]{2.5} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[BaseCookie]{js_output}{\optional{attrs}} |
| Return an embeddable JavaScript snippet, which, if run on a browser which |
| supports JavaScript, will act the same as if the HTTP headers was sent. |
| |
| The meaning for \var{attrs} is the same as in \method{output()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[BaseCookie]{load}{rawdata} |
| If \var{rawdata} is a string, parse it as an \code{HTTP_COOKIE} and add |
| the values found there as \class{Morsel}s. If it is a dictionary, it |
| is equivalent to: |
| |
| \begin{verbatim} |
| for k, v in rawdata.items(): |
| cookie[k] = v |
| \end{verbatim} |
| \end{methoddesc} |
| |
| |
| \subsection{Morsel Objects \label{morsel-objects}} |
| |
| \begin{classdesc}{Morsel}{} |
| Abstract a key/value pair, which has some \rfc{2109} attributes. |
| |
| Morsels are dictionary-like objects, whose set of keys is constant --- |
| the valid \rfc{2109} attributes, which are |
| |
| \begin{itemize} |
| \item \code{expires} |
| \item \code{path} |
| \item \code{comment} |
| \item \code{domain} |
| \item \code{max-age} |
| \item \code{secure} |
| \item \code{version} |
| \end{itemize} |
| |
| The keys are case-insensitive. |
| \end{classdesc} |
| |
| \begin{memberdesc}[Morsel]{value} |
| The value of the cookie. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[Morsel]{coded_value} |
| The encoded value of the cookie --- this is what should be sent. |
| \end{memberdesc} |
| |
| \begin{memberdesc}[Morsel]{key} |
| The name of the cookie. |
| \end{memberdesc} |
| |
| \begin{methoddesc}[Morsel]{set}{key, value, coded_value} |
| Set the \var{key}, \var{value} and \var{coded_value} members. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Morsel]{isReservedKey}{K} |
| Whether \var{K} is a member of the set of keys of a \class{Morsel}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Morsel]{output}{\optional{attrs\optional{, header}}} |
| Return a string representation of the Morsel, suitable |
| to be sent as an HTTP header. By default, all the attributes are included, |
| unless \var{attrs} is given, in which case it should be a list of attributes |
| to use. \var{header} is by default \code{"Set-Cookie:"}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Morsel]{js_output}{\optional{attrs}} |
| Return an embeddable JavaScript snippet, which, if run on a browser which |
| supports JavaScript, will act the same as if the HTTP header was sent. |
| |
| The meaning for \var{attrs} is the same as in \method{output()}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[Morsel]{OutputString}{\optional{attrs}} |
| Return a string representing the Morsel, without any surrounding HTTP |
| or JavaScript. |
| |
| The meaning for \var{attrs} is the same as in \method{output()}. |
| \end{methoddesc} |
| |
| |
| \subsection{Example \label{cookie-example}} |
| |
| The following example demonstrates how to use the \module{Cookie} module. |
| |
| \begin{verbatim} |
| >>> import Cookie |
| >>> C = Cookie.SimpleCookie() |
| >>> C = Cookie.SerialCookie() |
| >>> C = Cookie.SmartCookie() |
| >>> C["fig"] = "newton" |
| >>> C["sugar"] = "wafer" |
| >>> print C # generate HTTP headers |
| Set-Cookie: sugar=wafer |
| Set-Cookie: fig=newton |
| >>> print C.output() # same thing |
| Set-Cookie: sugar=wafer |
| Set-Cookie: fig=newton |
| >>> C = Cookie.SmartCookie() |
| >>> C["rocky"] = "road" |
| >>> C["rocky"]["path"] = "/cookie" |
| >>> print C.output(header="Cookie:") |
| Cookie: rocky=road; Path=/cookie |
| >>> print C.output(attrs=[], header="Cookie:") |
| Cookie: rocky=road |
| >>> C = Cookie.SmartCookie() |
| >>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header) |
| >>> print C |
| Set-Cookie: vienna=finger |
| Set-Cookie: chips=ahoy |
| >>> C = Cookie.SmartCookie() |
| >>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";') |
| >>> print C |
| Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;" |
| >>> C = Cookie.SmartCookie() |
| >>> C["oreo"] = "doublestuff" |
| >>> C["oreo"]["path"] = "/" |
| >>> print C |
| Set-Cookie: oreo=doublestuff; Path=/ |
| >>> C = Cookie.SmartCookie() |
| >>> C["twix"] = "none for you" |
| >>> C["twix"].value |
| 'none for you' |
| >>> C = Cookie.SimpleCookie() |
| >>> C["number"] = 7 # equivalent to C["number"] = str(7) |
| >>> C["string"] = "seven" |
| >>> C["number"].value |
| '7' |
| >>> C["string"].value |
| 'seven' |
| >>> print C |
| Set-Cookie: number=7 |
| Set-Cookie: string=seven |
| >>> C = Cookie.SerialCookie() |
| >>> C["number"] = 7 |
| >>> C["string"] = "seven" |
| >>> C["number"].value |
| 7 |
| >>> C["string"].value |
| 'seven' |
| >>> print C |
| Set-Cookie: number="I7\012." |
| Set-Cookie: string="S'seven'\012p1\012." |
| >>> C = Cookie.SmartCookie() |
| >>> C["number"] = 7 |
| >>> C["string"] = "seven" |
| >>> C["number"].value |
| 7 |
| >>> C["string"].value |
| 'seven' |
| >>> print C |
| Set-Cookie: number="I7\012." |
| Set-Cookie: string=seven |
| \end{verbatim} |