Table of Contents

Module: web qm/web.py

Common code for implementing web user interfaces.

Functions   
__clean_up_expired_sessions
__replacement_for_entity
decode_properties
decode_set_control_contents
encode_properties
encode_set_control_contents
escape
format_color
format_exception
format_structured_text
generate_error_page
generate_login_form
get_session
handle_login
handle_logout
http_return_exception
http_return_html
javascript_escape
javascript_unescape
make_button_for_popup
make_button_for_request
make_button_for_url
make_choose_control
make_help_link
make_help_link_html
make_javascript_string
make_popup_page
make_properties_control
make_set_control
make_submit_button
make_url
parse_url_query
unescape
  __clean_up_expired_sessions 
__clean_up_expired_sessions ()

Remove any sessions that are expired.

  __replacement_for_entity 
__replacement_for_entity ( match )

A function that returns the replacement for an entity matched by the above expression.

  decode_properties 
decode_properties ( properties )

Decode a URL-encoded representation of a set of properties.

properties
A string containing URL-encoded properties.
returns
A map from names to values.

This function is the inverse of encode_properties.

  decode_set_control_contents 
decode_set_control_contents ( content_string )

Decode the contents of a set control.

content_string
The text of the form field containing the encoded set contents.
returns
A sequence of the values of the elements of the set.
  encode_properties 
encode_properties ( properties )

Construct a URL-encoded representation of a set of properties.

properties
A map from property names to values. Names must be URL-safe strings. Values are arbitrary strings.
returns
A URL-encoded string representation of properties.

This function is the inverse of decode_properties.

  encode_set_control_contents 
encode_set_control_contents ( values )

Encode values for a set control.

values
A sequence of values of elements of the set.
returns
The encoded value for the control field.
  escape 
escape ( text )

Escape special characters in text for formatting as HTML.

  format_color 
format_color (
        red,
        green,
        blue,
        )

Format an RGB color value for HTML.

red, green, blue
Color values for respective channels, between 0.0 and 1.0. Values outside this range are truncated to this range.
  format_exception 
format_exception ( exc_info )

Format an exception as HTML.

exc_info
A three-element tuple containing exception info, of the form (type, value, traceback).
returns
A string containing a complete HTML file displaying the exception.
  format_structured_text 
format_structured_text ( text )

Render text as HTML.

  generate_error_page 
generate_error_page ( request,  error_text )

Generate a page to indicate a user error.

request
The request that was being processed when the error was encountered.
error_text
A description of the error, as structured text.
returns
The generated HTML source for the page.
  generate_login_form 
generate_login_form ( redirect_request,  message=None )

Show a form for user login.

message
If not None, a message to display to the user.
  get_session 
get_session ( request,  session_id )

Retrieve the session corresponding to session_id.

request
A WebRequest object for which to get the session.
raises
InvalidSessionError if the session ID is invalid, or is invalid for this request.
Exceptions   
InvalidSessionError, qm.error( "session invalid" )
  handle_login 
handle_login ( request,  default_redirect_url="/" )

Handle a login request.

Authenticate the login using the user name and password stored in the _login_user_name and _login_password request fields, respectively.

If authentication succeeds, redirect to the URL stored in the _redirect_url request field by raising an HttpRedirect, passing all other request fields along as well.

If _redirect_url is not specified in the request, the value of default_redirect_url is used instead.

Exceptions   
HttpRedirect, redirect_request
  handle_logout 
handle_logout ( request,  default_redirect_url="/" )

Handle a logout request.

prerequisite
request must be in a valid session, which is ended.

After ending the session, redirect to the URL specified by the _redirect_url field of request. If _redirect_url is not specified in the request, the value of default_redirect_url is used instead.

Exceptions   
HttpRedirect, redirect_request
  http_return_exception 
http_return_exception ( exc_info=None,  stream=sys.stdout )

Generate an HTTP response for an exception.

exc_info
A three-element tuple containing exception info, of the form (type, value, traceback). If None, use the exception currently being handled.
stream
The stream to write the response, by default sys.stdout..
  http_return_html 
http_return_html ( html_text,  stream=sys.stdout )

Generate an HTTP response consisting of HTML text.

html_text
The HTML souce text to return.
stream
The stream to write the response, by default sys.stdout..
  javascript_escape 
javascript_escape ( text )

Equivalent to the JavaScript escape built-in function.

  javascript_unescape 
javascript_unescape ( text )

Equivalent to the JavaScript unescape built-in function.

  make_button_for_popup 
make_button_for_popup (
        label,
        url,
        window_width=480,
        window_height=240,
        )

Construct a button for displaying a popup page.

label
The button label.
url
The URL to display in the popup page.
returns
HTML source for the button. The button must be placed within a form element.
  make_button_for_request 
make_button_for_request (
        title,
        request,
        css_class=None,
        )

Generate HTML for a button.

Note that the caller is responsible for making sure the resulting button is placed within a form element.

