From 458120dd40db6b4df55a4e96b650e16798ef06a0 Mon Sep 17 00:00:00 2001 From: cinap_lenrek Date: Tue, 3 May 2011 11:25:13 +0000 Subject: add hg and python --- sys/src/cmd/python/Doc/lib/libbasehttp.tex | 245 +++++++++++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 sys/src/cmd/python/Doc/lib/libbasehttp.tex (limited to 'sys/src/cmd/python/Doc/lib/libbasehttp.tex') diff --git a/sys/src/cmd/python/Doc/lib/libbasehttp.tex b/sys/src/cmd/python/Doc/lib/libbasehttp.tex new file mode 100644 index 000000000..64c069f07 --- /dev/null +++ b/sys/src/cmd/python/Doc/lib/libbasehttp.tex @@ -0,0 +1,245 @@ +\section{\module{BaseHTTPServer} --- + Basic HTTP server} + +\declaremodule{standard}{BaseHTTPServer} +\modulesynopsis{Basic HTTP server (base class for + \class{SimpleHTTPServer} and \class{CGIHTTPServer}).} + + +\indexii{WWW}{server} +\indexii{HTTP}{protocol} +\index{URL} +\index{httpd} + +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 +\refmodule{SimpleHTTPServer}\refstmodindex{SimpleHTTPServer} and +\refmodule{CGIHTTPServer}\refstmodindex{CGIHTTPServer} modules. + +The first class, \class{HTTPServer}, is a +\class{SocketServer.TCPServer} subclass. It creates and listens at the +HTTP socket, dispatching the requests to a handler. Code to create and +run the server looks like this: + +\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} + +\begin{classdesc}{HTTPServer}{server_address, RequestHandlerClass} +This class builds on the \class{TCPServer} class by +storing the server address as instance +variables named \member{server_name} and \member{server_port}. The +server is accessible by the handler, typically through the handler's +\member{server} instance variable. +\end{classdesc} + +\begin{classdesc}{BaseHTTPRequestHandler}{request, client_address, server} +This class 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). +\class{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 method \samp{SPAM}, the +\method{do_SPAM()} method will be called with no arguments. All of +the relevant information is stored in instance variables of the +handler. Subclasses should not need to override or extend the +\method{__init__()} method. +\end{classdesc} + + +\class{BaseHTTPRequestHandler} has the following instance variables: + +\begin{memberdesc}{client_address} +Contains a tuple of the form \code{(\var{host}, \var{port})} referring +to the client's address. +\end{memberdesc} + +\begin{memberdesc}{command} +Contains the command (request type). For example, \code{'GET'}. +\end{memberdesc} + +\begin{memberdesc}{path} +Contains the request path. +\end{memberdesc} + +\begin{memberdesc}{request_version} +Contains the version string from the request. For example, +\code{'HTTP/1.0'}. +\end{memberdesc} + +\begin{memberdesc}{headers} +Holds an instance of the class specified by the \member{MessageClass} +class variable. This instance parses and manages the headers in +the HTTP request. +\end{memberdesc} + +\begin{memberdesc}{rfile} +Contains an input stream, positioned at the start of the optional +input data. +\end{memberdesc} + +\begin{memberdesc}{wfile} +Contains the output stream for writing a response back to the client. +Proper adherence to the HTTP protocol must be used when writing +to this stream. +\end{memberdesc} + + +\class{BaseHTTPRequestHandler} has the following class variables: + +\begin{memberdesc}{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{memberdesc} + +\begin{memberdesc}{sys_version} +Contains the Python system version, in a form usable by the +\member{version_string} method and the \member{server_version} class +variable. For example, \code{'Python/1.4'}. +\end{memberdesc} + +\begin{memberdesc}{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, specifying 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{memberdesc} + +\begin{memberdesc}{protocol_version} +This specifies the HTTP protocol version used in responses. If set +to \code{'HTTP/1.1'}, the server will permit HTTP persistent +connections; however, your server \emph{must} then include an +accurate \code{Content-Length} header (using \method{send_header()}) +in all of its responses to clients. For backwards compatibility, +the setting defaults to \code{'HTTP/1.0'}. +\end{memberdesc} + +\begin{memberdesc}{MessageClass} +Specifies a \class{rfc822.Message}-like class to parse HTTP +headers. Typically, this is not overridden, and it defaults to +\class{mimetools.Message}. +\withsubitem{(in module mimetools)}{\ttindex{Message}} +\end{memberdesc} + +\begin{memberdesc}{responses} +This variable contains a mapping of error code integers to two-element +tuples containing a short and long message. For example, +\code{\{\var{code}: (\var{shortmessage}, \var{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 \member{error_message_format} class variable). +\end{memberdesc} + + +A \class{BaseHTTPRequestHandler} instance has the following methods: + +\begin{methoddesc}{handle}{} +Calls \method{handle_one_request()} once (or, if persistent connections +are enabled, multiple times) to handle incoming HTTP requests. +You should never need to override it; instead, implement appropriate +\method{do_*()} methods. +\end{methoddesc} + +\begin{methoddesc}{handle_one_request}{} +This method will parse and dispatch +the request to the appropriate \method{do_*()} method. You should +never need to override it. +\end{methoddesc} + +\begin{methoddesc}{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 \member{error_message_format} +class variable. +\end{methoddesc} + +\begin{methoddesc}{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 +\method{version_string()} and \method{date_time_string()} methods, +respectively. +\end{methoddesc} + +\begin{methoddesc}{send_header}{keyword, value} +Writes a specific HTTP header to the output stream. \var{keyword} +should specify the header keyword, with \var{value} specifying +its value. +\end{methoddesc} + +\begin{methoddesc}{end_headers}{} +Sends a blank line, indicating the end of the HTTP headers in +the response. +\end{methoddesc} + +\begin{methoddesc}{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{methoddesc} + +\begin{methoddesc}{log_error}{...} +Logs an error when a request cannot be fulfilled. By default, +it passes the message to \method{log_message()}, so it takes the +same arguments (\var{format} and additional values). +\end{methoddesc} + +\begin{methoddesc}{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 \method{log_message()} are applied +as inputs to the formatting. The client address and current date +and time are prefixed to every message logged. +\end{methoddesc} + +\begin{methoddesc}{version_string}{} +Returns the server software's version string. This is a combination +of the \member{server_version} and \member{sys_version} class variables. +\end{methoddesc} + +\begin{methoddesc}{date_time_string}{\optional{timestamp}} +Returns the date and time given by \var{timestamp} (which must be in the +format returned by \function{time.time()}), formatted for a message header. +If \var{timestamp} is omitted, it uses the current date and time. + +The result looks like \code{'Sun, 06 Nov 1994 08:49:37 GMT'}. +\versionadded[The \var{timestamp} parameter]{2.5} +\end{methoddesc} + +\begin{methoddesc}{log_date_time_string}{} +Returns the current date and time, formatted for logging. +\end{methoddesc} + +\begin{methoddesc}{address_string}{} +Returns the client address, formatted for logging. A name lookup +is performed on the client's IP address. +\end{methoddesc} + + +\begin{seealso} + \seemodule{CGIHTTPServer}{Extended request handler that supports CGI + scripts.} + + \seemodule{SimpleHTTPServer}{Basic request handler that limits response + to files actually under the document root.} +\end{seealso} -- cgit v1.2.3