# HG changeset patch # User paulb # Date 1125006347 0 # Node ID 333874e30b6b5b2c420c2f008afa0db6de7ca590 # Parent 6ff28190079e74e583690cab1d18672a4ac5a56a [project @ 2005-08-25 21:45:47 by paulb] Flattened the document structure slightly. Added details of encoding parameters for path information, together with some examples and explanations. diff -r 6ff28190079e -r 333874e30b6b docs/design.html --- a/docs/design.html Thu Aug 25 21:44:47 2005 +0000 +++ b/docs/design.html Thu Aug 25 21:45:47 2005 +0000 @@ -1,12 +1,10 @@ - - + - Application Design Considerations - - - + + Application Design Considerations + +

Application Design Considerations

When writing an application, we @@ -26,22 +24,21 @@ transaction object effectively tells us what it is the user wants to do; it does so through a number of different pieces of information including the request method, headers, parameters, cookies and sessions.

WebStack API - The Transaction Object

The transaction object appears as the first parameter in a resource's respond method:

class SomeResource:
    def respond(self, trans):
        [Here is where the code for the resource is written.]

For full information about transaction objects, see the API -documentation for the WebStack.Generic.Transaction -class.

+ +

class MyResource:
    def respond(self, trans):
        [Here is where the code for the resource is written.]

Within this activity, certain topics are of interest:

For full information about transaction objects, see the API +documentation for the WebStack.Generic.Transaction +class.

Perform Actions

Of all activities summarised above, this is the most vague because the kinds of actions performed by applications will vary substantially @@ -63,5 +60,4 @@

Cookies, Sessions, Users and Persistent Information

- - + \ No newline at end of file diff -r 6ff28190079e -r 333874e30b6b docs/developing.html --- a/docs/developing.html Thu Aug 25 21:44:47 2005 +0000 +++ b/docs/developing.html Thu Aug 25 21:45:47 2005 +0000 @@ -5,7 +5,6 @@ Developing a WebStack Application -

Developing a WebStack Application

Many different topics are involved in the development of WebStack @@ -13,39 +12,66 @@ documentation:

Applications and Resources

How Resources are Created
Application Design Considerations

URLs and Paths

Paths To and Within Applications
Path Design and Interpretation

Path Info Support in Server Environments

Request Methods
Request Parameters and Uploads

Request headers
Request bodies

Responses and Presentation
Cookies, Sessions, Users and Persistent Information

Cookies
Sessions and Persistent Information

Path Info Support in Server Environments

Request Methods
Request Parameters and Uploads

Request headers
Request bodies

Responses and Presentation
Cookies, Sessions, Users and Persistent Information

Cookies
Sessions and Persistent Information

Using Sessions
Server Environment Support for Sessions

Users and Authentication

Users and Authentication

The following topic is referenced in many locations and should diff -r 6ff28190079e -r 333874e30b6b docs/paths.html --- a/docs/paths.html Thu Aug 25 21:44:47 2005 +0000 +++ b/docs/paths.html Thu Aug 25 21:45:47 2005 +0000 @@ -3,7 +3,6 @@ URLs and Paths -

URLs and Paths

The URL at which your application shall appear is arguably the first @@ -54,13 +53,31 @@

This gets the entire path of a resource including parameter information (as described in "Request Parameters and Uploads").
-An optional encoding parameter may be used to assist the process of converting the path to a Unicode object - see "Character Encodings" for more information.

encoding

get_path_without_query

This gets the entire path of a resource but without any parameter -information.

encoding

To obtain the above path using the WebStack API, we can write the following code:

path = trans.get_path()

Really, however, we should explicitly state the character encoding of the path. Unfortunately, as noted in "Character Encodings", +some guesswork is required, but if we have decided to use UTF-8 as the +encoding of our output, it is reasonable to specify UTF-8 here as well:

path = trans.get_path("utf-8")
path = trans.get_path(self.encoding) # assuming a class/instance attribute defining such things centrally

In many applications such nuances are not particularly important, but consider the following URL:

http://www.boddie.org.uk/python/WebStack-%E6%F8%E5.html

Here, the URL includes non-ASCII characters which must be +interpreted somehow. In this case, the "URL encoded" character values +refer to ISO-8859-1 values and can be safely inspected as follows:

path = trans.get_path("iso-8859-1")

The above usage of UTF-8 will also work in this case, but only +because WebStack will use ISO-8859-1 as a "safe" default for character +values it does not understand.

Query Strings

Sometimes, a "query string" will be provided as part of a URL; for example:

http://www.boddie.org.uk/application?param1=value1

"Request Parameters and Uploads"

WebStack API - Getting Query Strings

WebStack provides a method to get only the query string from the URL:

get_query_string: This method returns the part of the URL which contains parameter +information. Such information will be "URL encoded", meaning that +certain characters will have the form %xx where xx +is a two digit hexadecimal number referring to the byte value of the +unencoded character - see below for discussion of this.

Note that unlike the path access methods, get_query_string +does not accept an encoding as a parameter. Moreover, when retrieving a +path including a query string, the encoding is not used to interpret +"URL encoded" character values in the query string itself. Consider +this example URL:

http://www.boddie.org.uk/application-%E6?var%F8=value%E5

Upon requesting the path and the query string, certain differences should be noticeable:

trans.get_path("iso-8859-1")               # returns /application-æ?var%F8=value%E5
trans.get_path_without_query("iso-8859-1") # returns /application-æ
trans.get_query_string()                   # returns var%F8=value%E5

One reason for this seemingly arbitrary distinction in treatment is +the way certain servers present path information to WebStack - often +the "URL encoded" information has been replaced by raw character values +which must then be converted to Unicode characters. In contrast, most +servers do not perform the same automatic conversion on the query +string.

In fact, it may become impossible to properly interpret the query +string if it is decoded prematurely; consider this example URL:

http://www.boddie.org.uk/application?a=%26b

If we were to just decode the query string and then extract the +parameters/fields, the result would be two empty parameters with the +names a and b, as opposed to the correct interpretation of the query string as describing a single parameter a with the value &b.

Conclusion

Regardless of all this, all inspection of path parameters should be done using the appropriate methods (see "Request Parameters and +Uploads"), +and direct access to the query string should only occur in situations +of a specialised nature such as the building of URLs for output.

More About Paths

Paths To and Within Applications

Applications and Resources

You should now be able to visit http://localhost:8080 in your browser and see the message printed by your application:

Hello world.

About Resources

Hello world.