Package WebStack :: Module Generic :: Class Transaction
[show private | hide private]
[frames | no frames]

Class Transaction


A generic transaction interface containing framework-specific methods to be
overridden.

Method Summary
  commit(self)
A special method, synchronising the transaction with framework-specific objects.
  convert_to_list(self, value)
Returns a single element list containing 'value' if it is not itself a list, a tuple, or None.
  decode_cookie_value(self, value)
Decode the given cookie 'value'.
  decode_path(self, path, encoding)
From the given 'path', use the optional 'encoding' (if specified) to decode the information and convert it to Unicode.
  delete_cookie(self, cookie_name)
Adds to the response a request that the cookie with the given 'cookie_name' be deleted/discarded by the client.
  encode_cookie_value(self, value)
Encode the given cookie 'value'.
  encode_path(self, path, encoding)
Encode the given 'path', using the optional 'encoding' (if specified) or the default encoding where 'encoding' is not specified, and produce a suitable "URL encoded" string.
  expire_session(self)
Expires any session established according to information provided in the transaction.
  format_header_value(self, value)
Format the given header 'value'.
  get_attributes(self)
An application-specific method which obtains a dictionary mapping names to attribute values that can be used to store arbitrary information.
  get_content_charsets(self)
Returns the character set preferences.
  get_content_languages(self)
Returns extracted language information from the transaction.
  get_content_type(self)
Returns the content type specified on the request, along with the charset employed.
  get_cookie(self, cookie_name)
Obtains cookie information from the request.
  get_cookies(self)
Obtains cookie information from the request.
  get_fields(self, encoding)
Extracts fields (or request parameters) from both the path specified in the transaction as well as the message body.
  get_fields_from_body(self, encoding)
Extracts fields (or request parameters) from the message body in the transaction.
  get_fields_from_path(self, encoding)
Extracts fields (or request parameters) from the path specified in the transaction.
  get_header_values(self, key)
Returns a list of all request header values associated with the given 'key'.
  get_headers(self)
Returns all request headers as a dictionary-like object mapping header names to values.
  get_path(self, encoding)
Returns the entire path from the request as a Unicode object.
  get_path_info(self, encoding)
Returns the "path info" (the part of the URL after the resource name handling the current request) from the request as a Unicode object containing genuine characters (as opposed to "URL encoded" character values).
  get_path_without_info(self, encoding)
Returns the entire path from the request minus the query string and the "path info" as a Unicode object containing genuine characters (as opposed to "URL encoded" character values).
  get_path_without_query(self, encoding)
Returns the entire path from the request minus the query string as a Unicode object containing genuine characters (as opposed to "URL encoded" character values).
  get_processed_virtual_path_info(self, encoding)
An application-specific method which returns the virtual path info that is considered "processed"; that is, the part of the path info which is not included in the virtual path info.
  get_query_string(self)
Returns the query string from the path in the request.
  get_request_method(self)
Returns the request method.
  get_request_stream(self)
Returns the request stream for the transaction.
  get_response_code(self)
Get the response code associated with the transaction.
  get_response_stream(self)
Returns the response stream for the transaction.
  get_response_stream_encoding(self)
Returns the response stream encoding.
  get_server_name(self)
Returns the server name.
  get_server_port(self)
Returns the server port as a string.
  get_session(self, create)
Gets a session corresponding to an identifier supplied in the transaction.
  get_user(self)
Extracts user information from the transaction.
  get_virtual_path_info(self, encoding)
An application-specific method which either returns path info set in the 'set_virtual_path_info' method, or the normal path info found in the request.
  parse_content_preferences(self, accept_preference)
Returns the preferences as requested by the user agent.
  parse_content_type(self, content_type_field)
Parse the given 'content_type_field' - a value found comparable to that found in an HTTP request header for "Content-Type".
  parse_header_value(self, header_class, header_value_str)
Create an object of the given 'header_class' by determining the details of the given 'header_value_str' - a string containing the value of a particular header.
  process_cookies(self, cookie_dict, using_strings)
Process the given 'cookie_dict', returning a dictionary mapping cookie names to cookie objects where the names and values have been decoded from the form used in the cookies retrieved from the request.
  redirect(self, path, code)
Send a redirect response to the client, providing the given 'path' as the suggested location of a resource.
  rollback(self)
A special method, partially synchronising the transaction with framework-specific objects, but discarding previously emitted content that is to be replaced by an error message.
  set_content_type(self, content_type)
