WebStack

Annotated docs/parameters.html

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