This is Info file /home/pdm/tmp/Python-1.5.2p1/Doc/lib/python-lib.info, produced by Makeinfo version 1.68 from the input file lib.texi. July 6, 1999 1.5.2  File: python-lib.info, Node: NNTP Objects, Prev: nntplib, Up: nntplib NNTP Objects ------------ NNTP instances have the following methods. The RESPONSE that is returned as the first item in the return tuple of almost all methods is the server's response: a string beginning with a three-digit code. If the server's response indicates an error, the method raises one of the above exceptions. `getwelcome()' Return the welcome message sent by the server in reply to the initial connection. (This message sometimes contains disclaimers or help information that may be relevant to the user.) `set_debuglevel(level)' Set the instance's debugging level. This controls the amount of debugging output printed. The default, `0', produces no debugging output. A value of `1' produces a moderate amount of debugging output, generally a single line per request or response. A value of `2' or higher produces the maximum amount of debugging output, logging each line sent and received on the connection (including message text). `newgroups(date, time)' Send a `NEWGROUPS' command. The DATE argument should be a string of the form `'YYMMDD'' indicating the date, and TIME should be a string of the form `'HHMMSS'' indicating the time. Return a pair `(RESPONSE, GROUPS)' where GROUPS is a list of group names that are new since the given date and time. `newnews(group, date, time)' Send a `NEWNEWS' command. Here, GROUP is a group name or `'*'', and DATE and TIME have the same meaning as for `newgroups()'. Return a pair `(RESPONSE, ARTICLES)' where ARTICLES is a list of article ids. `list()' Send a `LIST' command. Return a pair `(RESPONSE, LIST)' where LIST is a list of tuples. Each tuple has the form `(GROUP, LAST, FIRST, FLAG)', where GROUP is a group name, LAST and FIRST are the last and first article numbers (as strings), and FLAG is `'y'' if posting is allowed, `'n'' if not, and `'m'' if the newsgroup is moderated. (Note the ordering: LAST, FIRST.) `group(name)' Send a `GROUP' command, where NAME is the group name. Return a tuple `(RESPONSE, COUNT, FIRST, LAST, NAME)' where COUNT is the (estimated) number of articles in the group, FIRST is the first article number in the group, LAST is the last article number in the group, and NAME is the group name. The numbers are returned as strings. `help()' Send a `HELP' command. Return a pair `(RESPONSE, LIST)' where LIST is a list of help strings. `stat(id)' Send a `STAT' command, where ID is the message id (enclosed in `<' and `>') or an article number (as a string). Return a triple `(RESPONSE, NUMBER, ID)' where NUMBER is the article number (as a string) and ID is the article id (enclosed in `<' and `>'). `next()' Send a `NEXT' command. Return as for `stat()'. `last()' Send a `LAST' command. Return as for `stat()'. `head(id)' Send a `HEAD' command, where ID has the same meaning as for `stat()'. Return a tuple `(RESPONSE, NUMBER, ID, LIST)' where the first three are the same as for `stat()', and LIST is a list of the article's headers (an uninterpreted list of lines, without trailing newlines). `body(id)' Send a `BODY' command, where ID has the same meaning as for `stat()'. Return as for `head()'. `article(id)' Send a `ARTICLE' command, where ID has the same meaning as for `stat()'. Return as for `head()'. `slave()' Send a `SLAVE' command. Return the server's RESPONSE. `xhdr(header, string)' Send an `XHDR' command. This command is not defined in the RFC but is a common extension. The HEADER argument is a header keyword, e.g. `'subject''. The STRING argument should have the form `'FIRST-LAST'' where FIRST and LAST are the first and last article numbers to search. Return a pair `(RESPONSE, LIST)', where LIST is a list of pairs `(ID, TEXT)', where ID is an article id (as a string) and TEXT is the text of the requested header for that article. `post(file)' Post an article using the `POST' command. The FILE argument is an open file object which is read until EOF using its `readline()' method. It should be a well-formed news article, including the required headers. The `post()' method automatically escapes lines beginning with `.'. `ihave(id, file)' Send an `IHAVE' command. If the response is not an error, treat FILE exactly as for the `post()' method. `date()' Return a triple `(RESPONSE, DATE, TIME)', containing the current date and time in a form suitable for the `newnews()' and `newgroups()' methods. This is an optional NNTP extension, and may not be supported by all servers. `xgtitle(name)' Process an `XGTITLE' command, returning a pair `(RESPONSE, LIST)', where LIST is a list of tuples containing `(NAME, TITLE)'. This is an optional NNTP extension, and may not be supported by all servers. `xover(start, end)' Return a pair `(RESP, LIST)'. LIST is a list of tuples, one for each article in the range delimited by the START and END article numbers. Each tuple is of the form `(ARTICLE NUMBER, SUBJECT, POSTER, DATE, ID, REFERENCES, SIZE, LINES)'. This is an optional NNTP extension, and may not be supported by all servers. `xpath(id)' Return a pair `(RESP, PATH)', where PATH is the directory path to the article with message ID ID. This is an optional NNTP extension, and may not be supported by all servers. `quit()' Send a `QUIT' command and close the connection. Once this method has been called, no other methods of the NNTP object should be called.  File: python-lib.info, Node: smtplib, Next: telnetlib, Prev: nntplib, Up: Internet Protocols and Support SMTP protocol client ==================== SMTP protocol client (requires sockets). This section was written by Eric S. Raymond . The `smtplib' module defines an SMTP client session object that can be used to send mail to any Internet machine with an SMTP or ESMTP listener daemon. For details of SMTP and ESMTP operation, consult RFC 821 (*Simple Mail Transfer Protocol*) and RFC 1869 (*SMTP Service Extensions*). `SMTP([host[, port]])' A `SMTP' instance encapsulates an SMTP connection. It has methods that support a full repertoire of SMTP and ESMTP operations. If the optional host and port parameters are given, the SMTP `connect()' method is called with those parameters during initialization. An `SMTPConnectError' is raised if the specified host doesn't respond correctly. For normal use, you should only require the initialization/connect, `sendmail()', and `quit()' methods. An example is included below. A nice selection of exceptions is defined as well: `SMTPException' Base exception class for all exceptions raised by this module. `SMTPServerDisconnected' This exception is raised when the server unexpectedly disconnects, or when an attempt is made to use the `SMTP' instance before connecting it to a server. `SMTPResponseException' Base class for all exceptions that include an SMTP error code. These exceptions are generated in some instances when the SMTP server returns an error code. The error code is stored in the `smtp_code' attribute of the error, and the `smtp_error' attribute is set to the error message. `SMTPSenderRefused' Sender address refused. In addition to the attributes set by on all `SMTPResponseException' exceptions, this sets `sender' to the string that the SMTP server refused. `SMTPRecipientsRefused' All recipient addresses refused. The errors for each recipient are accessable through the attribute `recipients', which is a dictionary of exactly the same sort as `SMTP.sendmail()' returns. `SMTPDataError' The SMTP server refused to accept the message data. `SMTPConnectError' Error occurred during establishment of a connection with the server. `SMTPHeloError' The server refused our `HELO' message. * Menu: * SMTP Objects:: * SMTP Example::  File: python-lib.info, Node: SMTP Objects, Next: SMTP Example, Prev: smtplib, Up: smtplib SMTP Objects ------------ An `SMTP' instance has the following methods: `set_debuglevel(level)' Set the debug output level. A true value for LEVEL results in debug messages for connection and for all messages sent to and received from the server. `connect([host[, port]])' Connect to a host on a given port. The defaults are to connect to the local host at the standard SMTP port (25). If the hostname ends with a colon (`:') followed by a number, that suffix will be stripped off and the number interpreted as the port number to use. Note: This method is automatically invoked by the constructor if a host is specified during instantiation. `docmd(cmd, [, argstring])' Send a command CMD to the server. The optional argument ARGSTRING is simply concatenated to the command, separated by a space. This returns a 2-tuple composed of a numeric response code and the actual response line (multiline responses are joined into one long line.) In normal operation it should not be necessary to call this method explicitly. It is used to implement other methods and may be useful for testing private extensions. If the connection to the server is lost while waiting for the reply, `SMTPServerDisconnected' will be raised. `helo([hostname])' Identify yourself to the SMTP server using `HELO'. The hostname argument defaults to the fully qualified domain name of the local host. In normal operation it should not be necessary to call this method explicitly. It will be implicitly called by the `sendmail()' when necessary. `ehlo([hostname])' Identify yourself to an ESMTP server using `EHLO'. The hostname argument defaults to the fully qualified domain name of the local host. Examine the response for ESMTP option and store them for use by `has_option()'. Unless you wish to use `has_option()' before sending mail, it should not be necessary to call this method explicitly. It will be implicitly called by `sendmail()' when necessary. `has_extn(name)' Return `1' if NAME is in the set of SMTP service extensions returned by the server, `0' otherwise. Case is ignored. `verify(address)' Check the validity of an address on this server using SMTP `VRFY'. Returns a tuple consisting of code 250 and a full RFC 822 address (including human name) if the user address is valid. Otherwise returns an SMTP error code of 400 or greater and an error string. Note: many sites disable SMTP `VRFY' in order to foil spammers. `sendmail(from_addr, to_addrs, msg[, mail_options, rcpt_options])' Send mail. The required arguments are an RFC 822 from-address string, a list of RFC 822 to-address strings, and a message string. The caller may pass a list of ESMTP options (such as `8bitmime') to be used in `MAIL FROM' commands as MAIL_OPTIONS. ESMTP options (such as `DSN' commands) that should be used with all `RCPT' commands can be passed as RCPT_OPTIONS. (If you need to use different ESMTP options to different recipients you have to use the low-level methods such as `mail', `rcpt' and `data' to send the message.) If there has been no previous `EHLO' or `HELO' command this session, this method tries ESMTP `EHLO' first. If the server does ESMTP, message size and each of the specified options will be passed to it (if the option is in the feature set the server advertises). If `EHLO' fails, `HELO' will be tried and ESMTP options suppressed. This method will return normally if the mail is accepted for at least one recipient. Otherwise it will throw an exception. That is, if this method does not throw an exception, then someone should get your mail. If this method does not throw an exception, it returns a dictionary, with one entry for each recipient that was refused. Each entry contains a tuple of the SMTP error code and the accompanying error message sent by the server. This method may raise the following exceptions: * `SMTPRecipientsRefused' All recipients were refused. Nobody got the mail. The RECIPIENTS attribute of the exception object is a dictionary with information about the refused recipients (like the one returned when at least one recipient was accepted). * `SMTPHeloError' The server didn't reply properly to the helo greeting. * `SMTPSenderRefused' The server didn't accept the from_addr. * `SMTPDataError' The server replied with an unexpected error code (other than a refusal of a recipient). Unless otherwise noted the connection will be open even after an exception is raised. `quit()' Terminate the SMTP session and close the connection. Low-level methods corresponding to the standard SMTP/ESMTP commands `HELP', `RSET', `NOOP', `MAIL', `RCPT', and `DATA' are also supported. Normally these do not need to be called directly, so they are not documented here. For details, consult the module code.  File: python-lib.info, Node: SMTP Example, Prev: SMTP Objects, Up: smtplib SMTP Example ------------ This example prompts the user for addresses needed in the message envelop (`To' and `From' addresses), and the message to be delivered. Note that the headers to be included with the message must be included in the message as entered; this example doesn't do any processing of the RFC 822 headers. In particular, the `To' and `From' addresses must be included in the message headers explicitly. import rfc822, string, sys import smtplib def prompt(prompt): sys.stdout.write(prompt + ": ") return string.strip(sys.stdin.readline()) fromaddr = prompt("From") toaddrs = string.splitfields(prompt("To"), ',') print "Enter message, end with ^D:" msg = "" while 1: line = sys.stdin.readline() if not line: break msg = msg + line print "Message length is " + `len(msg)` server = smtplib.SMTP('localhost') server.set_debuglevel(1) server.sendmail(fromaddr, toaddrs, msg) server.quit() See also: Internet RFC 821, *Simple Mail Transfer Protocol*. Available online at `http://info.internet.isi.edu/in-notes/rfc/files/rfc821.txt'. Internet RFC 1869, *SMTP Service Extensions*. Available online at `http://info.internet.isi.edu/in-notes/rfc/files/rfc1869.txt'.  File: python-lib.info, Node: telnetlib, Next: urlparse, Prev: smtplib, Up: Internet Protocols and Support Telnet client ============= Telnet client class. The `telnetlib' module provides a `Telnet' class that implements the Telnet protocol. See RFC 854 for details about the protocol. `Telnet([host[, port]])' `Telnet' represents a connection to a telnet server. The instance is initially not connected; the `open()' method must be used to establish a connection. Alternatively, the host name and optional port number can be passed to the constructor, too. Do not reopen an already connected instance. This class has many `read_*()' methods. Note that some of them raise `EOFError' when the end of the connection is read, because they can return an empty string for other reasons. See the individual descriptions below. * Menu: * Telnet Objects::  File: python-lib.info, Node: Telnet Objects, Prev: telnetlib, Up: telnetlib Telnet Objects -------------- `Telnet' instances have the following methods: `read_until(expected[, timeout])' Read until a given string is encountered or until timeout. When no match is found, return whatever is available instead, possibly the empty string. Raise `EOFError' if the connection is closed and no cooked data is available. `read_all()' Read all data until `EOF'; block until connection closed. `read_some()' Read at least one byte of cooked data unless `EOF' is hit. Return `''' if `EOF' is hit. Block if no data is immediately available. `read_very_eager()' Read everything that can be without blocking in I/O (eager). Raise `EOFError' if connection closed and no cooked data available. Return `''' if no cooked data available otherwise. Do not block unless in the midst of an IAC sequence. `read_eager()' Read readily available data. Raise `EOFError' if connection closed and no cooked data available. Return `''' if no cooked data available otherwise. Do not block unless in the midst of an IAC sequence. `read_lazy()' Process and return data already in the queues (lazy). Raise `EOFError' if connection closed and no data available. Return `''' if no cooked data available otherwise. Do not block unless in the midst of an IAC sequence. `read_very_lazy()' Return any data available in the cooked queue (very lazy). Raise `EOFError' if connection closed and no data available. Return `''' if no cooked data available otherwise. This method never blocks. `open(host[, port])' Connect to a host. The optional second argument is the port number, which defaults to the standard telnet port (23). Do not try to reopen an already connected instance. `msg(msg[, *args])' Print a debug message when the debug level is `>' 0. If extra arguments are present, they are substituted in the message using the standard string formatting operator. `set_debuglevel(debuglevel)' Set the debug level. The higher the value of DEBUGLEVEL, the more debug output you get (on `sys.stdout'). `close()' Close the connection. `get_socket()' Return the socket object used internally. `fileno()' Return the file descriptor of the socket object used internally. `write(buffer)' Write a string to the socket, doubling any IAC characters. This can block if the connection is blocked. May raise `socket.error' if the connection is closed. `interact()' Interaction function, emulates a very dumb telnet client. `mt_interact()' Multithreaded version of `interact()'. `expect(list[, timeout])' Read until one from a list of a regular expressions matches. The first argument is a list of regular expressions, either compiled (`re.RegexObject' instances) or uncompiled (strings). The optional second argument is a timeout, in seconds; the default is to block indefinately. Return a tuple of three items: the index in the list of the first regular expression that matches; the match object returned; and the text read up till and including the match. If end of file is found and no text was read, raise `EOFError'. Otherwise, when nothing matches, return `(-1, None, TEXT)' where TEXT is the text received so far (may be the empty string if a timeout happened). If a regular expression ends with a greedy match (e.g. ".*") or if more than one expression can match the same input, the results are undeterministic, and may depend on the I/O timing.  File: python-lib.info, Node: urlparse, Next: SocketServer, Prev: telnetlib, Up: Internet Protocols and Support Parse URLs into components. =========================== Parse URLs into components. This module defines a standard interface to break URL strings up in components (addessing scheme, network location, path etc.), to combine the components back into a URL string, and to convert a "relative URL" to an absolute URL given a "base URL." The module has been designed to match the Internet RFC on Relative Uniform Resource Locators (and discovered a bug in an earlier draft!). Refer to RFC 1808 for details on relative URLs and RFC 1738 for information on basic URL syntax. It defines the following functions: `urlparse(urlstring[, default_scheme[, allow_fragments]])' Parse a URL into 6 components, returning a 6-tuple: (addressing scheme, network location, path, parameters, query, fragment identifier). This corresponds to the general structure of a URL: `SCHEME://NETLOC/PATH;PARAMETERS?QUERY#FRAGMENT'. Each tuple item is a string, possibly empty. The components are not broken up in smaller parts (e.g. the network location is a single string), and % escapes are not expanded. The delimiters as shown above are not part of the tuple items, except for a leading slash in the PATH component, which is retained if present. Example: urlparse('http://www.cwi.nl:80/%7Eguido/Python.html') yields the tuple ('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '') If the DEFAULT_SCHEME argument is specified, it gives the default addressing scheme, to be used only if the URL string does not specify one. The default value for this argument is the empty string. If the ALLOW_FRAGMENTS argument is zero, fragment identifiers are not allowed, even if the URL's addressing scheme normally does support them. The default value for this argument is `1'. `urlunparse(tuple)' Construct a URL string from a tuple as returned by `urlparse()'. This may result in a slightly different, but equivalent URL, if the URL that was parsed originally had redundant delimiters, e.g. a ? with an empty query (the draft states that these are equivalent). `urljoin(base, url[, allow_fragments])' Construct a full ("absolute") URL by combining a "base URL" (BASE) with a "relative URL" (URL). Informally, this uses components of the base URL, in particular the addressing scheme, the network location and (part of) the path, to provide missing components in the relative URL. Example: urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html') yields the string 'http://www.cwi.nl/%7Eguido/FAQ.html' The ALLOW_FRAGMENTS argument has the same meaning as for `urlparse()'.  File: python-lib.info, Node: SocketServer, Next: BaseHTTPServer, Prev: urlparse, Up: Internet Protocols and Support A framework for network servers. ================================ A framework for network servers. The `SocketServer' module simplifies the task of writing network servers. There are four basic server classes: `TCPServer' uses the Internet TCP protocol, which provides for continuous streams of data between the client and server. `UDPServer' uses datagrams, which are discrete packets of information that may arrive out of order or be lost while in transit. The more infrequently used `UnixStreamServer' and `UnixDatagramServer' classes are similar, but use UNIX domain sockets; they're not available on non-UNIX platforms. For more details on network programming, consult a book such as W. Richard Steven's *UNIX Network Programming* or Ralph Davis's *Win32 Network Programming*. These four classes process requests "synchronously"; each request must be completed before the next request can be started. This isn't suitable if each request takes a long time to complete, because it requires a lot of computation, or because it returns a lot of data which the client is slow to process. The solution is to create a separate process or thread to handle each request; the `ForkingMixIn' and `ThreadingMixIn' mix-in classes can be used to support asynchronous behaviour. Creating a server requires several steps. First, you must create a request handler class by subclassing the `BaseRequestHandler' class and overriding its `handle()' method; this method will process incoming requests. Second, you must instantiate one of the server classes, passing it the server's address and the request handler class. Finally, call the `handle_request()' or `serve_forever()' method of the server object to process one or many requests. Server classes have the same external methods and attributes, no matter what network protocol they use: `fileno()' Return an integer file descriptor for the socket on which the server is listening. This function is most commonly passed to `select.select()', to allow monitoring multiple servers in the same process. `handle_request()' Process a single request. This function calls the following methods in order: `get_request()', `verify_request()', and `process_request()'. If the user-provided `handle()' method of the handler class raises an exception, the server's `handle_error()' method will be called. `serve_forever()' Handle an infinite number of requests. This simply calls `handle_request()' inside an infinite loop. `address_family' The family of protocols to which the server's socket belongs. `socket.AF_INET' and `socket.AF_UNIX' are two possible values. `RequestHandlerClass' The user-provided request handler class; an instance of this class is created for each request. `server_address' The address on which the server is listening. The format of addresses varies depending on the protocol family; see the documentation for the socket module for details. For Internet protocols, this is a tuple containing a string giving the address, and an integer port number: `('127.0.0.1', 80)', for example. `socket' The socket object on which the server will listen for incoming requests. The server classes support the following class variables: `request_queue_size' The size of the request queue. If it takes a long time to process a single request, any requests that arrive while the server is busy are placed into a queue, up to `request_queue_size' requests. Once the queue is full, further requests from clients will get a "Connection denied" error. The default value is usually 5, but this can be overridden by subclasses. `socket_type' The type of socket used by the server; `socket.SOCK_STREAM' and `socket.SOCK_DGRAM' are two possible values. There are various server methods that can be overridden by subclasses of base server classes like `TCPServer'; these methods aren't useful to external users of the server object. `finish_request()' Actually processes the request by instantiating `RequestHandlerClass' and calling its `handle()' method. `get_request()' Must accept a request from the socket, and return a 2-tuple containing the *new* socket object to be used to communicate with the client, and the client's address. `handle_error(request, client_address)' This function is called if the `RequestHandlerClass''s `handle()' method raises an exception. The default action is to print the traceback to standard output and continue handling further requests. `process_request(request, client_address)' Calls `finish_request()' to create an instance of the `RequestHandlerClass'. If desired, this function can create a new process or thread to handle the request; the `ForkingMixIn' and `ThreadingMixIn' classes do this. `server_activate()' Called by the server's constructor to activate the server. May be overridden. `server_bind()' Called by the server's constructor to bind the socket to the desired address. May be overridden. `verify_request(request, client_address)' Must return a Boolean value; if the value is true, the request will be processed, and if it's false, the request will be denied. This function can be overridden to implement access controls for a server. The default implementation always return true. The request handler class must define a new `handle()' method, and can override any of the following methods. A new instance is created for each request. `finish()' Called after the `handle()' method to perform any clean-up actions required. The default implementation does nothing. If `setup()' or `handle()' raise an exception, this function will not be called. `handle()' This function must do all the work required to service a request. Several instance attributes are available to it; the request is available as `self.request'; the client address as `self.client_address'; and the server instance as `self.server', in case it needs access to per-server information. The type of `self.request' is different for datagram or stream services. For stream services, `self.request' is a socket object; for datagram services, `self.request' is a string. However, this can be hidden by using the mix-in request handler classes `StreamRequestHandler' or `DatagramRequestHandler', which override the `setup()' and `finish()' methods, and provides `self.rfile' and `self.wfile' attributes. `self.rfile' and `self.wfile' can be read or written, respectively, to get the request data or return data to the client. `setup()' Called before the `handle()' method to perform any initialization actions required. The default implementation does nothing.  File: python-lib.info, Node: BaseHTTPServer, Next: SimpleHTTPServer, Prev: SocketServer, Up: Internet Protocols and Support Basic HTTP server. ================== Basic HTTP server (base class for `SimpleHTTPServer' and `CGIHTTPServer'). 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 `SimpleHTTPServer' and `CGIHTTPServer' modules. The first class, `HTTPServer', is a `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: def run(server_class=BaseHTTPServer.HTTPServer, handler_class=BaseHTTPServer.BaseHTTPRequestHandler): server_address = ('', 8000) httpd = server_class(server_address, handler_class) httpd.serve_forever() `HTTPServer(server_address, RequestHandlerClass)' This class builds on the `TCPServer' class by storing the server address as instance variables named `server_name' and `server_port'. The server is accessible by the handler, typically through the handler's `server' instance variable. `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). `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 `SPAM', the `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 `__init__()' method. `BaseHTTPRequestHandler' has the following instance variables: `client_address' Contains a tuple of the form `(HOST, PORT)' referring to the client's address. `command' Contains the command (request type). For example, `'GET''. `path' Contains the request path. `request_version' Contains the version string from the request. For example, `'HTTP/1.0''. `headers' Holds an instance of the class specified by the `MessageClass' class variable. This instance parses and manages the headers in the HTTP request. `rfile' Contains an input stream, positioned at the start of the optional input data. `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. `BaseHTTPRequestHandler' has the following class variables: `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, `'BaseHTTP/0.2''. `sys_version' Contains the Python system version, in a form usable by the `version_string' method and the `server_version' class variable. For example, `'Python/1.4''. `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 CODE key should be an integer, specifing the numeric HTTP error code value. MESSAGE should be a string containing a (detailed) error message of what occurred, and EXPLAIN should be an explanation of the error code number. Default MESSAGE and EXPLAIN values can found in the RESPONSES class variable. `protocol_version' This specifies the HTTP protocol version used in responses. Typically, this should not be overridden. Defaults to `'HTTP/1.0''. `MessageClass' Specifies a `rfc822.Message'-like class to parse HTTP headers. Typically, this is not overridden, and it defaults to `mimetools.Message'. `responses' This variable contains a mapping of error code integers to two-element tuples containing a short and long message. For example, `{CODE: (SHORTMESSAGE, LONGMESSAGE)}'. The SHORTMESSAGE is usually used as the MESSAGE key in an error response, and LONGMESSAGE as the EXPLAIN key (see the `error_message_format' class variable). A `BaseHTTPRequestHandler' instance has the following methods: `handle()' Overrides the superclass' `handle()' method to provide the specific handler behavior. This method will parse and dispatch the request to the appropriate `do_*()' method. `send_error(code[, message])' Sends and logs a complete error reply to the client. The numeric CODE specifies the HTTP error code, with MESSAGE as optional, more specific text. A complete set of headers is sent, followed by text composed using the `error_message_format' class variable. `send_response(code[, message])' Sends a response header and logs the accepted request. The HTTP response line is sent, followed by *Server* and *Date* headers. The values for these two headers are picked up from the `version_string()' and `date_time_string()' methods, respectively. `send_header(keyword, value)' Writes a specific MIME header to the output stream. KEYWORD should specify the header keyword, with VALUE specifying its value. `end_headers()' Sends a blank line, indicating the end of the MIME headers in the response. `log_request([code[, size]])' Logs an accepted (successful) request. 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 SIZE parameter. `log_error(...)' Logs an error when a request cannot be fulfilled. By default, it passes the message to `log_message()', so it takes the same arguments (FORMAT and additional values). `log_message(format, ...)' Logs an arbitrary message to `sys.stderr'. This is typically overridden to create custom error logging mechanisms. The FORMAT argument is a standard printf-style format string, where the additional arguments to `log_message()' are applied as inputs to the formatting. The client address and current date and time are prefixed to every message logged. `version_string()' Returns the server software's version string. This is a combination of the `server_version' and `sys_version' class variables. `date_time_string()' Returns the current date and time, formatted for a message header. `log_data_time_string()' Returns the current date and time, formatted for logging. `address_string()' Returns the client address, formatted for logging. A name lookup is performed on the client's IP address. See also: *Note CGIHTTPServer:: Extended request handler that supports CGI scripts. *Note SimpleHTTPServer:: Basic request handler that limits response to files actually under the document root.  File: python-lib.info, Node: SimpleHTTPServer, Next: CGIHTTPServer, Prev: BaseHTTPServer, Up: Internet Protocols and Support A Do-Something Request Handler ============================== This section was written by Moshe Zadka . This module provides a request handler for HTTP servers. The `SimpleHTTPServer' module defines a request-handler class, interface compatible with `BaseHTTPServer.BaseHTTPRequestHandler' which serves files only from a base directory. The `SimpleHTTPServer' module defines the following class: `SimpleHTTPRequestHandler(request, client_address, server)' This class is used, to serve files from current directory and below, directly mapping the directory structure to HTTP requests. A lot of the work is done by the base class `BaseHTTPServer.BaseHTTPRequestHandler', such as parsing the request. This class implements the `do_GET()' and `do_HEAD()' functions. The `SimpleHTTPRequestHandler' defines the following member variables: `server_version' This will be `"SimpleHTTP/" + __version__', where `__version__' is defined in the module. `extensions_map' A dictionary mapping suffixes into MIME types. Default is signified by an empty string, and is considered to be `text/plain'. The mapping is used case-insensitively, and so should contain only lower-cased keys. The `SimpleHTTPRequestHandler' defines the following methods: `do_HEAD()' This method serves the `'HEAD'' request type: it sends the headers it would send for the equivalent `GET' request. See the `do_GET()' method for more complete explanation of the possible headers. `do_GET()' The request is mapped to a local file by interpreting the request as a path relative to the current working directory. If the request was mapped to a directory, a `403' respond is output, followed by the explanation `'Directory listing not supported''. Any `IOError' exception in opening the requested file, is mapped to a `404', `'File not found'' error. Otherwise, the content type is guessed using the EXTENSIONS_MAP variable. A `'Content-type:'' with the guessed content type is output, and then a blank line, signifying end of headers, and then the contents of the file. The file is always opened in binary mode. For example usage, see the implementation of the `test()' function. See also: *Note BaseHTTPServer:: Base class implementation for Web server and request handler.  File: python-lib.info, Node: CGIHTTPServer, Next: asyncore, Prev: SimpleHTTPServer, Up: Internet Protocols and Support A Do-Something Request Handler ============================== This section was written by Moshe Zadka . This module provides a request handler for HTTP servers which can run CGI scripts. The `CGIHTTPServer' module defines a request-handler class, interface compatible with `BaseHTTPServer.BaseHTTPRequestHandler' and inherits behaviour from `SimpleHTTPServer.SimpleHTTPRequestHandler' but can also run CGI scripts. The `CGIHTTPServer' module defines the following class: `CGIHTTPRequestHandler(request, client_address, server)' This class is used to serve either files or output of CGI scripts from the current directory and below. Note that mapping HTTP hierarchic structure to local directory structure is exactly as in `SimpleHTTPServer.SimpleHTTPRequestHandler'. The class will however, run the CGI script, instead of serving it as a file, if it guesses it to be a CGI script. Only directory-based CGI are used -- the other common server configuration is to treat special extensions as denoting CGI scripts. The `do_GET()' and `do_HEAD()' functions are modified to run CGI scripts and serve the output, instead of serving files, if the request leads to somewhere below the `cgi_directories' path. The `CGIHTTPRequestHandler' defines the following data member: `cgi_directories' This defaults to `['/cgi-bin', '/htbin']' and describes directories to treat as containing CGI scripts. The `CGIHTTPRequestHandler' defines the following methods: `do_POST()' This method serves the `'POST'' request type, only allowed for CGI scripts. Error 501, "Can only POST to CGI scripts", is output when trying to POST to a non-CGI url. Note that CGI scripts will be run with UID of user nobody, for security reasons. Problems with the CGI script will be translated to error 403. For example usage, see the implementation of the `test()' function. See also: *Note BaseHTTPServer:: Base class implementation for Web server and request handler.  File: python-lib.info, Node: asyncore, Prev: CGIHTTPServer, Up: Internet Protocols and Support Asyncronous socket handler ========================== A base class for developing asyncronous socket handling services. This module was documented by Sam Rushing . This section was written by Christopher Petrilli . This module provides the basic infrastructure for writing asyncronous socket service clients and servers. There are only two ways to have a program on a single processor do "more than one thing at a time." Multi-threaded programming is the simplest and most popular way to do it, but there is another very different technique, that lets youhave nearly all the advantages of multi-threading, without actually using multiple threads. it's really only practical if your program is largely I/O bound. If your program is CPU bound, then pre-emtpive scheduled threads are probably what you really need. Network servers are rarely CPU-bound, however. If your operating system supports the `select()' system call in its I/O library (and nearly all do), then you can use it to juggle multiple communication channels at once; doing other work while your I/O is taking place in the "background." Although this strategy can seem strange and complex, especially at first, it is in many ways easier to understand and control than multi-threaded programming. The module documented here solves manyof the difficult problems for you, making the task of building sophisticated high-performance network servers and clients a snap. `dispatcher()' The first class we will introduce is the `dispatcher' class. This is a thin wrapper around a low-level socket object. To make it more useful, it has a few methods for event-handling on it. Otherwise, it can be treated as a normal non-blocking socket object. The direct interface between the select loop and the socket object are the `handle_read_event()' and `handle_write_event()' methods. These are called whenever an object `fires' that event. The firing of these low-level events can tell us whether certain higher-level events have taken place, depending on the timing and the state of the connection. For example, if we have asked for a socket to connect to another host, we know that the connection has been made when the socket fires a write event (at this point you know that you may write to it with the expectation of success). The implied higher-level events are: Event Description ------ ----- handle_connect() Implied by a write event handle_close() Implied by a read event with no data available handle_accept() Implied by a read event on a listening socket This set of user-level events is larger than the basics. The full set of methods that can be overridden in your subclass are: `handle_read()' Called when there is new data to be read from a socket. `handle_write()' Called when there is an attempt to write data to the object. Often this method will implement the necessary buffering for performance. For example: def handle_write(self): sent = self.send(self.buffer) self.buffer = self.buffer[sent:] `handle_expt()' Called when there is out of band (OOB) data for a socket connection. This will almost never happen, as OOB is tenuously supported and rarely used. `handle_connect()' Called when the socket actually makes a connection. This might be used to send a "welcome" banner, or something similar. `handle_close()' Called when the socket is closed. `handle_accept()' Called on listening sockets when they actually accept a new connection. `readable()' Each time through the `select()' loop, the set of sockets is scanned, and this method is called to see if there is any interest in reading. The default method simply returns `1', indicating that by default, all channels will be interested. `writeable()' Each time through the `select()' loop, the set of sockets is scanned, and this method is called to see if there is any interest in writing. The default method simply returns `1', indiciating that by default, all channels will be interested. In addition, there are the basic methods needed to construct and manipulate "channels," which are what we will call the socket connections in this context. Note that most of these are nearly identical to their `socket' partners. `create_socket(family, type)' This is identical to the creation of a normal socket, and will use the same options for creation. This means you will need to reference the `socket' module. `connect(address)' As with the normal `socket' object, ADDRESS is a tuple with the first element the host to connect to, and the second the port. `send(data)' Send DATA out the socket. `recv(buffer_size)' Read at most BUFFER_SIZE bytes from the socket. `listen([backlog])' Listen for connections made to the socket. The BACKLOG argument specifies the maximum number of queued connections and should be at least 1; the maximum value is system-dependent (usually 5). `bind(address)' Bind the socket to ADDRESS. The socket must not already be bound. (The format of ADDRESS depends on the address family -- see above.) `accept()' Accept a connection. The socket must be bound to an address and listening for connections. The return value is a pair `(CONN, ADDRESS)' where CONN is a *new* socket object usable to send and receive data on the connection, and ADDRESS is the address bound to the socket on the other end of the connection. `close()' Close the socket. All future operations on the socket object will fail. The remote end will receive no more data (after queued data is flushed). Sockets are automatically closed when they are garbage-collected. * Menu: * Example basic HTTP client::  File: python-lib.info, Node: Example basic HTTP client, Prev: asyncore, Up: asyncore Example basic HTTP client ------------------------- As a basic example, below is a very basic HTTP client that uses the `dispatcher' class to implement its socket handling: class http_client(asyncore.dispatcher): def __init__(self, host,path): asyncore.dispatcher.__init__(self) self.path = path self.create_socket(socket.AF_INET, socket.SOCK_STREAM) self.connect( (host, 80) ) self.buffer = 'GET %s HTTP/1.0\r\b\r\n' % self.path def handle_connect(self): pass def handle_read(self): data = self.recv(8192) print data def writeable(self): return (len(self.buffer) > 0) def handle_write(self): sent = self.send(self.buffer) self.buffer = self.buffer[sent:]  File: python-lib.info, Node: Internet Data Handling, Next: Restricted Execution, Prev: Internet Protocols and Support, Up: Top Internet Data Handling ********************** This chapter describes modules which support handling data formats commonly used on the internet. Some, like SGML and XML, may be useful for other applications as well. * Menu: * sgmllib:: * htmllib:: * htmlentitydefs:: * xmllib:: * formatter:: * rfc822:: * mimetools:: * MimeWriter:: * multifile:: * binhex:: * uu:: * binascii:: * xdrlib:: * mailcap:: * mimetypes:: * base64:: * quopri:: * mailbox:: * mhlib:: * mimify:: * netrc::