1 <?xml version="1.0" encoding="iso-8859-1"?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 4 <html xmlns="http://www.w3.org/1999/xhtml"> 5 <head> 6 <title>Request Parameters and Uploads</title> 7 <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 8 <link href="styles.css" rel="stylesheet" type="text/css" /> 9 </head> 10 11 <body> 12 <h1>Request Parameters and Uploads</h1> 13 14 <p>Even though it is possible to expose different parts of an application 15 using different <a href="paths.html">URLs and paths</a>, this usually is only 16 enough for applications which model some kind of <a 17 href="paths-filesystem.html">filesystem</a> or repository. Applications which 18 involve user input through forms, for example, need to be able to receive 19 such input by other means, and this is where request parameters come in. For 20 example, when a user fills out a form in a Web browser, the following 21 happens:</p> 22 <ol> 23 <li>The browser collects the values in the form fields and puts them in a 24 request as request parameters.</li> 25 <li>The request is sent to the server environment and into the 26 application.</li> 27 <li>The application reads the field values using the WebStack API.</li> 28 </ol> 29 30 <h2>Parameter Origins</h2> 31 32 <p>Request parameters can originate from two sources:</p> 33 <ul> 34 <li><a href="parameters-headers.html">Request headers</a> - parameters are 35 found here when they are specified in the URL as a "query string".</li> 36 <li><a href="parameters-body.html">Request bodies</a> - parameters are 37 found here when the POST <a href="methods.html">request method</a> is 38 used.</li> 39 </ul> 40 41 <p>One useful application of parameters transferred in request bodies is the 42 sending or uploading of file contents through such parameters - this is 43 described in "Request Body Parameters". Another way of uploading content in 44 conjunction with the <code>PUT</code> <a href="methods.html">request 45 method</a> is mentioned below.</p> 46 47 <div class="WebStack"> 48 <h3>WebStack API - Getting All Parameters</h3> 49 50 <p>If the origin of the different parameters received in a request is not 51 particularly interesting or important, WebStack provides a convenience method 52 in transaction objects to get all known parameters from a request:</p> 53 <dl> 54 <dt><code>get_fields</code></dt> 55 <dd>This method returns a dictionary mapping field names to lists of 56 values for all known parameters. Each value will be a Unicode 57 object.<br /> 58 An optional <code>encoding</code> parameter may be used to assist the 59 process of converting parameter values to Unicode objects - see <a 60 href="parameters-body.html">"Request Body Parameters"</a> and <a 61 href="encodings.html">"Character Encodings"</a> for more discussion of 62 this parameter.</dd> 63 </dl> 64 </div> 65 66 <p>Generally, it is not recommended to just get all parameters since there 67 may be some parameters from the request headers which have the same names as 68 some other parameters from the request body. Consequently, confusion could 69 arise about the significance of various parameter values.</p> 70 71 <h2>Using PUT Requests to Upload Files</h2> 72 73 <p>When handling requests in your application, instead of treating request as 74 containers of parameters and using the WebStack API methods to access those 75 parameters, you can instead choose to read directly from the data sent by the 76 user and interpret that data in your own way. In most situations, this is not 77 really necessary - those methods will decode request parameters (for example, 78 form fields) in a way which is fairly convenient - but when files are being 79 sent, and when the <a href="methods.html">request method</a> is specified as 80 <code>PUT</code>, it is necessary to obtain the input stream from the request 81 and to read the file contents from that stream.</p> 82 83 <div class="WebStack"> 84 <h3>WebStack API - Reading Directly from Requests</h3> 85 86 <p>When the request does not contain standard form-encoded parameter 87 information and instead contains the contents of an uploaded file, methods 88 like <code>get_fields</code> and <code>get_fields_from_body</code> should be 89 avoided and other methods in the transaction employed.</p> 90 <dl> 91 <dt><code>get_request_stream</code></dt> 92 <dd>This returns the input stream associated with the request. Reading 93 from this will result in the request body being obtained as a plain 94 Python string.</dd> 95 <dt><code>get_content_type</code></dt> 96 <dd>This returns a content type object (typically 97 <code>WebStack.Generic.ContentType</code>) which describes the request 98 body's contents.</dd> 99 </dl> 100 </div> 101 102 <p>The purpose and behaviour of <code>PUT</code> <a 103 href="methods.html">request methods</a> is described in the HTTP 104 specification.</p> 105 </body> 106 </html>