WebStack

docs/parameters.html

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