WebStack

Changeset

629:e0d4c80ffc97
2007-02-28 paulb raw files shortlog changelog graph [project @ 2007-02-28 22:31:10 by paulb] Improved encodings documentation, adding references to the EncodingSelector class. rel-1-2-2
docs/encodings.html (file) docs/responses.html (file) docs/selectors.html (file)
     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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;<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&nbsp;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&nbsp;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>&nbsp;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&nbsp;<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&nbsp;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&nbsp;resource
    3.34 +objects whilst changing the default encoding of the current transaction object. The class can be applied&nbsp;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>&nbsp;object instead of an instance of the <code>MyResource</code> class. However, the <code>EncodingSelector</code>&nbsp;will forward requests on to <code>MyResource</code>&nbsp;(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&nbsp;<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>&nbsp;sets
    3.42 +a default encoding,&nbsp;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&nbsp;<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&nbsp;<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