Package qm :: Module web :: Class WebServer
[hide private]
[frames] | no frames]

Class WebServer
source code

             BaseServer --+            
                          |            
     SocketServer.TCPServer --+        
                              |        
      BaseHTTPServer.HTTPServer --+    
                                  |    
                         HTTPServer --+
                                      |
                                     WebServer
Known Subclasses:
test.web.web.QMTestServer

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.



Instance Methods [hide private]
  Bind(self)
Bind the server to the specified address and port.
  CachePage(self, page_text, session_id=None)
Cache an HTML page.
  GetCachedPage(self, request, session_id=None)
Retrieve a page from the page cache.
  GetServerAddress(self)
Return the host address on which this server is running.
  GetTemporaryAttachmentStore(self)
Return the 'AttachmentStore' used for new 'Attachment's.
  HandleNoSessionError(self, request, message)
Handler when session is absent.
  IsScript(self, request)
Return a true value if 'request' corresponds to a script.
  LogMessage(self, message)
Log a message.
  MakeButtonForCachedPopup(self, label, html_text, request=None, window_width=480, window_height=240)
Construct a button for displaying a cached popup page.
  MakeConfirmationDialog(self, message, url)
Generate JavaScript for a confirmation dialog box.
  MakePopupDialog(self, message, buttons, title="")
Generate JavaScript to show a popup dialog box.
  ProcessScript(self, request)
Process 'request' as a script.
  RegisterPathTranslation(self, url_path, file_path)
Register a path translation.
  RegisterScript(self, script_path, script)
Register a dynamic URL.
  RequestShutdown(self)
Shut the server down after processing the current request.
  Run(self)
Start the web server.
  TranslateRequest(self, request)
Translate the URL in 'request' to a file system path.
  _HandleProblems(self, request)
Handle internal errors.
  _HandleRoot(self, request)
Handle the '/' URL.
  __GetPathForCachedPage(self, request, session_id)
Return the path for a cached page.
  __init__(self, port, address="", log_file=sys.stderr)
Create a new web server.
  handle_error(self, request, client_address)
Handle an error gracefully.

Inherited from HTTPServer: server_bind

Inherited from SocketServer.TCPServer: close_request, fileno, get_request, server_activate, server_close

Inherited from SocketServer.BaseServer: finish_request, handle_request, process_request, serve_forever, verify_request


Class Variables [hide private]

Inherited from BaseHTTPServer.HTTPServer: allow_reuse_address

Inherited from SocketServer.TCPServer: address_family, request_queue_size, socket_type


Method Details [hide private]

Bind(self)

source code 

Bind the server to the specified address and port.

Does not start serving.

CachePage(self, page_text, session_id=None)

source code 

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(self, request, session_id=None)

source code 

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(self)

source code 

Return the host address on which this server is running.

returns -- A pair '(hostname, port)'.

GetTemporaryAttachmentStore(self)

source code 

Return the 'AttachmentStore' used for new 'Attachment's.

returns -- The 'AttachmentStore' used for new 'Attachment's.

HandleNoSessionError(self, request, message)

source code 
Handler when session is absent.

IsScript(self, request)

source code 
Return a true value if 'request' corresponds to a script.

LogMessage(self, message)

source code 
Log a message.

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

source code 

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(self, message, url)

source code 

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(self, message, buttons, title="")

source code 

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(self, request)

source code 

Process 'request' as a script.

'request' -- A 'WebRequest' object.

returns -- The output of the script.

RegisterPathTranslation(self, url_path, file_path)

source code 
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(self, script_path, script)

source code 
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(self)

source code 
Shut the server down after processing the current request.

Run(self)

source code 

Start the web server.

preconditions -- The server must be bound.

TranslateRequest(self, request)

source code 

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(self, request)

source code 
Handle internal errors.

_HandleRoot(self, request)

source code 
Handle the '/' URL.

__GetPathForCachedPage(self, request, session_id)

source code 

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__(self, port, address="", log_file=sys.stderr)
(Constructor)

source code 

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.
Overrides: SocketServer.TCPServer.__init__

handle_error(self, request, client_address)

source code 
Handle an error gracefully.
Overrides: SocketServer.BaseServer.handle_error