1.1 --- a/docs/encodings.html Wed Feb 28 19:49:11 2007 +0000
1.2 +++ b/docs/encodings.html Wed Feb 28 22:31:10 2007 +0000
1.3 @@ -43,8 +43,7 @@
1.4 for Unicode objects which let you think of letters, numbers, symbols
1.5 and all other characters in an abstract way.</p>
1.6 <ul>
1.7 - <li>Convert textual content to Unicode as soon as possible (see below
1.8 -for choosing encodings).</li>
1.9 + <li>Convert textual content to Unicode as soon as possible.</li>
1.10 <li>If you must include hard-coded messages in your application code,
1.11 make sure to specify the encoding using the <a href="http://www.python.org/peps/pep-0263.html">standard declaration</a>
1.12 at the top of your source file.</li>
1.13 @@ -68,10 +67,13 @@
1.14 best way to do this is to decide which encoding is most suitable for
1.15 the data
1.16 presented and received in your application and then to use it
1.17 -throughout.
1.18 -Here is an outline of code which does this:</p>
1.19 +throughout.</p><p>One
1.20 +approach which works acceptably for smaller applications is to define
1.21 +an attribute (or a global) which is conveniently accessible and which
1.22 +can be used directly with various transaction methods. Here is an
1.23 +outline of code which does this:</p>
1.24 <pre>from WebStack.Generic import ContentType<br /><br />class MyResource:<br /><br /> encoding = "utf-8" # We decide on "utf-8" as our chosen<br /> # encoding.<br /> def respond(self, trans):<br /> [Do various things.]<br /><br /> fields = trans.get_fields_from_body(encoding=self.encoding) # Explicitly use the encoding.<br /><br /> [Do other things with the Unicode values from the fields.]<br /><br /> trans.set_content_type(ContentType("text/html", self.encoding)) # The output Web page uses the encoding.<br /><br /> [Produce the response, making sure that self.encoding is used to convert Unicode to raw strings.]</pre>
1.25 -<h3>Tell Encodings to Other Components</h3>
1.26 +<h3>Use EncodingSelector to Set the Default Encoding</h3><p>An arguably better approach is to use selectors (as described in <a href="selectors.html">"Selectors - Components for Dispatching to Resources"</a>), typically in a "site map" arrangement (as described in <a href="deploying.html">"Deploying a WebStack Application"</a>), specifically using the <code>EncodingSelector</code>:</p><pre>from WebStack.Generic import ContentType<br /><br />class MyResource:<br /><br /> def respond(self, trans):<br /> [Do various things.]<br /><br /> fields = trans.get_fields_from_body() # Encoding set by EncodingSelector.<br /><br /> [Do other things with the Unicode values from the fields.]<br /><br /> trans.set_content_type(ContentType("text/html")) # The output Web page uses the default encoding.<br /><br /> [Produce the response, making sure that self.encoding is used to convert Unicode to raw strings.]<br /><br />def get_site_map():<br /><br /> return EncodingSelector(MyResource(), "utf-8")</pre><h3>Tell Encodings to Other Components</h3>
1.27 <p>When using other components to generate content (see <a href="integrating.html">"Integrating with Other Systems"</a>), it may
1.28 be the case that such components will just write the generated content
1.29 straight to a normal stream (rather than one wrapped by a <code>codecs</code>
2.1 --- a/docs/responses.html Wed Feb 28 19:49:11 2007 +0000
2.2 +++ b/docs/responses.html Wed Feb 28 22:31:10 2007 +0000
2.3 @@ -33,7 +33,12 @@
2.4 <p>The kind of code involved may
2.5 well resemble the following:</p>
2.6 <pre>from WebStack.Generic import ContentType<br /><br />class MyResource:<br /> def respond(self, trans):<br /> [Perform the requested operations.]<br /><br /> if [the operation was successful]:<br /> trans.set_response_code(200)<br /> trans.set_content_type(ContentType("text/html", encoding="utf-8"))<br /> out = trans.get_response_stream()<br /> out.write([some data either as a plain string suitably encoded or as Unicode])<br /> else:<br /> trans.set_response_code(500) # or some other code<br /> trans.set_content_type(ContentType("text/html", encoding="utf-8"))<br /> out = trans.get_response_stream()<br /> out.write([some other data either as a plain string suitably encoded or as Unicode])</pre>
2.7 -<p>As discussed in <a href="encodings.html">"Character Encodings"</a>,
2.8 +<h2>Unicode and the Response Stream</h2><p>Although an encoding may be specified or be set as a default by the <code>EncodingSelector</code> (see <a href="selectors.html">"Selectors - Components for Dispatching to Resources"</a>),
2.9 +it should be noted that the encoding of textual information will only
2.10 +take place if Unicode objects are written to the stream. Where binary
2.11 +information or information which should not be changed is being
2.12 +written, this must be supplied as plain strings to the transaction
2.13 +object's <code>write</code> method.</p><p>As discussed in <a href="encodings.html">"Character Encodings"</a>,
2.14 care
2.15 must be taken generating the response so that it meets any expectations
2.16 that
3.1 --- a/docs/selectors.html Wed Feb 28 19:49:11 2007 +0000
3.2 +++ b/docs/selectors.html Wed Feb 28 22:31:10 2007 +0000
3.3 @@ -10,7 +10,7 @@
3.4 resources, but which attempt to "select" other resources, dispatch each
3.5 request to those resources, and to cause various side-effects, mostly
3.6 on the attributes stored on the transaction object. These "selector"
3.7 -classes behave those in the <code>ResourceMap</code> module, but aspire to be more generally applicable.</p><h2>Introducing PathSelector</h2><p>In
3.8 +classes behave those in the <code>ResourceMap</code> module, but aspire to be more generally applicable.</p><h2>Selecting Path Roots with PathSelector</h2><p>In
3.9 non-trivial applications, it is often desirable to know the path or URL
3.10 to a particular resource, especially the "root" resource under which
3.11 the application or one of its components may reside. The <code>PathSelector</code>
3.12 @@ -28,4 +28,37 @@
3.13 function (as described in the <a href="deploying.html">"Deploying a WebStack Application"</a> document) would provide a <code>PathSelector</code> object instead of an instance of the <code>MyResource</code> class. However, the side-effect of combining these two resources would be the availability of an attribute named <code>root</code> on the transaction object. Thus, the "root" <code>MyResource</code>
3.14 object and, indeed, all resource objects visited after this side-effect
3.15 has occurred will have access to the "root" path or URL information.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Selectors.PathSelector-class.html">API documentation</a> for the <code>PathSelector</code>
3.16 -class provides additional information.</p></div></body></html>
3.17 \ No newline at end of file
3.18 +class provides additional information.</p></div><h2>Defining Encodings using EncodingSelector</h2><p>One
3.19 +frequently bothersome aspect of writing Web applications involves the
3.20 +processing and production of text in different encodings. Whilst the
3.21 +WebStack API lets applications explicitly state the character encoding
3.22 +for various operations, one often wants to be able to ignore such
3.23 +details since they start to clutter up application code. The <code>EncodingSelector</code> class offers a basic solution which is compatible with the mechanisms in transaction objects: by wrapping WebStack resources with instances of <code>EncodingSelector</code>,
3.24 +an application-wide default encoding (or character set) will be
3.25 +defined; this will result in request information being processed
3.26 +according to the stated encoding and response information being
3.27 +produced according to that encoding (see below for more details of the
3.28 +latter activity).</p><div class="WebStack">
3.29 +<h3>WebStack API - The EncodingSelector Class</h3>
3.30 +
3.31 +<p>The <code>EncodingSelector</code>
3.32 +class (found in the
3.33 +<code>WebStack.Resources.Selectors</code> module) wraps resource
3.34 +objects whilst changing the default encoding of the current transaction object. The class can be applied like this:</p><pre>def get_site_map():<br /> return EncodingSelector(MyResource(), "utf-8")</pre><p>Here, the <code>get_site_map</code>
3.35 +function (as described in the <a href="deploying.html">"Deploying a WebStack Application"</a> document) would provide a <code>EncodingSelector</code> object instead of an instance of the <code>MyResource</code> class. However, the <code>EncodingSelector</code> will forward requests on to <code>MyResource</code> (since it "selects" that resource), whilst setting the default encoding to be <code>"utf-8"</code>.</p><h4>Request Streams and Encodings</h4><p>Although a default encoding affects the processing of request parameters, direct access to the request stream using the <code>get_request_stream</code>
3.36 +method will only produce plain strings. This behaviour is justified by
3.37 +the observation that, if conversion from an encoding to Unicode were to
3.38 +take place, the resulting character values may be unsuitable
3.39 +substitutes for the original byte values in applications intending to
3.40 +make use of the raw incoming (possibly binary) data. A recipe for
3.41 +making a Unicode stream is provided in the <a href="encodings.html">"Character Encodings"</a> document.</p><h4>Response Encodings and Content Types</h4><p>Although <code>EncodingSelector</code> sets
3.42 +a default encoding, responses will generally be written in that
3.43 +encoding, at least if textual data is written to the response stream as
3.44 +Unicode objects. However, the content type must typically be set either
3.45 +to match the encoding in use or to not specify an encoding. It may
3.46 +become necessary to find out what the response stream encoding is when
3.47 +creating a <code>ContentType</code> object. For this and other purposes, the <code>get_response_stream_encoding</code> method is available on the transaction object<code></code>:</p><pre>from WebStack.Generic import ContentType<br /><br />def respond(self, trans):<br /><br /> # Some code...<br /><br /> trans.set_content_type(ContentType("text/html", trans.get_response_stream_encoding()))<br /> out = trans.get_response_stream()<br /> out.write(some_unicode_object)</pre><p>However, it is completely acceptable to omit the encoding information where a default encoding has been set:</p><pre> trans.set_content_type(ContentType("text/html")) # no encoding/charset specified<br /></pre><h4>Reading the Default Directly</h4><p>For
3.48 +some activities, such as making a Unicode stream from the request
3.49 +stream, it is desirable to find out the encoding set by the selector.
3.50 +This information is made available on transaction objects as the <code>default_charset</code> attribute.</p><h4>Further Reading</h4><p>The <a href="../apidocs/public/WebStack.Resources.Selectors.EncodingSelector-class.html">API documentation</a> for the <code>EncodingSelector</code>
3.51 +class provides additional information, along with the <a href="responses.html">"Responses and Presentation"</a> document.</p></div><p></p><br /></body></html>
3.52 \ No newline at end of file