Table of Contents

Class: WebServer qm/web.py

A web server that serves ordinary files and dynamic content.

To configure the server to serve ordinary files, register the directories containing those files with RegisterPathTranslations. An arbitrary number of directories may be specified, and all files in each directory and under it are made available.

To congifure the server to serve dynamic content, register dynamic URLs with RegisterScript. A request matching the URL exactly will cause the server to invoke the provided function.

The web server resolves request URLs in a two-step process.

  1. The server checks if the URL matches exactly a script URL. If a match is found, the corresponding function is invoked, and its return value is sent to the client.

  2. The server checks whether any registered path translation is a prefix of the reqest URL. If it is, the path is translated into a file system path, and the corresponding file is returned.

The server also provides a rudimentary manual caching mechanism for generated pages. The application may insert a generated page into the page cache, if it is expected not to change. The application can use this mechanism:

  • to supress duplicate generation of the same page,

  • or to pre-generate a page that may be requested later. This is particularly handy if generating the page requires state information that would be difficult to reconstruct later.

Pages may be shared across sessions, or may be specific to a particular session.

Base Classes   
HTTPServer
    BaseHTTPServer.HTTPServer
Methods   
Bind
CachePage
GetCachedPage
GetServerAddress
GetTemporaryAttachmentStore
HandleNoSessionError
IsScript
LogMessage
MakeButtonForCachedPopup
MakeConfirmationDialog
MakePopupDialog
ProcessScript
RegisterPathTranslation
RegisterScript
RequestShutdown
Run
TranslateRequest
_HandleProblems
_HandleRoot
__GetPathForCachedPage
__init__
handle_error
  Bind 
Bind ( self )

Bind the server to the specified address and port.

Does not start serving.

Exceptions   
AddressInUseError, address
PrivilegedPortError, "port %d" % self.__port
  CachePage 
CachePage (
        self,
        page_text,
        session_id=None,
        )

Cache an HTML page.

page_text
The text of the page.
session_id
The session ID for this page, or None.
returns
A WebRequest object with which the cached page can be retrieved later.

If session_id is None, the page is placed in the global page cache. Otherwise, it is placed in the session page cache for that session.

  GetCachedPage 
GetCachedPage (
        self,
        request,
        session_id=None,
        )

Retrieve a page from the page cache.

request
The URL requesting the page from the cache.
session_id
The session ID for the request, or None.
returns
The cached page, or a placeholder page if the page was not found in the cache.

If session_id is None, the page is retrieved from the global page cache. Otherwise, it is retrieved from the session page cache for that session.

  GetServerAddress 
GetServerAddress ( self )

Return the host address on which this server is running.

returns
A pair (hostname, port).
  GetTemporaryAttachmentStore 
GetTemporaryAttachmentStore ( self )

Return the AttachmentStore used for new 'Attachment's.

returns
The AttachmentStore used for new 'Attachment's.
  HandleNoSessionError 
HandleNoSessionError (
        self,
        request,
        message,
        )

Handler when session is absent.

Exceptions   
HttpRedirect( request )
  IsScript 
IsScript ( self,  request )

Return a true value if request corresponds to a script.

  LogMessage 
LogMessage ( self,  message )

Log a message.

  MakeButtonForCachedPopup 
MakeButtonForCachedPopup (
        self,
        label,
        html_text,
        request=None,
        window_width=480,
        window_height=240,
        )

Construct a button for displaying a cached popup page.

label
The button label.
html_text
The HTML source for the popup page.
window_width
The width, in pixels, of the popup window.
window_height
The height, in pixels, of the popup window.
returns
HTML source for the button. The button must be placed within a form element.
  MakeConfirmationDialog 
MakeConfirmationDialog (
        self,
        message,
        url,
        )

Generate JavaScript for a confirmation dialog box.

url
The location in the main browser window is set to the URL if the user confirms the action.

See make_popup_dialog_script for a description of function_name and message and information on how to use the return value.

  MakePopupDialog 
MakePopupDialog (
        self,
        message,
        buttons,
        title="",
        )

Generate JavaScript to show a popup dialog box.

The popup dialog box displays a message and one or more buttons. Each button can have a JavaScript statement (or statements) associated with it; if the button is clicked, the statement is invoked. After any button is clicked, the popup window is closed as well.

message
HTML source of the message to display in the popup window.
buttons
A sequence of button specifications. Each is a pair (caption, script). caption is the button caption. script is the JavaScript statement to invoke when the button is clicked, or None.
title
The popup window title.
returns
JavaScript statements to show the dialog box, suiteable for use as an event handler.
  ProcessScript 
ProcessScript ( self,  request )

Process request as a script.

request
A WebRequest object.
returns
The output of the script.
  RegisterPathTranslation 
RegisterPathTranslation (
        self,
        url_path,
        file_path,
        )

Register a path translation.

url_path
The path in URL-space to map from. URLs of which url_path is a prefix can be translated.
file_path
The file system path corresponding to url_path.

For example, if you register

web_server.RegisterPathTranslation(/images, /path/to/pictures)

the URL http://my.server.com/images/big/tree.gif will be mapped to the file path /path/to/pictures/big/tree.gif.

  RegisterScript 
RegisterScript (
        self,
        script_path,
        script,
        )

Register a dynamic URL.

script_path
The URL for this script. A request must match this path exactly.
script
A callable to invoke to generate the page content.

If you register

web_server.RegisterScript(/cgi-bin/myscript, make_page)

then the URL http://my.server.com/cgi-bin/myscript will respond with the output of calling make_page.

The script is passed a single argument, a WebRequest instance. It returns the HTML source, as a string, of the page it generates. If it returns a tuple instead, the first element is taken to be a MIME type and the second is the data.

The script may instead raise an HttpRedirect instance, indicating an HTTP redirect response should be sent to the client.

  RequestShutdown 
RequestShutdown ( self )

Shut the server down after processing the current request.

  Run 
Run ( self )

Start the web server.

preconditions
The server must be bound.
  TranslateRequest 
TranslateRequest ( self,  request )

Translate the URL in request to a file system path.

request
A WebRequest object.
returns
A path to the corresponding file, or None if the request URL didn't match any translations.
  _HandleProblems 
_HandleProblems ( self,  request )

Handle internal errors.

  _HandleRoot 
_HandleRoot ( self,  request )

Handle the / URL.

Exceptions   
HttpRedirect, WebRequest( "/static/index.html" )
  __GetPathForCachedPage 
__GetPathForCachedPage (
        self,
        request,
        session_id,
        )

Return the path for a cached page.

request
The URL requesting the page from the cache.
session_id
The session ID for the request, or None.
  __init__ 
__init__ (
        self,
        port,
        address="",
        log_file=sys.stderr,
        )

Create a new web server.

port
The port on which to accept connections. If port is 0, then any port will do.
address
The local address to which to bind. An empty string means bind to all local addresses.
log_file
A file object to which to write log messages. If it's None, no logging.

The server is not started until the Bind and Run methods are invoked.

  handle_error 
handle_error (
        self,
        request,
        client_address,
        )

Handle an error gracefully.


Table of Contents

This document was automatically generated on Mon Jan 3 09:42:29 2005 by HappyDoc version 2.1