Sets the 'content_type' for the response.
  set_cookie(self, cookie)
Stores the given 'cookie' object in the response.
  set_cookie_value(self, name, value, path, expires)
Stores a cookie with the given 'name' and 'value' in the response.
  set_header_value(self, header, value)
Set the HTTP 'header' with the given 'value'.
  set_response_code(self, response_code)
Set the 'response_code' using a numeric constant defined in the HTTP specification.
  set_user(self, username)
An application-specific method which sets the user information with 'username' in the transaction.
  set_virtual_path_info(self, path_info)
An application-specific method which sets the 'path_info' in the transaction.
  traverse_path(self, encoding)
Traverse the path, updating the virtual path info and thus the processed virtual path info accordingly.
  update_path(self, path, relative_path)
Transform the given 'path' using the specified 'relative_path'.

Class Variable Summary
str default_charset = 'iso-8859-1'
NoneType path_info = None                                                                  
NoneType user = None                                                                  

Method Details

commit(self)

A special method, synchronising the transaction with framework-specific
objects.

convert_to_list(self, value)

Returns a single element list containing 'value' if it is not itself a list, a
tuple, or None. If 'value' is a list then it is itself returned; if 'value' is a
tuple then a new list containing the same elements is returned; if 'value' is None
then an empty list is returned.

decode_cookie_value(self, value)

Decode the given cookie 'value'.

decode_path(self, path, encoding=None)

From the given 'path', use the optional 'encoding' (if specified) to decode the
information and convert it to Unicode. Upon failure for a specified 'encoding'
or where 'encoding' is not specified, use the default character encoding to
perform the conversion.

Returns the 'path' as a Unicode value without "URL encoded" character values.

delete_cookie(self, cookie_name)

Adds to the response a request that the cookie with the given
'cookie_name' be deleted/discarded by the client.

encode_cookie_value(self, value)

Encode the given cookie 'value'. This ensures the usage of US-ASCII
through the encoding of Unicode objects as URL-encoded UTF-8 text.

encode_path(self, path, encoding=None)

Encode the given 'path', using the optional 'encoding' (if specified) or the
default encoding where 'encoding' is not specified, and produce a suitable "URL
encoded" string.

expire_session(self)

Expires any session established according to information provided in the
transaction.

format_header_value(self, value)

Format the given header 'value'. Typically, this just ensures the usage
of US-ASCII.

get_attributes(self)

An application-specific method which obtains a dictionary mapping names
to attribute values that can be used to store arbitrary information.

Since the dictionary of attributes is retained by the transaction during
its lifetime, such a dictionary can be used to store information that an
application wishes to communicate amongst its components and resources
without having to pass objects other than the transaction between them.

The returned dictionary can be modified using normal dictionary-like
methods. If no attributes existed previously, a new dictionary is
created and associated with the transaction.

get_content_charsets(self)

Returns the character set preferences.

get_content_languages(self)

Returns extracted language information from the transaction.

get_content_type(self)

Returns the content type specified on the request, along with the
charset employed.

get_cookie(self, cookie_name)

Obtains cookie information from the request.

Returns a cookie object for the given 'cookie_name' or None if no such
cookie exists.

get_cookies(self)

Obtains cookie information from the request.

Returns a dictionary mapping cookie names to cookie objects.

get_fields(self, encoding=None)

Extracts fields (or request parameters) from both the path specified in
the transaction as well as the message body. The optional 'encoding'
parameter specifies the character encoding of the message body for cases
where no such information is available, but where the default encoding
is to be overridden.

Returns a dictionary mapping field names to lists of values (even if a
single value is associated with any given field name). Each value is
either a Unicode object (representing a simple form field, for example)
or a WebStack.Helpers.Request.FileContent object (representing a file
upload form field).

Where a given field name is used in both the path and message body to
specify values, the values from both sources will be combined into a
single list associated with that field name.

get_fields_from_body(self, encoding=None)

Extracts fields (or request parameters) from the message body in the
transaction. The optional 'encoding' parameter specifies the character
encoding of the message body for cases where no such information is
available, but where the default encoding is to be overridden.

Returns a dictionary mapping field names to lists of values (even if a
single value is associated with any given field name). Each value is
either a Unicode object (representing a simple form field, for example)
or a WebStack.Helpers.Request.FileContent object (representing a file
upload form field).

get_fields_from_path(self, encoding=None)

