Selectors - Components for Dispatching to Resources

The Selectors module provides classes (although currently only one class is supplied) which act as standard WebStack resources, but which attempt to "select" other resources, dispatch each request to those resources, and to cause various side-effects, mostly on the attributes stored on the transaction object. These "selector" classes behave those in the ResourceMap module, but aspire to be more generally applicable.

Selecting Path Roots with PathSelector

In non-trivial applications, it is often desirable to know the path or URL to a particular resource, especially the "root" resource under which the application or one of its components may reside. The PathSelector class can be instantiated and be made to refer to a resource, recording such path or URL details in an attribute for later inspection.

WebStack API - The PathSelector Class

The PathSelector class (found in the WebStack.Resources.Selectors module) wraps resource objects whose location (as indicated by a path or URL) should be recorded as an attribute on the current transaction. The most common use of the class is to record the "root" resource's location, and this would be done as follows:

def get_site_map():
return PathSelector(MyResource())

Here, the get_site_map function (as described in the "Deploying a WebStack Application" document) would provide a PathSelector object instead of an instance of the MyResource class. However, the side-effect of combining these two resources would be the availability of an attribute named root on the transaction object. Thus, the "root" MyResource object and, indeed, all resource objects visited after this side-effect has occurred will have access to the "root" path or URL information.

Further Reading

The API documentation for the PathSelector class provides additional information.

Defining Encodings using EncodingSelector

One frequently bothersome aspect of writing Web applications involves the processing and production of text in different encodings. Whilst the WebStack API lets applications explicitly state the character encoding for various operations, one often wants to be able to ignore such details since they start to clutter up application code. The EncodingSelector class offers a basic solution which is compatible with the mechanisms in transaction objects: by wrapping WebStack resources with instances of EncodingSelector, an application-wide default encoding (or character set) will be defined; this will result in request information being processed according to the stated encoding and response information being produced according to that encoding (see below for more details of the latter activity).

WebStack API - The EncodingSelector Class

The EncodingSelector class (found in the WebStack.Resources.Selectors module) wraps resource objects whilst changing the default encoding of the current transaction object. The class can be applied like this:

def get_site_map():
return EncodingSelector(MyResource(), "utf-8")

Here, the get_site_map function (as described in the "Deploying a WebStack Application" document) would provide a EncodingSelector object instead of an instance of the MyResource class. However, the EncodingSelector will forward requests on to MyResource (since it "selects" that resource), whilst setting the default encoding to be "utf-8".

Request Streams and Encodings

Although a default encoding affects the processing of request parameters, direct access to the request stream using the get_request_stream method will only produce plain strings. This behaviour is justified by the observation that, if conversion from an encoding to Unicode were to take place, the resulting character values may be unsuitable substitutes for the original byte values in applications intending to make use of the raw incoming (possibly binary) data. A recipe for making a Unicode stream is provided in the "Character Encodings" document.

Response Encodings and Content Types

Although EncodingSelector sets a default encoding, responses will generally be written in that encoding, at least if textual data is written to the response stream as Unicode objects. However, the content type must typically be set either to match the encoding in use or to not specify an encoding. It may become necessary to find out what the response stream encoding is when creating a ContentType object. For this and other purposes, the get_response_stream_encoding method is available on the transaction object:

from WebStack.Generic import ContentType

def respond(self, trans):

# Some code...

trans.set_content_type(ContentType("text/html", trans.get_response_stream_encoding()))
out = trans.get_response_stream()
out.write(some_unicode_object)

However, it is completely acceptable to omit the encoding information where a default encoding has been set:

    trans.set_content_type(ContentType("text/html")) # no encoding/charset specified

Reading the Default Directly

For some activities, such as making a Unicode stream from the request stream, it is desirable to find out the encoding set by the selector. This information is made available on transaction objects as the default_charset attribute.

Further Reading

The API documentation for the EncodingSelector class provides additional information, along with the "Responses and Presentation" document.