WebStack

docs/path-value-encoding.html

755:139b1412b9c3
2008-02-03 paulb [project @ 2008-02-03 19:58:01 by paulb] Added measures to permit the usage of non-ASCII characters in plaintexts.
     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   <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />     5   <title>Encoding and Decoding Path Values</title>     6   <link href="styles.css" rel="stylesheet" type="text/css" /></head>     7 <body>     8 <h1>Encoding and Decoding Path Values</h1><p>On some occasions it can     9 be necessary to manually decode path values, producing genuine Unicode    10 objects, and then to encode them, producing plain strings that can be    11 used in response headers and other places. For such occasions, some    12 transaction methods are available:</p><div class="WebStack">    13 <h3>WebStack API - Encoding and Decoding Path Values</h3>    14 <p>WebStack provides the following methods to transform path values:</p>    15 <dl><dt><code>decode_path</code></dt><dd>This method accepts a path containing "URL encoded" information (as defined in the <a href="paths.html">"URLs and Paths"</a>    16 document) and, using an optional encoding parameter, returns a Unicode    17 object containing genuine character values in place of the "URL    18 encoded" values.</dd><dt><code>encode_path</code></dt><dd>This method    19 accepts a Unicode object containing the path and an optional encoding    20 parameter; it reverses the process carried out by the <code>decode_path</code> method.</dd></dl>    21 </div><p>Generally, the <code>decode_path</code> method is of little interest; its only relatively common application might be to decode query strings:</p><pre>qs = trans.get_query_string()                # eg. "a=%E6"<br />new_qs = trans.decode_path(qs, "iso-8859-1") #     producing "a=?"</pre><p>Such operations are generally better performed using the <a href="parameters.html">request parameter methods</a>.</p><p>The <code>encode_path</code>    22 method is slightly more useful: since various transaction methods    23 return values which have already been transformed into Unicode objects,    24 we must consider the use of <code>encode_path</code> to produce values    25 which are suitable for feeding into other methods. For example, having    26 obtained a path, we may wish to cause a <a href="redirection.html">redirect</a> to another location    27 based on that path:</p><pre>path = trans.get_path_without_query("iso-8859-1") # eg. "/app/resource"<br />path += "/???;"<br />new_path = trans.encode_path(path, "iso-8859-1")  #     producing "/app/resource/%E6%F8%E5"<br />trans.redirect(new_path)</pre><p>It    28 is essential to encode the path in such situations because the    29 underlying mechanisms do not support the full range of Unicode    30 characters. Some cases where this limitation exists are listed in the <a href="encodings.html">"Character Encodings"</a> document.</p></body></html>