Make it format.
Adjust markup for hyperlinking to the relevant RFCs. Give it a little organization. Minor nits.
This commit is contained in:
Fred Drake
parent
514a1028a2
commit
e5c7352201
|
|
@ -1,17 +1,173 @@
|
|||
\section{\module{Cookie} ---
|
||||
RFC2109 HTTP State Management (AKA Cookies) Support}
|
||||
\declaremodule{standard}{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}
|
||||
|
||||
\modulesynopsis{Support HTTP State Management (Cookies)}
|
||||
|
||||
The \module{Cookie} module defines classes for abstracting the concept of
|
||||
Cookies, an HTTP state management mechanism. It supports both simplistic
|
||||
string-only cookies, and provides an abstraction for having any serializable
|
||||
data-type as cookie value.
|
||||
|
||||
|
||||
\begin{excdesc}{CookieError}
|
||||
Exception failing because of \rfc{2109} invalidity: incorrect
|
||||
attributes, incorrect \code{Set-Cookie} header, etc.
|
||||
\end{excdesc}
|
||||
|
||||
|
||||
This used to be strict parsing based on the \rfc{2109} and \rfc{2068}
|
||||
specifications. I have since discovered that MSIE 3.0x doesn't
|
||||
follow the character rules outlined in those specs. As a
|
||||
result, the parsing rules here are less strict.
|
||||
|
||||
\begin{classdesc}{BaseCookie}{\optional{input}}
|
||||
This class is a dictionary-like object whose keys are strings and
|
||||
whose values are \class{Morsel}s. 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}. Note that using this class is a security hole,
|
||||
as arbitrary client-code can be run on \function{pickle.loads()}.
|
||||
\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.
|
||||
|
||||
The same security warning from \class{SerialCookie} applies here.
|
||||
\end{classdesc}
|
||||
|
||||
|
||||
\begin{seealso}
|
||||
\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
|
||||
a newline.
|
||||
\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 open a can of spam using the
|
||||
|
|
@ -42,7 +198,7 @@ The following example demonstrates how to open a can of spam using the
|
|||
Set-Cookie: vienna=finger;
|
||||
Set-Cookie: chips=ahoy;
|
||||
>>> C = Cookie.SmartCookie()
|
||||
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
|
||||
>>> C.load('keebler="E=everybody; L=\"Loves\"; fudge=\012;";')
|
||||
>>> C
|
||||
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;";
|
||||
>>> C = Cookie.SmartCookie()
|
||||
|
|
@ -85,148 +241,3 @@ The following example demonstrates how to open a can of spam using the
|
|||
Set-Cookie: number="I7\012.";
|
||||
Set-Cookie: string=seven;
|
||||
\end{verbatim}
|
||||
|
||||
\begin{excdesc}{CookieError}
|
||||
Exception failing because of RFC2109 invalidity: incorrect attributes,
|
||||
incorrect \code{Set-Cookie} header, etc.
|
||||
\end{excdesc}
|
||||
|
||||
%\subsection{Morsel Objects}
|
||||
%\label{morsel-objects}
|
||||
|
||||
\begin{classdesc}{Morsel}{}
|
||||
Abstract a key/value pair, which has some RFC2109 attributes.
|
||||
|
||||
Morsels are dictionary-like objects, whose set of keys is constant ---
|
||||
the valid RFC2109 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}
|
||||
\end{itemize}
|
||||
|
||||
The keys are case-insensitive.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{memberdesc}[Morsel]{value}
|
||||
The value of the cookie.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{memberdesc}[Morsel]{coded_value}
|
||||
The encoded value of the cookie --- this is what should be sent.
|
||||
\end{methoddesc}
|
||||
|
||||
|
||||
\begin{memberdesc}[Morsel]{key}
|
||||
The name of the cookie.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methodesc}[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}{\opt{attrs, \opt{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}{\opt{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}{\opt{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}
|
||||
|
||||
# This used to be strict parsing based on the RFC2109 and RFC2068
|
||||
# specifications. I have since discovered that MSIE 3.0x doesn't
|
||||
# follow the character rules outlined in those specs. As a
|
||||
# result, the parsing rules here are less strict.
|
||||
|
||||
\begin{classdesc}{BaseCookie}{\opt{input}}
|
||||
This class is a dictionary-like object whose keys are strings and
|
||||
whose values are \class{Morsel}s. 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{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}{\opt{attrs\opt{, header\opt{, 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
|
||||
a newline.
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{methoddesc}[BaseCookie]{js_output}{\opt{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 calling
|
||||
|
||||
\begin{verbatim}
|
||||
map(BaseCookie.__setitem__, rawdata.keys(), rawdata.values())
|
||||
\end{varbatim}
|
||||
\end{methoddesc}
|
||||
|
||||
\begin{classdesc}{SimpleCookie}{\opt{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}{\opt{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}. Note that using this class is a security hole,
|
||||
as arbitrary client-code can be run on \function{pickle.loads()}.
|
||||
\end{classdesc}
|
||||
|
||||
\begin{classdesc}{SmartCookie}{\opt{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.
|
||||
|
||||
The same security warning from \class{SerialCookie} applies here.
|
||||
\end{classdesc}
|
||||
|
|
|
|||
Loading…
Reference in New Issue