The term "cookie" is a technical term describing information which +is set in a response sent to a user and which is then provided every +time the user accesses the application. In effect, the application asks +the user to remember something on its behalf and to remind the +application of that thing over and over again.
+Although there are some restrictions on how much information can be +stored in a cookie and the type of that information (it must be a plain +Python string), the mechanism is useful for identifying users or +remembering simple things about the operations that the user has been +performing. Some applications use cookies to remember the state +of their user interfaces, such as which parts of a navigational +menu have been opened by the user, for example.
+The transaction +object provides the following methods for setting cookie information +and accessing it on later occasions:
+set_cookie_valueset_cookieget_cookiesget_cookiedelete_cookieCookie +objects can be any objects having the following properties:
+namevalueCookies which were set in previous interactions are always available +straight away unless they were deleted at some earlier point in time. +Typically, your application will have reserved a cookie name and will +then access the cookie using that name; for example:
+# In the respond method...+
my_cookie = trans.get_cookie("my_cookie") # this gets a cookie object
my_information = my_cookie.value # trans.get_cookie_value would get this value directly
It is possible to modify the cookie object, but on its own this has
+no effect on the value exchanged between the application and the user.
+To update the cookie in that way, you must also use the set_cookie
+method, or instead use the set_cookie_value method:
# In the respond method after getting the cookie...+
my_cookie.value = "Something else!" # this must be a plain string
trans.set_cookie(my_cookie) # this uses the existing object
trans.set_cookie_value("another_cookie", "More information!") # this adds a new cookie with the given name
Note that changing a cookie's value directly using set_cookie_value
+will not necessarily change the value found in cookie objects returned
+by subsequent calls to get_cookie during the handling
+of the same request.
To delete cookies, actual cookie objects must be provided:
+# In the respond method after getting the cookie...+
trans.delete_cookie(my_cookie)
This does not necessarily remove the cookie from the dictionary
+returned by get_cookies or prevent get_cookie
+returning a cookie object for the name specified in the deleted
+cookie during the handling of the same request.
WebStack tries to let applications work with Unicode as much as possible, -but there are two places where plain Python strings can be involved:
+When writing applications with WebStack, you should try and use +Python's Unicode objects as much as possible. However, there are a +number of places where plain Python strings can be involved:
When Web pages (and other types of content) are sent to and from +users of your application, the text will be in some kind of character +encoding. For example, in English-speaking environments, the US-ASCII +encoding is common and contains the basic letters, numbers and symbols +used in English, whereas in Western Europe encodings like +ISO-8859-1 and ISO-8859-15 are typically used, since they contain +additional letters and symbols in order to support other languages. +Often, UTF-8 is used to encode text because it covers most languages +simultaneously and is therefore flexible enough for many applications.
+When URLs are received in applications, in order for some of the +request parameters to be interpreted, the situation is a bit more +awkward. The original text is encoded in US-ASCII but will contain +special numeric codes that indicate character values in the +original text encoding - see the description +of query strings for more information.
Although WebStack has some support for detecting character encodings used -in requests, it is often best for your application to exercise control over -which encoding is used when inspecting request -parameters and when producing responses. The -best way to do this is to decide which encoding is most suitable for the data -presented and received in your application and then to use it throughout. +
Handling text in specific encodings using normal Python strings can +be difficult, and handling text in multiple encodings in the same +application can be highly error-prone. Fortunately, Python has support +for Unicode objects which let you think of letters, numbers, symbols +and all other characters in an abstract way.
+codecs
+module contains useful functions to access streams as if Unicode
+objects were being transmitted; for example:import codecs+
class MyResource:
encoding = "utf-8"
def respond(self, trans):
stream = trans.get_request_stream() # only reads strings
unicode_stream = codecs.getreader(self.encoding)(stream) # reads Unicode objects
[Some activity...]
out = trans.get_response_stream() # only writes strings
unicode_out = codecs.getwriter(self.encoding)(out) # writes Unicode objects
If you are reading and writing binary content, Unicode objects are +inappropriate. Make sure to open files in binary mode, where necessary.
+Although WebStack has some support for detecting character encodings +used +in requests, it is often best for your application to exercise control +over +which encoding is used when inspecting +request +parameters and when producing responses. +The +best way to do this is to decide which encoding is most suitable for +the data +presented and received in your application and then to use it +throughout. 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.]
+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.]
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
+module function). In such cases, it is likely that for textual content
+such as XML or related formats (XHTML, SVG, HTML) you will need to
+instruct the component to use your chosen encoding; for example:
# In the respond method, xml_document is an xml.dom.minidom.Document object...+
xml_document.toxml(self.encoding)
This will then generate the appropriate characters in the output and specify the correct encoding +for the XML document.