traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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 2000-08-19 16:54:57 +00:00
parent 514a1028a2
commit e5c7352201
1 changed files with 180 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

349
Doc/lib/libcookie.tex
View File

@ -1,167 +1,30 @@
\section{\module{Cookie} --- \section{\module{Cookie} ---
RFC2109 HTTP State Management (AKA Cookies) Support} HTTP state management}
\declaremodule{standard}{Cookie}
\declaremodule{standard}{Cookie}
\modulesynopsis{Support for HTTP state management (cookies).}
\moduleauthor{Timothy O'Malley}{timo@alum.mit.edu} \moduleauthor{Timothy O'Malley}{timo@alum.mit.edu}
\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} \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 The \module{Cookie} module defines classes for abstracting the concept of
Cookies, an HTTP state management mechanism. It supports both simplistic Cookies, an HTTP state management mechanism. It supports both simplistic
string-only cookies, and provides an abstraction for having any serializable string-only cookies, and provides an abstraction for having any serializable
data-type as cookie value. data-type as cookie value.
\subsection{Example \label{cookie-example}}
The following example demonstrates how to open a can of spam using the
\module{spam} module.
\begin{verbatim}
>>> import Cookie
>>> C = Cookie.SimpleCookie()
>>> C = Cookie.SerialCookie()
>>> C = Cookie.SmartCookie()
>>> C = Cookie.Cookie() # backwards compatible alias for SmartCookie
>>> C = Cookie.SmartCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> C # generate HTTP headers
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)
>>> C
Set-Cookie: vienna=finger;
Set-Cookie: chips=ahoy;
>>> C = Cookie.SmartCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> C
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;";
>>> C = Cookie.SmartCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> 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'
>>> 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'
>>> 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'
>>> C
Set-Cookie: number="I7\012.";
Set-Cookie: string=seven;
\end{verbatim}
\begin{excdesc}{CookieError} \begin{excdesc}{CookieError}
Exception failing because of RFC2109 invalidity: incorrect attributes, Exception failing because of \rfc{2109} invalidity: incorrect
incorrect \code{Set-Cookie} header, etc. attributes, incorrect \code{Set-Cookie} header, etc.
\end{excdesc} \end{excdesc}
%\subsection{Morsel Objects}
%\label{morsel-objects}
\begin{classdesc}{Morsel}{} This used to be strict parsing based on the \rfc{2109} and \rfc{2068}
Abstract a key/value pair, which has some RFC2109 attributes. 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.
Morsels are dictionary-like objects, whose set of keys is constant --- \begin{classdesc}{BaseCookie}{\optional{input}}
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 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 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 a value, the value is first converted to a \class{Morsel} containing
@ -170,6 +33,37 @@ the key and the value.
If \var{input} is given, it is passed to the \method{load} method. If \var{input} is given, it is passed to the \method{load} method.
\end{classdesc} \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} \begin{methoddesc}[BaseCookie]{value_decode}{val}
Return a decoded value from a string representation. Return value can Return a decoded value from a string representation. Return value can
be any type. This method does nothing in \class{BaseCookie} --- it exists be any type. This method does nothing in \class{BaseCookie} --- it exists
@ -185,14 +79,14 @@ In general, it should be the case that \method{value_encode} and
\method{value_decode} are inverses on the range of \var{value_decode}. \method{value_decode} are inverses on the range of \var{value_decode}.
\end{methoddesc}. \end{methoddesc}.
\begin{methoddesc}[BaseCookie]{output}{\opt{attrs\opt{, header\opt{, sep}}}} \begin{methoddesc}[BaseCookie]{output}{\optional{attrs\optional{, header\optional{, sep}}}}
Return a string representation suitable to be sent as HTTP headers. 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} \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 method. \var{sep} is used to join the headers together, and is by default
a newline. a newline.
\end{methoddesc} \end{methoddesc}
\begin{methoddesc}[BaseCookie]{js_output}{\opt{attrs}} \begin{methoddesc}[BaseCookie]{js_output}{\optional{attrs}}
Return an embeddable JavaScript snippet, which, if run on a browser which 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. supports JavaScript, will act the same as if the HTTP headers was sent.
@ -202,31 +96,148 @@ The meaning for \var{attrs} is the same as in \method{output()}.
\begin{methoddesc}[BaseCookie]{load}{rawdata} \begin{methoddesc}[BaseCookie]{load}{rawdata}
If \var{rawdata} is a string, parse it as an \code{HTTP_COOKIE} and add 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 the values found there as \class{Morsel}s. If it is a dictionary, it
is equivalent to calling is equivalent to:
\begin{verbatim} \begin{verbatim}
map(BaseCookie.__setitem__, rawdata.keys(), rawdata.values()) for k, v in rawdata.items():
\end{varbatim} cookie[k] = v
\end{verbatim}
\end{methoddesc} \end{methoddesc}
\begin{classdesc}{SimpleCookie}{\opt{input}}
This class derives from \class{BaseCookie} and overrides \method{value_decode} \subsection{Morsel Objects \label{morsel-objects}}
and \method{value_encode} to be the identity and \function{str()} respectively.
\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} \end{classdesc}
\begin{classdesc}{SerialCookie}{\opt{input}} \begin{memberdesc}[Morsel]{value}
This class derives from \class{BaseCookie} and overrides \method{value_decode} The value of the cookie.
and \method{value_encode} to be the \function{pickle.loads()} and \end{memberdesc}
\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}} \begin{memberdesc}[Morsel]{coded_value}
This class derives from \class{BaseCookie}. It overrides \method{value_decode} The encoded value of the cookie --- this is what should be sent.
to be \function{pickle.loads()} if it is a valid pickle, and otherwise \end{memberdesc}
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. \begin{memberdesc}[Morsel]{key}
\end{classdesc} 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
\module{spam} module.
\begin{verbatim}
>>> import Cookie
>>> C = Cookie.SimpleCookie()
>>> C = Cookie.SerialCookie()
>>> C = Cookie.SmartCookie()
>>> C = Cookie.Cookie() # backwards compatible alias for SmartCookie
>>> C = Cookie.SmartCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> C # generate HTTP headers
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)
>>> C
Set-Cookie: vienna=finger;
Set-Cookie: chips=ahoy;
>>> C = Cookie.SmartCookie()
>>> C.load('keebler="E=everybody; L=\"Loves\"; fudge=\012;";')
>>> C
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;";
>>> C = Cookie.SmartCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> 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'
>>> 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'
>>> 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'
>>> C
Set-Cookie: number="I7\012.";
Set-Cookie: string=seven;
\end{verbatim}