# HG changeset patch # User paulb # Date 1113167485 0 # Node ID 441c6bf6ad7d6feb0562326dd39be89a8e801c61 # Parent d0112e8a1847a73cb28cf189727ef6d3d88a7862 [project @ 2005-04-10 21:11:25 by paulb] Added links to more unwritten documents. Added information about query strings, request methods, request parameters and character encodings. diff -r d0112e8a1847 -r 441c6bf6ad7d docs/anatomy.html --- a/docs/anatomy.html Sat Apr 09 23:50:49 2005 +0000 +++ b/docs/anatomy.html Sun Apr 10 21:11:25 2005 +0000 @@ -1,6 +1,6 @@ + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
WebStack tries to let applications work with Unicode as much as possible, +but there are two places where plain Python strings can be involved:
+Although WebStack has some support for detecting character encodings used +in requests, it is often best for your application to exercise control over +which encoding is used when inspecting request +parameters and when producing responses. The +best way to do this is to decide which encoding is most suitable for the data +presented and received in your application and then to use it throughout. +Here is an outline of code which does this:
+from WebStack.Generic import ContentType + +class MyResource: + + encoding = "utf-8" # We decide on "utf-8" as our chosen + # encoding. + def respond(self, trans): + [Do various things.] + + fields = trans.get_fields_from_body(encoding=self.encoding) # Explicitly use the encoding. + + [Do other things with the Unicode values from the fields.] + + trans.set_content_type(ContentType("text/html", self.encoding)) # The output Web page uses the encoding. + + [Produce the response, making sure that self.encoding is used to convert Unicode to raw strings.]+ + diff -r d0112e8a1847 -r 441c6bf6ad7d docs/methods.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/methods.html Sun Apr 10 21:11:25 2005 +0000 @@ -0,0 +1,91 @@ + + + + +
In order for an application to behave in the right way when someone sends +a request into it, the application must take into consideration the type of +request being sent. The type of request is typically referred to as the +"request method" and indicates the kind of operation the user is attempting +to perform.
+ +The following table summarises the most common methods defined for Web +applications in the HTTP and WebDAV specifications:
+ +Method | +Type of Operation | +
---|---|
GET | +Retrieve a Web page or resource | +
POST | +Present information to an application - for example, submission of + fields in a form | +
PUT | +Upload a new Web page or resource | +
DELETE | +Delete a Web page or resource | +
PROPFIND | +List resources on a server or in an application | +
Most applications will at least need to support the GET request method in +order to support some kind of user experience, and those which employ forms +in Web pages will most probably want to support the POST request method, +too.
+ +Transaction objects provide the following method for discovering the +request method:
+get_request_method
Not all request methods are appropriate to every application. Should a +request be received which uses a method not supported by an application, the +most appropriate way of responding is to signal this condition to the sender +of the request. HTTP provides a response code to communicate just this kind +of condition - "405 Method Not Allowed".
+ +Transaction objects provide the set_response_code
method (as
+described in "Responses and Presentation") to
+communicate critical information on the success or failure of a request. In
+this case, we would use this method on a transaction object
+trans
as follows:
trans.set_response_code(405)+
Request parameters are typically added to the request body when forms are
+submitted by a browser which is instructed to use the POST
request method. A Web form (in HTML) can be used to
+achieve this; for example:
<form method="POST" action="http://www.boddie.org.uk/application"> + <input name="param1" type="text" /> + <input name="param2" type="text" /> +</form>+ +
As a consequence of this form being submitted, the following parameters +will become available in the application:
+param1
with the value value1
param2
with the value value2
Parameters encoded in this way are not transferred in URLs and are mostly +hidden in user interfaces, although viewing a Web page's source can often +reveal default values of such parameters.
+ +Transaction objects provide the following methods to access parameters +specified in request headers. The terminology used in the API describes such +parameters as body fields, since such parameters are often provided by form +fields.
+get_fields_from_body
encoding
parameter may be used to assist the
+ process of converting parameter values to Unicode objects - see below
+ for a discussion of the issues with this parameter.Some limitations exist with request body parameters:
+One way request body parameters may be used is to provide a mechanism for +the uploading of entire files from browsers and other Web clients to +applications. Unlike other parameters, those which carry file upload data +expose the contents of such uploaded files as plain Python string values +instead of Unicode objects.
+ + diff -r d0112e8a1847 -r 441c6bf6ad7d docs/parameters-headers.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/parameters-headers.html Sun Apr 10 21:11:25 2005 +0000 @@ -0,0 +1,67 @@ + + + + +Header parameters are typically specified in the URL like this:
+http://www.boddie.org.uk/application?param1=value1¶m2=value2+ +
Following the rules set out in "URLs and Paths", +we can say that the "query string" employed is this:
+param1=value1¶m2=value2+ +
From this string, we may extract the parameters and state that they are +the following:
+param1
with the value value1
param2
with the value value2
Parameters encoded in this way can be written into hyperlinks and may be
+used to remember things as users navigate their way around an application.
+Alternatively, a Web form (in HTML) written to use the GET
request method may be used to achieve the same
+effect:
<form method="GET" action="http://www.boddie.org.uk/application"> + <input name="param1" type="text" /> + <input name="param2" type="text" /> +</form>+ +
Transaction objects provide the following methods to access parameters +specified in request headers. The terminology used in the API describes such +parameters as path fields, since such parameters are often provided by form +fields.
+get_fields_from_path
get_query_string
There are some limitations with header parameters:
+Even though it is possible to expose different parts of an application +using different URLs and paths, this usually is only +enough for applications which model some kind of filesystem or repository. Applications which +involve user input through forms, for example, need to be able to receive +such input by other means, and this is where request parameters come in. For +example, when a user fills out a form in a Web browser, the following +happens:
+Request parameters can originate from two sources:
+If the origin of the different parameters received in a request is not +particularly interesting or important, WebStack provides a convenience method +in transaction objects to get all known parameters from a request:
+get_fields
encoding
parameter may be used to assist the
+ process of converting parameter values to Unicode objects - see "Request Body Parameters" and "Character Encodings" for more discussion of
+ this parameter.Generally, it is not recommended to just get all parameters since there +may be some parameters from the request headers which have the same names as +some other parameters from the request body. Consequently, confusion could +arise about the significance of various parameter values.
+ + diff -r d0112e8a1847 -r 441c6bf6ad7d docs/paths.html --- a/docs/paths.html Sat Apr 09 23:50:49 2005 +0000 +++ b/docs/paths.html Sun Apr 10 21:11:25 2005 +0000 @@ -1,6 +1,6 @@ + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">get_path
get_path_without_query
Sometimes, a "query string" will be provided as part of a URL; for +example:
+http://www.boddie.org.uk/application?param1=value1+ +
The question mark character marks the beginning of the query string which +contains encoded parameter information; such information and its inspection +is discussed in "Request Parameters and +Uploads".
+