ref: 4bcd247b909898766d549c3990c230cbeb3d17a3
dir: /sys/src/cmd/python/Doc/lib/libcookie.tex/
\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}