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

Module web
source code

Common code for implementing web user interfaces.

Classes [hide private]
AddressInUseError  
CGIWebRequest A 'WebRequest' object initialized from the CGI environment.
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.

Functions [hide private]
  __clean_up_expired_sessions()
Remove any sessions that are expired.
  __replacement_for_entity(match)
  decode_properties(properties)
Decode a URL-encoded representation of a set of properties.
  decode_set_control_contents(content_string)
Decode the contents of a set control.
  encode_properties(properties)
Construct a URL-encoded representation of a set of properties.
  encode_set_control_contents(values)
Encode 'values' for a set control.
  escape(text)
Escape special characters in 'text' for formatting as HTML.
  format_color(red, green, blue)
Format an RGB color value for HTML.
  format_exception(exc_info)
Format an exception as HTML.
  format_structured_text(text)
Render 'text' as HTML.
  generate_error_page(request, error_text)
Generate a page to indicate a user error.
  generate_login_form(redirect_request, message=None)
Show a form for user login.
  get_session(request, session_id)
Retrieve the session corresponding to 'session_id'.
  handle_login(request, default_redirect_url="/")
Handle a login request.
  handle_logout(request, default_redirect_url="/")
Handle a logout request.
  http_return_exception(exc_info=None, stream=sys.stdout)
Generate an HTTP response for an exception.
  http_return_html(html_text, stream=sys.stdout)
Generate an HTTP response consisting of HTML text.
  javascript_escape(text)
Equivalent to the JavaScript 'escape' built-in function.
  javascript_unescape(text)
Equivalent to the JavaScript 'unescape' built-in function.
  make_button_for_popup(label, url, window_width=480, window_height=240)
Construct a button for displaying a popup page.
  make_button_for_request(title, request, css_class=None)
Generate HTML for a button.
  make_button_for_url(title, url, css_class=None)
Generate HTML for a button.
  make_choose_control(field_name, included_label, included_items, excluded_label, excluded_items, item_to_text=<type 'str'>, item_to_value=<type 'str'>, ordered=0)
Construct HTML controls for selecting a subset.
  make_help_link(help_text_tag, label="Help", **substitutions)
Make a link to pop up help text.
  make_help_link_html(help_text, label="Help")
Make a link to pop up help text.
  make_javascript_string(text)
Return 'text' represented as a JavaScript string literal.
  make_popup_page(message, buttons, title="")
Generate a popup dialog box page.
  make_properties_control(form_name, field_name, properties, select_name=None)
Construct a control for representing a set of properties.
  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.
  make_submit_button(title="OK")
Generate HTML for a button to submit the current form.
  make_url(script_name, base_request=None, **fields)
Create a request and return a URL for it.
  parse_url_query(url)
Parse a URL-encoded query.
  unescape(text)
Undo 'escape' by replacing entities with ordinary characters.

Variables [hide private]
__entity_regex  
_counter A counter for generating somewhat-unique names.
_page_cache_name The URL prefix for the global page cache.
_session_cache_name The URL prefix for the session page cache.
session_id_field The name of the form field used to store the session ID.
sessions A mapping from session IDs to 'Session' instances.

Function Details [hide private]

__clean_up_expired_sessions()

source code 
Remove any sessions that are expired.

__replacement_for_entity(match)

source code 

decode_properties(properties)

source code 

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

source code 

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

source code 

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

source code 

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

source code 
Escape special characters in 'text' for formatting as HTML.

format_color(red, green, blue)

source code 

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

source code 

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

source code 
Render 'text' as HTML.

generate_error_page(request, error_text)

source code 

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(redirect_request, message=None)

source code 

Show a form for user login.

'message' -- If not 'None', a message to display to the user.

get_session(request, session_id)

source code 

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'.

handle_login(request, default_redirect_url="/")

source code 

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.

handle_logout(request, default_redirect_url="/")

source code 

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.

http_return_exception(exc_info=None, stream=sys.stdout)

source code 

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(html_text, stream=sys.stdout)

source code 

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

source code 
Equivalent to the JavaScript 'escape' built-in function.

javascript_unescape(text)

source code 
Equivalent to the JavaScript 'unescape' built-in function.

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

source code 

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(title, request, css_class=None)

source code 

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(title, url, css_class=None)

source code 

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(field_name, included_label, included_items, excluded_label, excluded_items, item_to_text=<type 'str'>, item_to_value=<type 'str'>, ordered=0)

source code 

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(help_text_tag, label="Help", **substitutions)

source code 

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(help_text, label="Help")

source code 

Make a link to pop up help text.

'help_text' -- HTML source for the help text.

'label' -- The help link label.

make_javascript_string(text)

source code 
Return 'text' represented as a JavaScript string literal.

make_popup_page(message, buttons, title="")

source code 

Generate a popup dialog box page.

See 'make_popup_dialog_script' for an explanation of the parameters.

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

source code 

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

source code 

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(title="OK")

source code 

Generate HTML for a button to submit the current form.

'title' -- The button title.

make_url(script_name, base_request=None, **fields)

source code 

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

source code 

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

source code 
Undo 'escape' by replacing entities with ordinary characters.

Variables Details [hide private]

__entity_regex

Value:
&(\w+);                                                                
      

_counter

A counter for generating somewhat-unique names.
Value:
0                                                                     
      

_page_cache_name

The URL prefix for the global page cache.
Value:
'page-cache'                                                           
      

_session_cache_name

The URL prefix for the session page cache.
Value:
'session-cache'                                                        
      

session_id_field

The name of the form field used to store the session ID.
Value:
'session'                                                              
      

sessions

A mapping from session IDs to 'Session' instances.
Value:
{}