# HG changeset patch # User paulb # Date 1113255143 0 # Node ID effeae83e02756a81daed546e4715faa635bd4a0 # Parent 06fde0b81b28884dc267cfc2ac6ccc9ac6b69336 [project @ 2005-04-11 21:32:23 by paulb] Improved the stylesheet. Added file upload and response descriptions. diff -r 06fde0b81b28 -r effeae83e027 docs/parameters.html --- a/docs/parameters.html Mon Apr 11 17:53:52 2005 +0000 +++ b/docs/parameters.html Mon Apr 11 21:32:23 2005 +0000 @@ -38,6 +38,12 @@ used. +

One useful application of parameters transferred in request bodies is the +sending or uploading of file contents through such parameters - this is +described in "Request Body Parameters". Another way of uploading content in +conjunction with the PUT request +method is mentioned below.

+

WebStack API - Getting All Parameters

@@ -61,5 +67,40 @@ 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.

+ +

Using PUT Requests to Upload Files

+ +

When handling requests in your application, instead of treating request as +containers of parameters and using the WebStack API methods to access those +parameters, you can instead choose to read directly from the data sent by the +user and interpret that data in your own way. In most situations, this is not +really necessary - those methods will decode request parameters (for example, +form fields) in a way which is fairly convenient - but when files are being +sent, and when the request method is specified as +PUT, it is necessary to obtain the input stream from the request +and to read the file contents from that stream.

+ +
+

WebStack API - Reading Directly from Requests

+ +

When the request does not contain standard form-encoded parameter +information and instead contains the contents of an uploaded file, methods +like get_fields and get_fields_from_body should be +avoided and other methods in the transaction employed.

+
+
get_request_stream
+
This returns the input stream associated with the request. Reading + from this will result in the request body being obtained as a plain + Python string.
+
get_content_type
+
This returns a content type object (typically + WebStack.Generic.ContentType) which describes the request + body's contents.
+
+
+ +

The purpose and behaviour of PUT request methods is described in the HTTP +specification.

diff -r 06fde0b81b28 -r effeae83e027 docs/responses.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/responses.html Mon Apr 11 21:32:23 2005 +0000 @@ -0,0 +1,84 @@ + + + + + Responses and Presentation + + + + + +

Responses and Presentation

+ +

After performing some kind of processing on input information, an +application will then want to produce some kind of response to indicate what +went on. Here are some examples of responses:

+ + +

Generating Responses

+ +

The procedure involved in generating a response usually involves the +following steps:

+
    +
  1. Setting a response code to signal whether the application performed the + requested operation successfully.
    2. +
  2. Setting a content type and a character encoding.
    3. +
  3. Producing content and sending it to the user.
    4. +
+ +

The kind of code involved may well resemble the following:

+
from WebStack.Generic import ContentType
+
+class MyResource:
+    def respond(self, trans):
+        [Perform the requested operations.]
+
+        if [the operation was successful]:
+            trans.set_response_code(200)
+            trans.set_content_type(ContentType("text/html", encoding="utf-8"))
+            out = trans.get_response_stream()
+            out.write([some data either as a plain string suitably encoded or as Unicode])
+        else:
+            trans.set_response_code(500) # or some other code
+            trans.set_content_type(ContentType("text/html", encoding="utf-8"))
+            out = trans.get_response_stream()
+            out.write([some other data either as a plain string suitably encoded or as Unicode])
+ +

As discussed in "Character Encodings", care +must be taken generating the response so that it meets any expectations that +browsers and other Web clients may have.

+ +
+

WebStack API - Response-Related Methods

+ +

Transaction objects have various methods that can be used in generating +responses:

+
+
set_response_code
+
This accepts an integer value denoting the response condition as + described in the HTTP specification. If this method is not used, + WebStack sets a 200 status condition on the response, + meaning that the request was processed successfully.
+
set_content_type
+
This accepts a content type object (typically + WebStack.Generic.ContentType) which specifies both the + media type and the character encoding (if relevant) of the data sent to + the user. The media type describes the format of the data (eg. + text/html - a Web page), whereas the character encoding + describes how any character information on the page is encoded - see "Character Encodings" for more + information.
+
get_response_stream
+
This returns the output stream through which data may be sent to the + user.
+
+
+ + diff -r 06fde0b81b28 -r effeae83e027 docs/styles.css --- a/docs/styles.css Mon Apr 11 17:53:52 2005 +0000 +++ b/docs/styles.css Mon Apr 11 21:32:23 2005 +0000 @@ -34,6 +34,10 @@ PRE { background-color: silver; color: black; +border-style: solid; +border-color: black; +border-width: 1pt; +padding: 0.5em; } .WebStack { @@ -41,8 +45,8 @@ border-style: solid; border-color: black; border-width: 1pt; -padding-left: 12pt; -padding-right: 12pt; +padding-left: 0.5em; +padding-right: 0.5em; } TH, TD, CAPTION {