1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/cookies.html Sat Apr 30 00:21:44 2005 +0000
1.3 @@ -0,0 +1,85 @@
1.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 +<html xmlns="http://www.w3.org/1999/xhtml">
1.6 +<head>
1.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.8 + <title>Cookies</title>
1.9 + <meta name="generator"
1.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.12 +</head>
1.13 +<body>
1.14 +<h1>Cookies</h1>
1.15 +<p>The term "cookie" is a technical term describing information which
1.16 +is set in a response sent to a user and which is then provided every
1.17 +time the user accesses the application. In effect, the application asks
1.18 +the user to remember something on its behalf and to remind the
1.19 +application of that thing over and over again.</p>
1.20 +<h2>Potential Uses</h2>
1.21 +<p>Although there are some restrictions on how much information can be
1.22 +stored in a cookie and the type of that information (it must be a plain
1.23 +Python string), the mechanism is useful for identifying users or
1.24 +remembering simple things about the operations that the user has been
1.25 +performing. Some applications use cookies to remember the state
1.26 +of their user interfaces, such as which parts of a navigational
1.27 +menu have been opened by the user, for example.</p>
1.28 +<div class="WebStack">
1.29 +<h3>WebStack API - Using Cookies</h3>
1.30 +<p>The <a
1.31 + href="../apidocs/public/WebStack.Generic.Transaction-class.html">transaction</a>
1.32 +object provides the following methods for setting cookie information
1.33 +and accessing it on later occasions:</p>
1.34 +<dl>
1.35 + <dt><code>set_cookie_value</code></dt>
1.36 + <dd>This method stores a piece of information associated with a given
1.37 +name and having a given plain Python string value as a cookie. Other
1.38 +information can also be specified which controls the way the
1.39 +cookie is used, notably the path (to which applications the cookie is
1.40 +sent) and expiry time (a UNIX time style number which states when the
1.41 +cookie should stop being exchanged).</dd>
1.42 + <dt><code>set_cookie</code></dt>
1.43 + <dd>This method stores an existing cookie object as a cookie in
1.44 +future communications with the user concerned. The form of such objects
1.45 +is described below.</dd>
1.46 + <dt><code>get_cookies</code></dt>
1.47 + <dd>This method returns a dictionary mapping names to cookie objects.</dd>
1.48 + <dt><code>get_cookie</code></dt>
1.49 + <dd>This method returns a specific cookie object for a given name.</dd>
1.50 + <dt><code>delete_cookie</code></dt>
1.51 + <dd>This method deletes a cookie, ensuring that the information
1.52 +within it is not exchanged in future.</dd>
1.53 +</dl>
1.54 +<p><a
1.55 + href="../apidocs/public/WebStack.Helpers.Request.Cookie-class.html">Cookie</a>
1.56 +objects can be any objects having the following properties:</p>
1.57 +<dl>
1.58 + <dt><code>name</code></dt>
1.59 + <dd>This is the name associated with the cookie. It must be a plain
1.60 +Python string.</dd>
1.61 + <dt><code>value</code></dt>
1.62 + <dd>This is the information stored in the cookie. It must be a plain
1.63 +Python string.</dd>
1.64 +</dl>
1.65 +</div>
1.66 +<h2>How and When to Get and Set Cookies</h2>
1.67 +<p>Cookies which were set in previous interactions are always available
1.68 +straight away unless they were deleted at some earlier point in time.
1.69 +Typically, your application will have reserved a cookie name and will
1.70 +then access the cookie using that name; for example:</p>
1.71 +<pre> # In the respond method...<br /> my_cookie = trans.get_cookie("my_cookie") # this gets a cookie object<br /> my_information = my_cookie.value # trans.get_cookie_value would get this value directly</pre>
1.72 +<p>It is possible to modify the cookie object, but on its own this has
1.73 +no effect on the value exchanged between the application and the user.
1.74 +To update the cookie in that way, you must also use the <code>set_cookie</code>
1.75 +method, or instead use the <code>set_cookie_value</code> method:</p>
1.76 +<pre> # In the respond method after getting the cookie...<br /> my_cookie.value = "Something else!" # this must be a plain string<br /> trans.set_cookie(my_cookie) # this uses the existing object<br /> trans.set_cookie_value("another_cookie", "More information!") # this adds a new cookie with the given name</pre>
1.77 +<p>Note that changing a cookie's value directly using <code>set_cookie_value</code>
1.78 +will not necessarily change the value found in cookie objects returned
1.79 +by subsequent calls to <code>get_cookie</code> during the handling
1.80 +of the same request.</p>
1.81 +<p>To delete cookies, actual cookie objects must be provided:</p>
1.82 +<pre> # In the respond method after getting the cookie...<br /> trans.delete_cookie(my_cookie)</pre>
1.83 +<p>This does not necessarily remove the cookie from the dictionary
1.84 +returned by <code>get_cookies</code> or prevent <code>get_cookie</code>
1.85 +returning a cookie object for the name specified in the deleted
1.86 +cookie during the handling of the same request.</p>
1.87 +</body>
1.88 +</html>
2.1 --- a/docs/design.html Tue Apr 26 18:33:06 2005 +0000
2.2 +++ b/docs/design.html Sat Apr 30 00:21:44 2005 +0000
2.3 @@ -60,7 +60,7 @@
2.4 understood in more detail:</p>
2.5 <ul>
2.6 <li><a href="responses.html">Responses and Presentation</a></li>
2.7 - <li><a href="state.html">Cookies, Sessions and Persistent
2.8 + <li><a href="state.html">Cookies, Sessions, Users and Persistent
2.9 Information</a></li>
2.10 </ul>
2.11 </body>
3.1 --- a/docs/encodings.html Tue Apr 26 18:33:06 2005 +0000
3.2 +++ b/docs/encodings.html Sat Apr 30 00:21:44 2005 +0000
3.3 @@ -1,48 +1,90 @@
3.4 -<?xml version="1.0" encoding="iso-8859-1"?>
3.5 -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.7 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.8 <html xmlns="http://www.w3.org/1999/xhtml">
3.9 <head>
3.10 <title>Character Encodings</title>
3.11 - <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.12 + <meta name="generator"
3.13 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.14 <link href="styles.css" rel="stylesheet" type="text/css" />
3.15 </head>
3.16 -
3.17 <body>
3.18 <h1>Character Encodings</h1>
3.19 -
3.20 -<p>WebStack tries to let applications work with Unicode as much as possible,
3.21 -but there are two places where plain Python strings can be involved:</p>
3.22 +<p>When writing applications with WebStack, you should try and use
3.23 +Python's Unicode objects as much as possible. However, there are a
3.24 +number of places where plain Python strings can be involved:</p>
3.25 <ul>
3.26 - <li>When <a href="responses.html">output is prepared</a> - for example, Web
3.27 - pages.</li>
3.28 <li>When <a href="parameters.html">inspecting request parameters</a>.</li>
3.29 + <li>When <a href="responses.html">sending output in a response</a>.</li>
3.30 + <li>When <a href="parameters.html">receiving uploaded content</a>.</li>
3.31 + <li>When <a href="state.html">accessing cookie information</a>.</li>
3.32 </ul>
3.33 -
3.34 +<p>When Web pages (and other types of content) are sent to and from
3.35 +users of your application, the text will be in some kind of character
3.36 +encoding. For example, in English-speaking environments, the US-ASCII
3.37 +encoding is common and contains the basic letters, numbers and symbols
3.38 +used in English, whereas in Western Europe encodings like
3.39 +ISO-8859-1 and ISO-8859-15 are typically used, since they contain
3.40 +additional letters and symbols in order to support other languages.
3.41 +Often, UTF-8 is used to encode text because it covers most languages
3.42 +simultaneously and is therefore flexible enough for many applications.</p>
3.43 +<p>When URLs are received in applications, in order for some of the
3.44 +request parameters to be interpreted, the situation is a bit more
3.45 +awkward. The original text is encoded in US-ASCII but will contain
3.46 +special numeric codes that indicate character values in the
3.47 +original text encoding - see the <a href="parameters.html">description
3.48 +of query strings</a> for more information.</p>
3.49 <h2>Recommendations</h2>
3.50 -
3.51 -<p>Although WebStack has some support for detecting character encodings used
3.52 -in requests, it is often best for your application to exercise control over
3.53 -which encoding is used when <a href="parameters.html">inspecting request
3.54 -parameters</a> and when <a href="responses.html">producing responses</a>. The
3.55 -best way to do this is to decide which encoding is most suitable for the data
3.56 -presented and received in your application and then to use it throughout.
3.57 +<dl>
3.58 + <dt>The following recommendations should help you avoid issues with
3.59 +incorrect characters in the Web pages (and other content) that you
3.60 +produce:</dt>
3.61 +</dl>
3.62 +<h3>Use Unicode Objects for Textual Content</h3>
3.63 +<p>Handling text in specific encodings using normal Python strings can
3.64 +be difficult, and handling text in multiple encodings in the same
3.65 +application can be highly error-prone. Fortunately, Python has support
3.66 +for Unicode objects which let you think of letters, numbers, symbols
3.67 +and all other characters in an abstract way.</p>
3.68 +<ul>
3.69 + <li>Convert textual content to Unicode as soon as possible (see below
3.70 +for choosing encodings).</li>
3.71 + <li>If you must include hard-coded messages in your application code,
3.72 +make sure to specify the encoding using the <a
3.73 + href="http://www.python.org/peps/pep-0263.html">standard declaration</a>
3.74 +at the top of your source file.</li>
3.75 + <li>Remember that the standard library <code>codecs</code>
3.76 +module contains useful functions to access streams as if Unicode
3.77 +objects were being transmitted; for example:</li>
3.78 +</ul>
3.79 +<pre>import codecs<br /><br />class MyResource:<br /><br /> encoding = "utf-8"<br /><br /> def respond(self, trans):<br /> stream = trans.get_request_stream() # only reads strings<br /> unicode_stream = codecs.getreader(self.encoding)(stream) # reads Unicode objects<br /><br /> [Some activity...]<br /><br /> out = trans.get_response_stream() # only writes strings<br /> unicode_out = codecs.getwriter(self.encoding)(out) # writes Unicode objects</pre>
3.80 +<h3>Use Strings for Binary Content</h3>
3.81 +<p>If you are reading and writing binary content, Unicode objects are
3.82 +inappropriate. Make sure to open files in binary mode, where necessary.</p>
3.83 +<h3>Use Explicit Encodings and Be Consistent</h3>
3.84 +<p>Although WebStack has some support for detecting character encodings
3.85 +used
3.86 +in requests, it is often best for your application to exercise control
3.87 +over
3.88 +which encoding is used when <a href="parameters.html">inspecting
3.89 +request
3.90 +parameters</a> and when <a href="responses.html">producing responses</a>.
3.91 +The
3.92 +best way to do this is to decide which encoding is most suitable for
3.93 +the data
3.94 +presented and received in your application and then to use it
3.95 +throughout.
3.96 Here is an outline of code which does this:</p>
3.97 -<pre>from WebStack.Generic import ContentType
3.98 -
3.99 -class MyResource:
3.100 -
3.101 - encoding = "utf-8" # We decide on "utf-8" as our chosen
3.102 - # encoding.
3.103 - def respond(self, trans):
3.104 - [Do various things.]
3.105 -
3.106 - fields = trans.get_fields_from_body(encoding=self.encoding) # Explicitly use the encoding.
3.107 -
3.108 - [Do other things with the Unicode values from the fields.]
3.109 -
3.110 - trans.set_content_type(ContentType("text/html", self.encoding)) # The output Web page uses the encoding.
3.111 -
3.112 - [Produce the response, making sure that self.encoding is used to convert Unicode to raw strings.] </pre>
3.113 +<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>
3.114 +<h3>Tell Encodings to Other Components</h3>
3.115 +<p>When using other components to generate content (see <a
3.116 + href="integrating.html">"Integrating with Other Systems"</a>), it may
3.117 +be the case that such components will just write the generated content
3.118 +straight to a normal stream (rather than one wrapped by a <code>codecs</code>
3.119 +module function). In such cases, it is likely that for textual content
3.120 +such as XML or related formats (XHTML, SVG, HTML) you will need to
3.121 +instruct the component to use your chosen encoding; for example:</p>
3.122 +<pre> # In the respond method, xml_document is an xml.dom.minidom.Document object...<br /> xml_document.toxml(self.encoding)</pre>
3.123 +<p>This will then generate the appropriate characters in the output <span
3.124 + style="font-style: italic;">and</span> specify the correct encoding
3.125 +for the XML document.</p>
3.126 </body>
3.127 </html>
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/state.html Sat Apr 30 00:21:44 2005 +0000
4.3 @@ -0,0 +1,37 @@
4.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4.5 +<html xmlns="http://www.w3.org/1999/xhtml">
4.6 +<head>
4.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
4.8 + <title>Cookies, Sessions, Users and Persistent Information</title>
4.9 + <meta name="generator"
4.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
4.12 +</head>
4.13 +<body>
4.14 +<h1>Cookies, Sessions, Users and Persistent Information</h1>
4.15 +<p>Due to the nature of the communications mechanisms
4.16 +involved, Web applications do not have automatic or "magic"
4.17 +knowledge about the people or entities accessing them as application
4.18 +users. Moreover, Web applications do not necessarily remember anything
4.19 +about what that user has done before. Due to this behaviour, where
4.20 +every request must tell the application as much as possible for an
4.21 +operation to be carried out, Web applications are referred to as being
4.22 +"stateless".</p>
4.23 +<p>Yet there are a number of ways of maintaining "state" information -
4.24 +that is, to remember the following things:</p>
4.25 +<ul>
4.26 + <li>Some kind of identify for the user, if only to be able to say
4.27 +that such a user has visited before (if not to actually give them a
4.28 +name).</li>
4.29 + <li>Some details about their previous interactions with the
4.30 +application.</li>
4.31 +</ul>
4.32 +<p>Such state information is typically provided using a number of
4.33 +different mechanisms:</p>
4.34 +<ul>
4.35 + <li><a href="cookies.html">Cookies</a></li>
4.36 + <li><a href="sessions.html">Sessions and Persistent Information</a></li>
4.37 + <li><a href="users.html">Users and Authentication</a></li>
4.38 +</ul>
4.39 +</body>
4.40 +</html>