WebStack

docs/sessions-usage.html

733:26865b172666
2007-11-12 paulb [project @ 2007-11-12 00:51:34 by paulb] Added a StringResource class for simple static resources. Introduced base classes for common authentication activities. Merged "app", "path" and "qs" fields into a single "app" field for login and redirection. Added support for OpenID authentication.
     1 <?xml version="1.0" encoding="iso-8859-1"?>     2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">     3 <html xmlns="http://www.w3.org/1999/xhtml"><head>     4   <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />     5   <title>Using Sessions</title>     6   <link href="styles.css" rel="stylesheet" type="text/css" /></head>     7 <body>     8 <h1>Using Sessions</h1>     9 <p>Unlike cookies, session information is always stored on the server    10 and is not communicated back to the user. Consequently, sessions have    11 several advantages over cookies, and the uses of sessions may include    12 the storage of...</p>    13 <ul>    14   <li>Sensitive or private information. Although such information can    15 be stored without needing to    16 encrypt it, in many applications you will still want to    17 encrypt such information anyway, no matter where it is stored or how it    18 is communicated.</li>    19   <li>Large amounts of session information can be stored, or at least    20 larger amounts than are typically allowed using cookies.</li>    21 </ul>    22 <div class="WebStack">    23 <h3>WebStack API - Using Sessions</h3>    24 <p>In WebStack, a session appears as a dictionary to applications and    25 is acquired for a specific user through the <a href="../apidocs/public/WebStack.Generic.Transaction-class.html">transaction</a>    26 object. The following methods are provided in the transaction for    27 accessing and maintenance of session information:</p>    28 <dl>    29   <dt><code>get_session</code></dt>    30   <dd>This method returns the session for the identified user. The <code>create</code>    31 parameter can be set to a true value to create a new session for a user    32 if no session previously existed; otherwise <code>None</code> is    33 returned in such situations.</dd>    34   <dt><code>expire_session</code></dt>    35   <dd>This method causes the session information associated with the    36 identified user to be forgotten. Note that this may not really happen    37 until the user sends another request, and that the <code>get_session</code>    38 method may still return the current session.</dd>    39 </dl>    40 <p>Session objects, which resemble dictionaries, employ plain Python    41 strings as keys in the accessing of information, and as the values    42 loaded and stored inside the session. Unlike cookies, upon setting    43 information within a session, such information is remembered thereafter    44 without any other actions being necessary to make that information    45 permanent or persistent.</p>    46 <dl>    47 </dl>    48 </div>    49 <h2>How and When to Access Sessions</h2>    50 <p>To find out if a session has already been created, ask for a session    51 by specifying that one should not be automatically created:</p>    52 <pre>        # In the respond method...<br />        session = trans.get_session(create=0)    # session is None if no session already exists</pre>    53 <p>To ensure that a session exists, just ask for a session:</p>    54 <pre>        # In the respond method...<br />        session = trans.get_session()            # this is the same as using create=1</pre>    55 <p>Session contents may mostly be accessed like dictionaries, so to    56 access the keys within a session the following code could be used:</p>    57 <pre>        # In the respond method after obtaining a session...<br />        for key in session.keys():<br />            [Do something with the key - perhaps obtain values.]</pre>    58 <p>To test the presence of a key, and to access values associated with    59 a key, the usual dictionary methods apply:</p>    60 <pre>        # In the respond method after obtaining the session...<br />        if session.has_key("my_data"):<br />            my_data = session["my_data"]<br />            [Do something with my_data.]<br />            session["my_data"] = my_data</pre>    61 <p>The session for the user may be removed or "expired" as follows:</p>    62 <pre>        # In the respond method...<br />        trans.expire_session()</pre>    63 <p>Note that WebStack automatically knows which session is to be    64 expired since only one such session can exist for the identified user.</p>    65 <h2><a name="Limitations"></a>Session Limitations and Guidelines</h2>    66 <ul>    67   <li>Due to various limitations in the storage of session information,    68 it is recommended that each item of data is converted to a string value    69 when being set in the session, and that the key employed is also a    70 string value. These limitations may be removed in a later release.</li>    71 </ul>    72     73 </body></html>