Partial doc draft

git-svn-id: svn://svn.eby-sarna.com/svnroot/wsgiref@2172 571e12c6-e1fa-0310-aee7-ff1267fa46bd

2 files changed, 458 insertions, 0 deletions

diff --git a/docs/libwsgiref.tex b/docs/libwsgiref.tex
new file mode 100755
index 0000000..a09dfa1
--- /dev/null
+++ b/docs/libwsgiref.tex
@@ -0,0 +1,369 @@
+\section{\module{wsgiref} --- WSGI Utilities and Reference Implementation}
+\declaremodule{}{wsgiref}
+\moduleauthor{Phillip J. Eby}{pje@telecommunity.com}
+\sectionauthor{Phillip J. Eby}{pje@telecommunity.com}
+\modulesynopsis{WSGI Utilities and Reference Implementation}
+
+The Web Server Gateway Interface (WSGI) is a standard interface
+between web server software and web applications written in Python.
+Having a standard interface makes it easy to use a WSGI-supporting
+application with a number of different web servers.
+
+Only authors of web servers and programming frameworks need to know
+every detail and corner case of the WSGI design.  You don't need to
+understand every detail of WSGI just to install a WSGI application or
+to write a web application using an existing framework.
+
+\module{wsgiref} is a reference implementation of the WSGI specification
+that can be used to add WSGI support to a web server or framework.  It
+provides utilities for manipulating WSGI environment variables and
+response headers, base classes for implementing WSGI servers, a demo
+HTTP server that serves WSGI applications, and a validation tool that
+checks WSGI servers and applications for conformance to the
+WSGI specification (\pep{333}).
+
+% XXX If you're just trying to write a web application...
+% XXX should create a URL on python.org to point people to.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+\subsection{\module{wsgiref.util} -- WSGI environment utilities}
+\declaremodule{}{wsgiref.util}
+
+This module provides a variety of utility functions for working with
+WSGI environments.  A WSGI environment is a dictionary containing
+HTTP request variables as described in \pep{333}.  All of the functions
+taking an \var{environ} parameter expect a WSGI-compliant dictionary to
+be supplied; please see \pep{333} for a detailed specification.
+
+\begin{funcdesc}{guess_scheme}{environ}
+Return a guess for whether \code{wsgi.url_scheme} should be ``http'' or
+``https'', by checking for a \code{HTTPS} environment variable in the
+\var{environ} dictionary.  The return value is a string.
+
+This function is useful when creating a gateway that wraps CGI or a
+CGI-like protocol such as FastCGI.  Typically, servers providing such
+protocols will include a \code{HTTPS} variable with a value of ``1''
+``yes'', or ``on'' when a request is received via SSL.  So, this
+function returns ``https'' if such a value is found, and ``http''
+otherwise.
+\end{funcdesc}
+
+\begin{funcdesc}{request_uri}{environ \optional{, include_query=1}}
+Return the full request URI, optionally including the query string,
+using the algorithm found in the ``URL Reconstruction'' section of
+\pep{333}.  If \var{include_query} is false, the query string is
+not included in the resulting URI.
+\end{funcdesc}
+
+\begin{funcdesc}{application_uri}{environ}
+Similar to \function{request_uri}, except that the \code{PATH_INFO} and
+\code{QUERY_STRING} variables are ignored.  The result is the base URI
+of the application object addressed by the request.
+\end{funcdesc}
+
+\begin{funcdesc}{shift_path_info}{environ}
+Shift a single name from \code{PATH_INFO} to \code{SCRIPT_NAME} and
+return the name.  The \var{environ} dictionary is \emph{modified}
+in-place; use a copy if you need to keep the original \code{PATH_INFO}
+or \code{SCRIPT_NAME} intact.
+
+If there are no remaining path segments in \code{PATH_INFO}, \code{None}
+is returned.
+
+Typically, this routine is used to process each portion of a request
+URI path, for example to treat the path as a series of dictionary keys.
+This routine modifies the passed-in environment to make it suitable for
+invoking another WSGI application that is located at the target URI.
+For example, if there is a WSGI application at \code{/foo}, and the
+request URI path is \code{/foo/bar/baz}, and the WSGI application at
+\code{/foo} calls \function{shift_path_info}, it will receive the string
+``bar'', and the environment will be updated to be suitable for passing
+to a WSGI application at \code{/foo/bar}.  That is, \code{SCRIPT_NAME}
+will change from \code{/foo} to \code{/foo/bar}, and \code{PATH_INFO}
+will change from \code{/bar/baz} to \code{/baz}.
+
+When \code{PATH_INFO} is just a ``/'', this routine returns an empty
+string and appends a trailing slash to \code{SCRIPT_NAME}, even though
+empty path segments are normally ignored, and \code{SCRIPT_NAME} doesn't
+normally end in a slash.  This is intentional behavior, to ensure that
+an application can tell the difference between URIs ending in \code{/x}
+from ones ending in \code{/x/} when using this routine to do object
+traversal.
+
+\end{funcdesc}
+
+\begin{funcdesc}{setup_testing_defaults}{environ}
+Update \var{environ} with trivial defaults for testing purposes.
+
+This routine adds various parameters required for WSGI, including
+\code{HTTP_HOST}, \code{SERVER_NAME}, \code{SERVER_PORT},
+\code{REQUEST_METHOD}, \code{SCRIPT_NAME}, \code{PATH_INFO}, and all of
+the \pep{333}-defined \code{wsgi.*} variables.  It only supplies default
+values, and does not replace any existing settings for these variables.
+
+This routine is intended to make it easier for unit tests of WSGI
+servers and applications to set up dummy environments.  It should NOT
+be used by actual WSGI servers or applications, since the data is fake!
+\end{funcdesc}
+
+
+
+In addition to the environment functions above, the
+\module{wsgiref.util} module also provides these miscellaneous
+utilities:
+
+\begin{funcdesc}{is_hop_by_hop}{header_name}
+Return true if 'header_name' is an HTTP/1.1 ``Hop-by-Hop'' header, as
+defined by \rfc{2616}.
+\end{funcdesc}
+
+\begin{classdesc}{FileWrapper}{filelike \optional{, blksize=8192}}
+A wrapper to convert a file-like object to an iterator.  The resulting
+objects support both \method{__getitem__} and \method{__iter__}
+iteration styles, for compatibility with Python 2.1 and Jython.
+As the object is iterated over, the optional \var{blksize} parameter
+will be repeatedly passed to the \var{filelike} object's \method{read()}
+method to obtain strings to yield.  When \method{read()} returns an
+empty string, iteration is ended and is not resumable.
+
+If \var{filelike} has a \method{close()} method, the returned object
+will also have a \method{close()} method, and it will invoke the
+\var{filelike} object's \method{close()} method when called.
+\end{classdesc}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+\subsection{\module{wsgiref.headers} -- WSGI response header tools}
+\declaremodule{}{wsgiref.headers}
+
+This module provides a single class, \class{Headers}, for convenient
+manipulation of WSGI response headers using a mapping-like interface.
+
+\begin{classdesc}{Headers}{headers}
+Create a mapping-like object wrapping \var{headers}, which must be a
+list of header name/value tuples as described in \pep{333}.  Any changes
+made to the new \class{Headers} object will directly update the
+\var{headers} list it was created with.
+
+\class{Headers} objects support typical mapping operations including
+\method{__getitem__}, \method{get}, \method{__setitem__},
+\method{setdefault}, \method{__delitem__}, \method{__contains__} and
+\method{has_key}.  For each of these methods, the key is the header name
+(treated case-insensitively), and the value is the first value
+associated with that header name.  Setting a header deletes any existing
+values for that header, then adds a new value at the end of the wrapped
+header list.  Headers' existing order is generally maintained, with new
+headers added to the end of the wrapped list.
+
+Unlike a dictionary, \class{Headers} objects do not raise an error when
+you try to get or delete a key that isn't in the wrapped header list.
+Getting a nonexistent header just returns \code{None}, and deleting
+a nonexistent header does nothing.
+
+\class{Headers} objects also support \method{keys()}, \method{values()},
+and \method{items()} methods.  The lists returned by \method{keys()}
+and \method{items()} can include the same key more than once if there
+is a multi-valued header.  The \code{len()} of a \class{Headers} object
+is the same as the length of its \method{items()}, which is the same
+as the length of the wrapped header list.  In fact, the \method{items()}
+method just returns a copy of the wrapped header list.
+
+Calling \code{str()} on a \class{Headers} object returns a formatted
+string suitable for transmission as HTTP response headers.  Each header
+is placed on a line with its value, separated by a colon and a space.
+Each line is terminated by a carriage return and line feed, and the
+string is terminated with a blank line.
+
+In addition to their mapping interface and formatting features,
+\class{Headers} objects also have the following methods for querying
+and adding multi-valued headers, and for adding headers with MIME
+parameters:
+
+\begin{methoddesc}{get_all}{name}
+Return a list of all the values for the named header.
+
+The returned list will be sorted in the order they appeared in the
+original header list or were added to this instance, and may contain
+duplicates.  Any fields deleted and re-inserted are always appended to
+the header list.  If no fields exist with the given name, returns an
+empty list.
+\end{methoddesc}
+
+
+\begin{methoddesc}{add_header}{name, value, **_params}
+Add a (possibly multi-valued) header, with optional MIME parameters
+specified via keyword arguments.
+
+_name is the header field to add.  keyword arguments can be used to set
+additional parameters for the header field, with underscores converted
+to dashes.  Normally the parameter will be added as key="value" unless
+value is None, in which case only the key will be added.
+
+Example:
+
+h.add_header('content-disposition', 'attachment', filename='bud.gif')
+
+Note that unlike the corresponding 'email.Message' method, this does
+*not* handle '(charset, language, value)' tuples: all values must be
+strings or None.
+\end{methoddesc}
+
+\end{classdesc}
+
+
+
+
+
+
+\subsection{\module{wsgiref.simple_server} -- a simple WSGI HTTP server}
+\declaremodule[wsgiref.simpleserver]{}{wsgiref.simple_server}
+
+\begin{funcdesc}{demo_app}{environ, start_response}
+This function is a small but complete WSGI application that
+returns a text page containing the message ``Hello world!''
+and a list of the key/value pairs provided in the
+\var{environ} parameter.
+\end{funcdesc}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+\subsection{\module{wsgiref.validate} -- WSGI conformance checker}
+\declaremodule{}{wsgiref.validate}
+
+\begin{funcdesc}{middleware}{application}
+\end{funcdesc}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+\subsection{\module{wsgiref.handlers} -- server/gateway base classes}
+\declaremodule{}{wsgiref.handlers}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/ref.tex b/docs/ref.tex
new file mode 100755
index 0000000..e2b6a8c
--- /dev/null
+++ b/docs/ref.tex
@@ -0,0 +1,89 @@
+% Complete documentation on the extended LaTeX markup used for Python
+% documentation is available in ``Documenting Python'', which is part
+% of the standard documentation for Python.  It may be found online
+% at:
+%
+%     http://www.python.org/doc/current/doc/doc.html
+
+\documentclass{manual}
+
+\title{The WSGI Reference Library}
+
+\author{Phillip J. Eby}
+
+% Please at least include a long-lived email address;
+% the rest is at your discretion.
+\authoraddress{
+%	Organization name, if applicable \\
+%	Street address, if you want to use it \\
+	Email: \email{pje@telecommunity.com}
+}
+
+\date{June 5, 2006}       % update before release!
+
+\release{0.1}     % release version; this is used to define the
+                  % \version macro
+
+\makeindex          % tell \index to actually write the .idx file
+\makemodindex       % If this contains a lot of module sections.
+
+
+\begin{document}
+
+\maketitle
+
+% This makes the contents more accessible from the front page of the HTML.
+%\ifhtml
+%\chapter*{Front Matter\label{front}}
+%\fi
+
+%\input{copyright}
+
+\begin{abstract}
+\noindent
+\module{wsgiref} is a reference implementation of the WSGI specification
+that can be used to add WSGI support to a web server or framework.  It also
+contains some useful utilities for writing applications or middleware that
+provide or implement WSGI.
+\end{abstract}
+
+\tableofcontents
+
+\chapter{Reference}
+
+\input{libwsgiref.tex}
+
+%\appendix
+%\chapter{...}
+
+%My appendix.
+
+%The \code{\e appendix} markup need not be repeated for additional
+%appendices.
+
+
+
+
+
+
+
+
+%
+%  The ugly "%begin{latexonly}" pseudo-environments are really just to
+%  keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
+%  not really valuable.
+%
+%  If you don't want the Module Index, you can remove all of this up
+%  until the second \input line.
+%
+%begin{latexonly}
+\renewcommand{\indexname}{Module Index}
+%end{latexonly}
+\input{mod\jobname.ind}     % Module Index
+
+%begin{latexonly}
+\renewcommand{\indexname}{Index}
+%end{latexonly}
+\input{\jobname.ind}        % Index
+
+\end{document}