Extracts fields (or request parameters) from the path specified in the
transaction. The underlying framework may refuse to supply fields from
the path if handling a POST transaction. The optional 'encoding'
parameter specifies the character encoding of the query string for cases
where the default encoding is to be overridden.

Returns a dictionary mapping field names to lists of values (even if a
single value is associated with any given field name).

get_header_values(self, key)

Returns a list of all request header values associated with the given
'key'. Note that according to RFC 2616, 'key' is treated as a
case-insensitive string.

get_headers(self)

Returns all request headers as a dictionary-like object mapping header
names to values.

get_path(self, encoding=None)

Returns the entire path from the request as a Unicode object. Any "URL
encoded" character values in the part of the path before the query
string will be decoded and presented as genuine characters; the query
string will remain "URL encoded", however.

If the optional 'encoding' is set, use that in preference to the default
encoding to convert the path into a form not containing "URL encoded"
character values.

get_path_info(self, encoding=None)

Returns the "path info" (the part of the URL after the resource name
handling the current request) from the request as a Unicode object
containing genuine characters (as opposed to "URL encoded" character
values).

If the optional 'encoding' is set, use that in preference to the default
encoding to convert the path into a form not containing "URL encoded"
character values.

get_path_without_info(self, encoding=None)

Returns the entire path from the request minus the query string and the
"path info" as a Unicode object containing genuine characters (as
opposed to "URL encoded" character values).

If the optional 'encoding' is set, use that in preference to the default
encoding to convert the path into a form not containing "URL encoded"
character values.

get_path_without_query(self, encoding=None)

