diff options
| -rw-r--r-- | Doc/Makefile | 21 | ||||
| -rw-r--r-- | Doc/lib.tex | 3 | ||||
| -rw-r--r-- | Doc/lib/lib.tex | 3 | ||||
| -rw-r--r-- | Doc/lib/libbasehttp.tex | 216 | ||||
| -rw-r--r-- | Doc/libbasehttp.tex | 216 |
5 files changed, 447 insertions, 12 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index 72f5802..5548881 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -119,7 +119,8 @@ LIBFILES = lib.tex \ libbase64.tex libfnmatch.tex libquopri.tex libzlib.tex libsocksvr.tex \ libmailbox.tex libcommands.tex libcmath.tex libni.tex libgzip.tex \ libpprint.tex libcode.tex libmimify.tex libre.tex libmacic.tex \ - libuserdict.tex libdis.tex libxmllib.tex libqueue.tex liblocale.tex + libuserdict.tex libdis.tex libxmllib.tex libqueue.tex \ + liblocale.tex libbasehttp.tex # Library document lib.dvi: $(LIBFILES) @@ -182,16 +183,16 @@ lib.info: python-lib.info # HTML converter. For more info on this program, see # <URL:http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html>. -# Note that LaTeX2HTML inserts references to an "icons" directory in -# each page that it generates. You can customize where these icons -# are to be found; I generally make it point to "../icons" and then -# create a symbolic link to the icons directory in the LaTeX2HTML -# source at the appropriate place. Change the definition of -# $ICONSERVER in .latex2html-init to point to a different location. +# Note that LaTeX2HTML inserts references to an icons directory in +# each page that it generates. I have placed a copy of this directory +# in the distribution to simplify the process of creating a +# self-contained HTML distribution; for this purpose I have also added +# a (trivial) index.html. Change the definition of $ICONSERVER in +# .latex2html-init to use a different location for the icons directory. -# The sed hack rips out a superfluous comma which I haven't found the source -# of; the prominent location makes it worth the extra step. This affects the -# title pages! +# The sed hack rips out a superfluous comma which I haven't found the +# source of. The prominent location makes it worth the extra step; +# this affects the title pages! l2h: l2htut l2hext l2hlib l2hapi diff --git a/Doc/lib.tex b/Doc/lib.tex index 055e61d..5082464 100644 --- a/Doc/lib.tex +++ b/Doc/lib.tex @@ -98,9 +98,9 @@ to Python and how to embed it in other applications. \input{libstrings} % String Services \input{libstring} +\input{libre} \input{libregex} \input{libregsub} -\input{libre} \input{libstruct} \input{libstrio} \input{libsoundex} @@ -176,6 +176,7 @@ to Python and how to embed it in other applications. \input{libsocksvr} \input{libmailbox} \input{libmimify} +\input{libbasehttp} \input{librestricted} \input{librexec} diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 055e61d..5082464 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -98,9 +98,9 @@ to Python and how to embed it in other applications. \input{libstrings} % String Services \input{libstring} +\input{libre} \input{libregex} \input{libregsub} -\input{libre} \input{libstruct} \input{libstrio} \input{libsoundex} @@ -176,6 +176,7 @@ to Python and how to embed it in other applications. \input{libsocksvr} \input{libmailbox} \input{libmimify} +\input{libbasehttp} \input{librestricted} \input{librexec} diff --git a/Doc/lib/libbasehttp.tex b/Doc/lib/libbasehttp.tex new file mode 100644 index 0000000..b9e2edb --- /dev/null +++ b/Doc/lib/libbasehttp.tex @@ -0,0 +1,216 @@ +\section{Standard Module \sectcode{BaseHTTPServer}} +\label{module-BaseHTTPServer} +\stmodindex{BaseHTTPServer} + +\indexii{WWW}{server} +\indexii{HTTP}{protocol} +\index{URL} +\index{httpd} + +\renewcommand{\indexsubitem}{(in module BaseHTTPServer)} + +This module defines two classes for implementing HTTP servers +(web servers). Usually, this module isn't used directly, but is used +as a basis for building functioning web servers. See the +\code{SimpleHTTPServer} and \code{CGIHTTPServer} modules. +\stmodindex{SimpleHTTPServer} +\stmodindex{CGIHTTPServer} + +The first class, \code{HTTPServer}, is a \code{SocketServer.TCPServer} +subclass. It creates and listens at the web socket, dispatching the +requests to a handler. Code to create and run the server looks like +this: + +\bcode\begin{verbatim} +def run(server_class=BaseHTTPServer.HTTPServer, + handler_class=BaseHTTPServer.BaseHTTPRequestHandler): + server_address = ('', 8000) + httpd = server_class(server_address, handler_class) + httpd.serve_forever() +\end{verbatim}\ecode +% +The \code{HTTPServer} class builds on the \code{TCPServer} class by +storing the server address as instance +variables named \code{server_name} and \code{server_port}. The +server is accessible by the handler, typically through the handler's +\code{server} instance variable. + +The module's second class, \code{BaseHTTPRequestHandler}, is used +to handle the HTTP requests that arrive at the server. By itself, +it cannot respond to any actual HTTP requests; it must be subclassed +to handle each request method (e.g. GET or POST). +\code{BaseHTTPRequestHandler} provides a number of class and instance +variables, and methods for use by subclasses. + +The handler will parse the request and the headers, then call a +method specific to the request type. The method name is constructed +from the request. For example, for the request \code{SPAM}, the +\code{do_SPAM} method will be called with no arguments. All of +the relevant information is stored into instance variables of the +handler. + +\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler instance variables)} + +\code{BaseHTTPRequestHandler} has the following instance variables: + +\begin{datadesc}{client_address} +Contains a tuple of the form (host, port) referring to the client's +address. +\end{datadesc} + +\begin{datadesc}{command} +Contains the command (request type). For example, \code{"GET"}. +\end{datadesc} + +\begin{datadesc}{path} +Contains the request path. +\end{datadesc} + +\begin{datadesc}{request_version} +Contains the version string from the request. For example, +\code{"HTTP/1.0"}. +\end{datadesc} + +\begin{datadesc}{headers} +Holds an instance of the class specified by the \var{MessageClass} +class variable. This instance parses and manages the headers in +the HTTP request. +\end{datadesc} + +\begin{datadesc}{rfile} +Contains an input stream, positioned at the start of the optional +input data. +\end{datadesc} + +\begin{datadesc}{wfile} +Contains the output stream for writing a response back to the client. +Proper adherance to the HTTP protocol must be used when writing +to this stream. +\end{datadesc} + +\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler class variables)} + +\code{BaseHTTPRequestHandler} has the following class variables: + +\begin{datadesc}{server_version} +Specifies the server software version. You may want to override +this. +The format is multiple whitespace-separated strings, +where each string is of the form name[/version]. +For example, \code{"BaseHTTP/0.2"}. +\end{datadesc} + +\begin{datadesc}{sys_version} +Contains the Python system version, in a form usable by the +\code{version_string} method and the \code{server_version} class +variable. For example, \code{"Python/1.4"}. +\end{datadesc} + +\begin{datadesc}{error_message_format} +Specifies a format string for building an error response to the +client. It uses parenthesized, keyed format specifiers, so the +format operand must be a dictionary. The \var{code} key should +be an integer, specifing the numeric HTTP error code value. +\var{message} should be a string containing a (detailed) error +message of what occurred, and \var{explain} should be an +explanation of the error code number. Default \var{message} +and \var{explain} values can found in the \var{responses} +class variable. +\end{datadesc} + +\begin{datadesc}{protocol_version} +This specifies the HTTP protocol version used in responses. +Typically, this should not be overridden. Defaults to +\code{"HTTP/1.0"}. +\end{datadesc} + +\begin{datadesc}{MessageClass} +Specifies a Message-like class to parse HTTP headers. Typically, +this is not overridden, and it defaults to \code{mimetools.Message}. +\end{datadesc} + +\begin{datadesc}{responses} +This variable contains a mapping of error code integers to two-element +tuples containing a short and long message. For example, +\code{\{code : (shortmessage, longmessage)\}}. The +\var{shortmessage} is usually used as the \var{message} key in an +error response, and \var{longmessage} as the \var{explain} key +(see the \code{error_message_format} class variable). +\end{datadesc} + +\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler method)} + +A \code{BaseHTTPRequestHandler} instance has the following methods: + +\begin{funcdesc}{handle}{} +Overrides the superclass' \code{handle} method to provide the +specific handler behavior. This method will parse and dispatch +the request to the appropriate \code{do_}* method. +\end{funcdesc} + +\begin{funcdesc}{send_error}{code\optional{\, message}} +Sends and logs a complete error reply to the client. The numeric +\var{code} specifies the HTTP error code, with \var{message} as +optional, more specific text. A complete set of headers is sent, +followed by text composed using the \code{error_message_format} +class variable. +\end{funcdesc} + +\begin{funcdesc}{send_response}{code\optional{\, message}} +Sends a response header and logs the accepted request. The HTTP +response line is sent, followed by \emph{Server} and \emph{Date} +headers. The values for these two headers are picked up from the +\code{version_string()} and \code{date_time_string()} methods, +respectively. +\end{funcdesc} + +\begin{funcdesc}{send_header}{keyword\, value} +Writes a specific MIME header to the output stream. \var{keyword} +should specify the header keyword, with \var{value} specifying +its value. +\end{funcdesc} + +\begin{funcdesc}{end_headers}{} +Sends a blank line, indicating the end of the MIME headers in +the response. +\end{funcdesc} + +\begin{funcdesc}{log_request}{\optional{code\optional{\, size}}} +Logs an accepted (successful) request. \var{code} should specify +the numeric HTTP code associated with the response. If a size of +the response is available, then it should be passed as the +\var{size} parameter. +\end{funcdesc} + +\begin{funcdesc}{log_error}{...} +Logs an error when a request cannot be fulfilled. By default, +it passes the message to \code{log_message}, so it takes the +same arguments (\var{format} and additional values). +\end{funcdesc} + +\begin{funcdesc}{log_message}{format, ...} +Logs an arbitrary message to \code{sys.stderr}. This is typically +overridden to create custom error logging mechanisms. The +\var{format} argument is a standard printf-style format string, +where the additional arguments to \code{log_message} are applied +as inputs to the formatting. The client address and current date +and time are prefixed to every message logged. +\end{funcdesc} + +\begin{funcdesc}{version_string}{} +Returns the server software's version string. This is a combination +of the \var{server_version} and \var{sys_version} class variables. +\end{funcdesc} + +\begin{funcdesc}{date_time_string}{} +Returns the current date and time, formatted for a message header. +\end{funcdesc} + +\begin{funcdesc}{log_data_time_string}{} +Returns the current date and time, formatted for logging. +\end{funcdesc} + +\begin{funcdesc}{address_string}{} +Returns the client address, formatted for logging. A name lookup +is performed on the client's IP address. +\end{funcdesc} diff --git a/Doc/libbasehttp.tex b/Doc/libbasehttp.tex new file mode 100644 index 0000000..b9e2edb --- /dev/null +++ b/Doc/libbasehttp.tex @@ -0,0 +1,216 @@ +\section{Standard Module \sectcode{BaseHTTPServer}} +\label{module-BaseHTTPServer} +\stmodindex{BaseHTTPServer} + +\indexii{WWW}{server} +\indexii{HTTP}{protocol} +\index{URL} +\index{httpd} + +\renewcommand{\indexsubitem}{(in module BaseHTTPServer)} + +This module defines two classes for implementing HTTP servers +(web servers). Usually, this module isn't used directly, but is used +as a basis for building functioning web servers. See the +\code{SimpleHTTPServer} and \code{CGIHTTPServer} modules. +\stmodindex{SimpleHTTPServer} +\stmodindex{CGIHTTPServer} + +The first class, \code{HTTPServer}, is a \code{SocketServer.TCPServer} +subclass. It creates and listens at the web socket, dispatching the +requests to a handler. Code to create and run the server looks like +this: + +\bcode\begin{verbatim} +def run(server_class=BaseHTTPServer.HTTPServer, + handler_class=BaseHTTPServer.BaseHTTPRequestHandler): + server_address = ('', 8000) + httpd = server_class(server_address, handler_class) + httpd.serve_forever() +\end{verbatim}\ecode +% +The \code{HTTPServer} class builds on the \code{TCPServer} class by +storing the server address as instance +variables named \code{server_name} and \code{server_port}. The +server is accessible by the handler, typically through the handler's +\code{server} instance variable. + +The module's second class, \code{BaseHTTPRequestHandler}, is used +to handle the HTTP requests that arrive at the server. By itself, +it cannot respond to any actual HTTP requests; it must be subclassed +to handle each request method (e.g. GET or POST). +\code{BaseHTTPRequestHandler} provides a number of class and instance +variables, and methods for use by subclasses. + +The handler will parse the request and the headers, then call a +method specific to the request type. The method name is constructed +from the request. For example, for the request \code{SPAM}, the +\code{do_SPAM} method will be called with no arguments. All of +the relevant information is stored into instance variables of the +handler. + +\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler instance variables)} + +\code{BaseHTTPRequestHandler} has the following instance variables: + +\begin{datadesc}{client_address} +Contains a tuple of the form (host, port) referring to the client's +address. +\end{datadesc} + +\begin{datadesc}{command} +Contains the command (request type). For example, \code{"GET"}. +\end{datadesc} + +\begin{datadesc}{path} +Contains the request path. +\end{datadesc} + +\begin{datadesc}{request_version} +Contains the version string from the request. For example, +\code{"HTTP/1.0"}. +\end{datadesc} + +\begin{datadesc}{headers} +Holds an instance of the class specified by the \var{MessageClass} +class variable. This instance parses and manages the headers in +the HTTP request. +\end{datadesc} + +\begin{datadesc}{rfile} +Contains an input stream, positioned at the start of the optional +input data. +\end{datadesc} + +\begin{datadesc}{wfile} +Contains the output stream for writing a response back to the client. +Proper adherance to the HTTP protocol must be used when writing +to this stream. +\end{datadesc} + +\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler class variables)} + +\code{BaseHTTPRequestHandler} has the following class variables: + +\begin{datadesc}{server_version} +Specifies the server software version. You may want to override +this. +The format is multiple whitespace-separated strings, +where each string is of the form name[/version]. +For example, \code{"BaseHTTP/0.2"}. +\end{datadesc} + +\begin{datadesc}{sys_version} +Contains the Python system version, in a form usable by the +\code{version_string} method and the \code{server_version} class +variable. For example, \code{"Python/1.4"}. +\end{datadesc} + +\begin{datadesc}{error_message_format} +Specifies a format string for building an error response to the +client. It uses parenthesized, keyed format specifiers, so the +format operand must be a dictionary. The \var{code} key should +be an integer, specifing the numeric HTTP error code value. +\var{message} should be a string containing a (detailed) error +message of what occurred, and \var{explain} should be an +explanation of the error code number. Default \var{message} +and \var{explain} values can found in the \var{responses} +class variable. +\end{datadesc} + +\begin{datadesc}{protocol_version} +This specifies the HTTP protocol version used in responses. +Typically, this should not be overridden. Defaults to +\code{"HTTP/1.0"}. +\end{datadesc} + +\begin{datadesc}{MessageClass} +Specifies a Message-like class to parse HTTP headers. Typically, +this is not overridden, and it defaults to \code{mimetools.Message}. +\end{datadesc} + +\begin{datadesc}{responses} +This variable contains a mapping of error code integers to two-element +tuples containing a short and long message. For example, +\code{\{code : (shortmessage, longmessage)\}}. The +\var{shortmessage} is usually used as the \var{message} key in an +error response, and \var{longmessage} as the \var{explain} key +(see the \code{error_message_format} class variable). +\end{datadesc} + +\renewcommand{\indexsubitem}{(BaseHTTPRequestHandler method)} + +A \code{BaseHTTPRequestHandler} instance has the following methods: + +\begin{funcdesc}{handle}{} +Overrides the superclass' \code{handle} method to provide the +specific handler behavior. This method will parse and dispatch +the request to the appropriate \code{do_}* method. +\end{funcdesc} + +\begin{funcdesc}{send_error}{code\optional{\, message}} +Sends and logs a complete error reply to the client. The numeric +\var{code} specifies the HTTP error code, with \var{message} as +optional, more specific text. A complete set of headers is sent, +followed by text composed using the \code{error_message_format} +class variable. +\end{funcdesc} + +\begin{funcdesc}{send_response}{code\optional{\, message}} +Sends a response header and logs the accepted request. The HTTP +response line is sent, followed by \emph{Server} and \emph{Date} +headers. The values for these two headers are picked up from the +\code{version_string()} and \code{date_time_string()} methods, +respectively. +\end{funcdesc} + +\begin{funcdesc}{send_header}{keyword\, value} +Writes a specific MIME header to the output stream. \var{keyword} +should specify the header keyword, with \var{value} specifying +its value. +\end{funcdesc} + +\begin{funcdesc}{end_headers}{} +Sends a blank line, indicating the end of the MIME headers in +the response. +\end{funcdesc} + +\begin{funcdesc}{log_request}{\optional{code\optional{\, size}}} +Logs an accepted (successful) request. \var{code} should specify +the numeric HTTP code associated with the response. If a size of +the response is available, then it should be passed as the +\var{size} parameter. +\end{funcdesc} + +\begin{funcdesc}{log_error}{...} +Logs an error when a request cannot be fulfilled. By default, +it passes the message to \code{log_message}, so it takes the +same arguments (\var{format} and additional values). +\end{funcdesc} + +\begin{funcdesc}{log_message}{format, ...} +Logs an arbitrary message to \code{sys.stderr}. This is typically +overridden to create custom error logging mechanisms. The +\var{format} argument is a standard printf-style format string, +where the additional arguments to \code{log_message} are applied +as inputs to the formatting. The client address and current date +and time are prefixed to every message logged. +\end{funcdesc} + +\begin{funcdesc}{version_string}{} +Returns the server software's version string. This is a combination +of the \var{server_version} and \var{sys_version} class variables. +\end{funcdesc} + +\begin{funcdesc}{date_time_string}{} +Returns the current date and time, formatted for a message header. +\end{funcdesc} + +\begin{funcdesc}{log_data_time_string}{} +Returns the current date and time, formatted for logging. +\end{funcdesc} + +\begin{funcdesc}{address_string}{} +Returns the client address, formatted for logging. A name lookup +is performed on the client's IP address. +\end{funcdesc} |