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