# HG changeset patch # User paulb # Date 1172701870 0 # Node ID e0d4c80ffc97d684b6b1cab2689b4e780795a664 # Parent 9cdcfaa9ff7f8c8a326b19056c809a7855683274 [project @ 2007-02-28 22:31:10 by paulb] Improved encodings documentation, adding references to the EncodingSelector class. diff -r 9cdcfaa9ff7f -r e0d4c80ffc97 docs/encodings.html --- a/docs/encodings.html Wed Feb 28 19:49:11 2007 +0000 +++ b/docs/encodings.html Wed Feb 28 22:31:10 2007 +0000 @@ -43,8 +43,7 @@ for Unicode objects which let you think of letters, numbers, symbols and all other characters in an abstract way.
One +approach which works acceptably for smaller applications is to define +an attribute (or a global) which is conveniently accessible and which +can be used directly with various transaction methods. Here is an +outline of code which does this:
from WebStack.Generic import ContentType-
class MyResource:
encoding = "utf-8" # We decide on "utf-8" as our chosen
# encoding.
def respond(self, trans):
[Do various things.]
fields = trans.get_fields_from_body(encoding=self.encoding) # Explicitly use the encoding.
[Do other things with the Unicode values from the fields.]
trans.set_content_type(ContentType("text/html", self.encoding)) # The output Web page uses the encoding.
[Produce the response, making sure that self.encoding is used to convert Unicode to raw strings.]
An arguably better approach is to use selectors (as described in "Selectors - Components for Dispatching to Resources"), typically in a "site map" arrangement (as described in "Deploying a WebStack Application"), specifically using the EncodingSelector
:
from WebStack.Generic import ContentType
class MyResource:
def respond(self, trans):
[Do various things.]
fields = trans.get_fields_from_body() # Encoding set by EncodingSelector.
[Do other things with the Unicode values from the fields.]
trans.set_content_type(ContentType("text/html")) # The output Web page uses the default encoding.
[Produce the response, making sure that self.encoding is used to convert Unicode to raw strings.]
def get_site_map():
return EncodingSelector(MyResource(), "utf-8")
When using other components to generate content (see "Integrating with Other Systems"), it may
be the case that such components will just write the generated content
straight to a normal stream (rather than one wrapped by a codecs
diff -r 9cdcfaa9ff7f -r e0d4c80ffc97 docs/responses.html
--- a/docs/responses.html Wed Feb 28 19:49:11 2007 +0000
+++ b/docs/responses.html Wed Feb 28 22:31:10 2007 +0000
@@ -33,7 +33,12 @@
The kind of code involved may well resemble the following:
from WebStack.Generic import ContentType-
class MyResource:
def respond(self, trans):
[Perform the requested operations.]
if [the operation was successful]:
trans.set_response_code(200)
trans.set_content_type(ContentType("text/html", encoding="utf-8"))
out = trans.get_response_stream()
out.write([some data either as a plain string suitably encoded or as Unicode])
else:
trans.set_response_code(500) # or some other code
trans.set_content_type(ContentType("text/html", encoding="utf-8"))
out = trans.get_response_stream()
out.write([some other data either as a plain string suitably encoded or as Unicode])
As discussed in "Character Encodings", +
Although an encoding may be specified or be set as a default by the EncodingSelector
(see "Selectors - Components for Dispatching to Resources"),
+it should be noted that the encoding of textual information will only
+take place if Unicode objects are written to the stream. Where binary
+information or information which should not be changed is being
+written, this must be supplied as plain strings to the transaction
+object's write
method.
As discussed in "Character Encodings",
care
must be taken generating the response so that it meets any expectations
that
diff -r 9cdcfaa9ff7f -r e0d4c80ffc97 docs/selectors.html
--- a/docs/selectors.html Wed Feb 28 19:49:11 2007 +0000
+++ b/docs/selectors.html Wed Feb 28 22:31:10 2007 +0000
@@ -10,7 +10,7 @@
resources, but which attempt to "select" other resources, dispatch each
request to those resources, and to cause various side-effects, mostly
on the attributes stored on the transaction object. These "selector"
-classes behave those in the ResourceMap
module, but aspire to be more generally applicable.
In
+classes behave those in the ResourceMap
module, but aspire to be more generally applicable.
In
non-trivial applications, it is often desirable to know the path or URL
to a particular resource, especially the "root" resource under which
the application or one of its components may reside. The PathSelector
@@ -28,4 +28,37 @@
function (as described in the "Deploying a WebStack Application" document) would provide a PathSelector
object instead of an instance of the MyResource
class. However, the side-effect of combining these two resources would be the availability of an attribute named root
on the transaction object. Thus, the "root" MyResource
object and, indeed, all resource objects visited after this side-effect
has occurred will have access to the "root" path or URL information.
The API documentation for the PathSelector
-class provides additional information.