title
The button label.
request
A WebRequest object to be invoked when the button is clicked.
css_class
The CSS class to use for the button, or None.
  make_button_for_url 
make_button_for_url (
        title,
        url,
        css_class=None,
        )

Generate HTML for a button.

Note that the caller is responsible for making sure the resulting button is placed within a form element.

title
The button label.
url
The URL to load when the button is clicked..
css_class
The CSS class to use for the button, or None.
  make_choose_control 
make_choose_control (
        field_name,
        included_label,
        included_items,
        excluded_label,
        excluded_items,
        item_to_text=str,
        item_to_value=str,
        ordered=0,
        )

Construct HTML controls for selecting a subset.

The user is presented with two list boxes next to each other. The box on the left lists items included in the subset. The box on the right lists items excluded from the subset but available for inclusion. Between the boxes are buttons for adding and removing items from the subset.

If ordered is true, buttons are also shown for reordering items in the included list.

field_name
The name of an HTML hidden form field that will contain an encoding of the items included in the subset. The encoding consists of the values corresponding to included items, in a comma-separated list.
included_label
HTML source for the label for the left box, which displays the included items.
included_items
Items initially included in the subset. This is a sequence of arbitrary objects or values.
excluded_label
HTML source for the label for the right box, which displays the items available for inclusion but not currently included.
excluded_items
Items not initially included but available for inclusion. This is a sequence of arbitrary objects or values.
item_to_text
A function that produces a user-visible text description of an item.
item_to_value
A function that produces a value for an item, used as the value for an HTML option object.
ordered
If true, additional controls are displayed to allow the user to manipulate the order of items in the included set.
returns
HTML source for the items. Must be placed in a form.
  make_help_link 
make_help_link (
        help_text_tag,
        label="Help",
        **substitutions,
        )

Make a link to pop up help text.

help_text_tag
A message tag for the help diagnostic.
label
The help link label.
substitutions
Substitutions to the help diagnostic.
  make_help_link_html 
make_help_link_html ( help_text,  label="Help" )

Make a link to pop up help text.

help_text
HTML source for the help text.
label
The help link label.
  make_javascript_string 
make_javascript_string ( text )

Return text represented as a JavaScript string literal.

  make_popup_page 
make_popup_page (
        message,
        buttons,
        title="",
        )

Generate a popup dialog box page.

See make_popup_dialog_script for an explanation of the parameters.

  make_properties_control 
make_properties_control (
        form_name,
        field_name,
        properties,
        select_name=None,
        )

Construct a control for representing a set of properties.

form_name
The name of form in which the control is included.
field_name
The name of the input control that contains an encoded representation of the properties. See encode_properties and decode_properties.
properties
A map from property names to values of the properties to include in the control initially.
select_name
The name of the select control that displays the elements of the set. If None, a control name is generated automatically.
  make_set_control 
make_set_control (
        form_name,
        field_name,
        add_page,
        select_name=None,
        initial_elements=[],
        request=None,
        rows=6,
        width=200,
        window_width=480,
        window_height=240,
        ordered=0,
        )

Construct a control for representing a set of items.

form_name
The name of form in which the control is included.
field_name
The name of the input control that contains an encoded representation of the set's elements. See encode_set_control_contents and decode_set_control_contents.
select_name
The name of the select control that displays the elements of the set. If None, a control name is generated automatically.
add_page
The URL for a popup web page that is displayed in response to the "Add..." button.
initial_elements
The initial elements of the set.
rows
The number of rows for the select control.
width
The width of the select control.
window_width, window_height
The width and height of the popup window for adding a new element.
ordered
If true, controls are included for specifying the order of elements in the set.
  make_submit_button 
make_submit_button ( title="OK" )

Generate HTML for a button to submit the current form.

title
The button title.
  make_url 
make_url (
        script_name,
        base_request=None,
        **fields,
        )

Create a request and return a URL for it.

script_name
The script name for the request.
base_request
If not None, the base request for the generated request.
fields
Additional fields to include in the request.
  parse_url_query 
parse_url_query ( url )

Parse a URL-encoded query.

This function parses query strings encoded in URLs, such as /script.cgi?key1=val1&key2=val2. For this example, it would return ("/script.cgi", {"key1" : "val1", "key2" : "val2"})

url
The URL to parse.
returns
A pair containing the the base script path and a mapping of query field names to values.
  unescape 
unescape ( text )

Undo escape by replacing entities with ordinary characters.

Classes   

AddressInUseError

CGIWebRequest

A WebRequest object initialized from the CGI environment.

DtmlPage

Base class for classes to generate web pages from DTML.

HTTPServer

Workaround for problems in BaseHTTPServer.HTTPServer.

HttpRedirect

Exception signalling an HTTP redirect response.

InvalidSessionError

NoSessionError

PrivilegedPortError

Session

A persistent user session.

WebRequest

An object representing a request from the web server.

WebRequestHandler

Handler for HTTP requests.

WebServer

A web server that serves ordinary files and dynamic content.


Table of Contents

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