\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 simplestring-only cookies, and provides an abstraction for having any serializabledata-type as cookie value.The module formerly strictly applied the parsing rules described inthe \rfc{2109} and \rfc{2068} specifications. It has since been discoveredthat MSIE 3.0x doesn't follow the character rules outlined in thosespecs. As a result, the parsing rules used are a bit less strict.\begin{excdesc}{CookieError}Exception failing because of \rfc{2109} invalidity: incorrectattributes, incorrect \mailheader{Set-Cookie} header, etc.\end{excdesc}\begin{classdesc}{BaseCookie}{\optional{input}}This class is a dictionary-like object whose keys are strings andwhose values are \class{Morsel} instances. Note that upon setting a key toa value, the value is first converted to a \class{Morsel} containingthe 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 identityand \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 untrustedcookie data is a huge security hole, as pickle strings can be craftedto cause arbitrary code to execute on your server. It is supportedfor 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 avalid pickle, and otherwise the value itself. It overrides\method{value_encode()} to be \function{pickle.dumps()} unless it is astring, 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} whichis just an alias for \class{SmartCookie}. This is probably a mistakeand will likely be removed in a future version. You should not usethe \class{Cookie} class in your applications, for the same reason whyyou 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 canbe any type. This method does nothing in \class{BaseCookie} --- it existsso it can be overridden.\end{methoddesc}\begin{methoddesc}[BaseCookie]{value_encode}{val}Return an encoded value. \var{val} can be any type, but return valuemust be a string. This method does nothing in \class{BaseCookie} --- it existsso it can be overriddenIn 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 headerstogether, 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 whichsupports 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 addthe values found there as \class{Morsel}s. If it is a dictionary, itis 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, suitableto 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 attributesto 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 whichsupports 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 HTTPor 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 headersSet-Cookie: sugar=waferSet-Cookie: fig=newton>>> print C.output() # same thingSet-Cookie: sugar=waferSet-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 CSet-Cookie: vienna=fingerSet-Cookie: chips=ahoy>>> C = Cookie.SmartCookie()>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')>>> print CSet-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;">>> C = Cookie.SmartCookie()>>> C["oreo"] = "doublestuff">>> C["oreo"]["path"] = "/">>> print CSet-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 CSet-Cookie: number=7Set-Cookie: string=seven>>> C = Cookie.SerialCookie()>>> C["number"] = 7>>> C["string"] = "seven">>> C["number"].value7>>> C["string"].value'seven'>>> print CSet-Cookie: number="I7\012."Set-Cookie: string="S'seven'\012p1\012.">>> C = Cookie.SmartCookie()>>> C["number"] = 7>>> C["string"] = "seven">>> C["number"].value7>>> C["string"].value'seven'>>> print CSet-Cookie: number="I7\012."Set-Cookie: string=seven\end{verbatim}
\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}