add hg and python

1 files changed, 260 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libcookie.tex b/sys/src/cmd/python/Doc/lib/libcookie.tex
new file mode 100644
index 000000000..e5d2038e2
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libcookie.tex
@@ -0,0 +1,260 @@
+\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}