Returns the entire path from the request minus the query string as a
Unicode object containing genuine characters (as opposed to "URL
encoded" character values).

If the optional 'encoding' is set, use that in preference to the default
encoding to convert the path into a form not containing "URL encoded"
character values.

get_processed_virtual_path_info(self, encoding=None)

An application-specific method which returns the virtual path info that
is considered "processed"; that is, the part of the path info which is
not included in the virtual path info.

If the optional 'encoding' is set, use that in preference to the default
encoding to convert the path into a form not containing "URL encoded"
character values.

Where the virtual path info is identical to the path info, an empty
string is returned.

Where the virtual path info is a substring of the path info, the path
info preceding that substring is returned.

Where the virtual path info is either an empty string or not a substring
of the path info, the entire path info is returned.

Generally, one should expect the following relationship between the path
info, virtual path info and processed virtual path info:

path info == processed virtual path info + virtual path info

get_query_string(self)

Returns the query string from the path in the request.

get_request_method(self)

Returns the request method.

get_request_stream(self)

Returns the request stream for the transaction.

get_response_code(self)

Get the response code associated with the transaction. If no response
code is defined, None is returned.

get_response_stream(self)

Returns the response stream for the transaction.

get_response_stream_encoding(self)

Returns the response stream encoding.

get_server_name(self)

Returns the server name.

get_server_port(self)

Returns the server port as a string.

get_session(self, create=1)

Gets a session corresponding to an identifier supplied in the
transaction.

If no session has yet been established according to information
provided in the transaction then the optional 'create' parameter
determines whether a new session will be established.

Where no session has been established and where 'create' is set to 0
then None is returned. In all other cases, a session object is created
(where appropriate) and returned.

get_user(self)

Extracts user information from the transaction.

Returns a username as a string or None if no user is defined.

get_virtual_path_info(self, encoding=None)

An application-specific method which either returns path info set in the
'set_virtual_path_info' method, or the normal path info found in the
request.

If the optional 'encoding' is set, use that in preference to the default
encoding to convert the path into a form not containing "URL encoded"
character values.

parse_content_preferences(self, accept_preference)

Returns the preferences as requested by the user agent. The preferences are
returned as a list of codes in the same order as they appeared in the
appropriate environment variable. In other words, the explicit weighting
criteria are ignored.

As the 'accept_preference' parameter, values for language and charset
preferences are appropriate.

parse_content_type(self, content_type_field)

Parse the given 'content_type_field' - a value found comparable to that
found in an HTTP request header for "Content-Type".

parse_header_value(self, header_class, header_value_str)

Create an object of the given 'header_class' by determining the details
of the given 'header_value_str' - a string containing the value of a
particular header.

process_cookies(self, cookie_dict, using_strings=0)

Process the given 'cookie_dict', returning a dictionary mapping cookie names
to cookie objects where the names and values have been decoded from the form
used in the cookies retrieved from the request.

The optional 'using_strings', if set to 1, treats the 'cookie_dict' as a
mapping of cookie names to values.

redirect(self, path, code=302)

Send a redirect response to the client, providing the given 'path' as
the suggested location of a resource. The optional 'code' (set to 302 by
default) may be used to change the exact meaning of the response
according to the HTTP specifications.

Note that 'path' should be a plain string suitable for header output.
Use the 'encode_path' method to convert Unicode objects into such
strings.

rollback(self)

A special method, partially synchronising the transaction with
framework-specific objects, but discarding previously emitted content
that is to be replaced by an error message.

set_content_type(self, content_type)

Sets the 'content_type' for the response.

set_cookie(self, cookie)

Stores the given 'cookie' object in the response.

set_cookie_value(self, name, value, path=None, expires=None)

Stores a cookie with the given 'name' and 'value' in the response.

The optional 'path' is a string which specifies the scope of the cookie,
and the optional 'expires' parameter is a value compatible with the
time.time function, and indicates the expiry date/time of the cookie.

set_header_value(self, header, value)

Set the HTTP 'header' with the given 'value'.

set_response_code(self, response_code)

Set the 'response_code' using a numeric constant defined in the HTTP
specification.

set_user(self, username)

An application-specific method which sets the user information with
'username' in the transaction. This affects subsequent calls to
'get_user'.

set_virtual_path_info(self, path_info)

An application-specific method which sets the 'path_info' in the
transaction. This affects subsequent calls to 'get_virtual_path_info'.

Note that the virtual path info should either be an empty string, or it
should begin with "/" and then (optionally) include other details.
Virtual path info strings which omit the leading "/" - ie. containing
things like "xxx" or even "xxx/yyy" - do not really make sense and may
not be handled correctly by various WebStack components.

traverse_path(self, encoding=None)

Traverse the path, updating the virtual path info and thus the processed
virtual path info accordingly. Return the traversed virtual path info
fragment.

update_path(self, path, relative_path)

Transform the given 'path' using the specified 'relative_path'. For
example, a simple identifier replaces the last component from 'path':

trans.update_path("/parent/node", "other") -> "/parent/other"

If the last component is empty, the effect is similar to an append
operation:

trans.update_path("/parent/node/", "other") -> "/parent/node/other"

Where 'relative_path' is empty, the result is 'path' with the last
component erased (but still present):

trans.update_path("/parent/node", "") -> "/parent/"

trans.update_path("/parent/node/", "") -> "/parent/node/"

Where 'relative_path' contains ".", the component is regarded as being
empty:

trans.update_path("/parent/node", "other/./more") -> "/parent/other/more"

trans.update_path("/parent/node/", "other/./more") -> "/parent/node/other/more"

However, at the start of 'relative_path', "." can remove one component:

trans.update_path("/parent/node", ".") -> "/parent"

trans.update_path("/parent/node/", ".") -> "/parent/node"

Adding "/" immediately afterwards restores any removed "/":

trans.update_path("/parent/node/", "./") -> "/parent/node/"

trans.update_path("/parent/node", "./") -> "/parent/"

Following components add to the effect of "./":

trans.update_path("/parent/node", "./other/more") -> "/parent/other/more"

trans.update_path("/parent/node/", "./other/more") -> "/parent/node/other/more"

Where 'relative_path' contains "..", two components are removed from the
resulting path:

trans.update_path("/parent/node/", "..") -> "/parent"

trans.update_path("/parent/node/", "../other") -> "/parent/other"

trans.update_path("/parent/node", "..") -> "/"

trans.update_path("/parent/node", "../other") -> "/other"

Where fewer components exist than are to be removed, the path is reset:

trans.update_path("/parent/node", "../..") -> "/"

Subsequent components are applied to the reset path:

trans.update_path("/parent/node", "../../other") -> "/other"

trans.update_path("/parent/node/", "../../other") -> "/other"

Where 'relative_path' begins with "/", the 'path' is reset to "/" and
the components of the 'relative_path' are then applied to that new path:

trans.update_path("/parent/node", "/other") -> "/other"

Where 'relative_path' ends with "/", the final "/" is added to the
result:

trans.update_path("/parent/node", "other/") -> "/parent/other/"

Class Variable Details

default_charset

Type:
str
Value:
'iso-8859-1'                                                           

path_info

Type:
NoneType
Value:
None                                                                  

user

Type:
NoneType
Value:
None                                                                  

Generated by Epydoc 2.1 on Thu Mar 1 00:37:14 2007 http://epydoc.sf.net