- Added a tutorial which explains how to use ``repoze.session``

  (ZODB-based sessions) in a ZODB-based repoze.bfg app.

2 files changed, 203 insertions, 13 deletions

diff --git a/docs/tutorials/zeo/index.rst b/docs/tutorials/zeo/index.rst
index edf499c7f..36d681acb 100644
--- a/docs/tutorials/zeo/index.rst
+++ b/docs/tutorials/zeo/index.rst
@@ -62,6 +62,9 @@ Installing Dependencies
    of this tutorial, we'll assume that your "application" is actually
    just the result of the ``bfg_starter`` Paster template.
 
+Configuration
+-------------
+
 #. Edit your application's Paste ``.ini`` file.
 
    If you already have an ``app`` section in the ``.ini`` file named
@@ -179,6 +182,9 @@ Installing Dependencies
                root['myapp'] = MyModel()
                transaction.commit()
            return root['myapp']
+
+Running
+-------
     
 #.  Start the ZEO server in a terminal with the current directory set
     to the package directory:
@@ -193,17 +199,17 @@ Installing Dependencies
     .. code-block:: bash
        :linenos:
 
-      [chrism@snowpro myapp]$ ../bin/runzeo -C zeo.conf 
-      ------
-      2009-09-19T13:48:41 INFO ZEO.runzeo (9910) created PID file './zeo.pid'
-      ------
-      2009-09-19T13:48:41 INFO ZEO.runzeo (9910) opening storage '1' using BlobStorage
-      ------
-      2009-09-19T13:48:41 WARNING ZODB.FileStorage Ignoring index for ./myapp.db
-      ------
-      2009-09-19T13:48:41 INFO ZEO.StorageServer (9910) StorageServer created RW with storages: 1:RW:./myapp.db
-      ------
-      2009-09-19T13:48:41 INFO ZEO.zrpc (9910) listening on ./zeo.sock
+       [chrism@snowpro myapp]$ ../bin/runzeo -C zeo.conf 
+       ------
+       2009-09-19T13:48:41 INFO ZEO.runzeo (9910) created PID file './zeo.pid'
+       ------
+       2009-09-19T13:48:41 INFO ZEO.runzeo (9910) opening storage '1' using BlobStorage
+       ------
+       2009-09-19T13:48:41 WARNING ZODB.FileStorage Ignoring index for ./myapp.db
+       ------
+       2009-09-19T13:48:41 INFO ZEO.StorageServer (9910) StorageServer created RW with storages: 1:RW:./myapp.db
+       ------
+       2009-09-19T13:48:41 INFO ZEO.zrpc (9910) listening on ./zeo.sock
 
 #.  While the ZEO server is running, start the application server:
 
@@ -217,8 +223,9 @@ Installing Dependencies
 #.  The root object is now a "folderish" ZODB object.  Nothing else
     about the application has changed.  
 
-#.  You can manipulate the database directly by using the ``bfgshell``
-    command in a separate terminal window:
+#.  You can manipulate the database directly (even when the
+    application's HTTP server is running) by using the ``bfgshell``
+    command in a third terminal window:
 
     .. code-block:: bash
        :linenos:
diff --git a/docs/tutorials/zodbsessions/index.rst b/docs/tutorials/zodbsessions/index.rst
new file mode 100644
index 000000000..362fd7e1d
--- /dev/null
+++ b/docs/tutorials/zodbsessions/index.rst
@@ -0,0 +1,183 @@
+.. _zodb_sessions:
+
+Using ZODB-Based Sessions
+=========================
+
+Sessions are server-side namespaces which are associated with a site
+user that expire automatically after some period of disuse.
+
+If your application is ZODB-based (e.g. you've created an application
+from the ``bfg_zodb`` paster template, or you've follow the
+instructions in :ref:`zodb_with_zeo`), you can make use of the
+``repoze.session`` and ``repoze.browserid`` packages to add
+sessioning to your application.
+
+.. note:: You can use the ``repoze.session`` package even if your
+   application is not ZODB-based, but its backing store requires ZODB,
+   so it makes the most sense to use this package if your application
+   already uses ZODB.  This tutorial does not cover usage of
+   ``repoze.session``-based sessions in applications that don't
+   already use ZODB.  For this, see `the standalone repoze.session
+   usage documentation <http://docs.repoze.org/session/usage.html>`_.
+
+Installing Dependencies
+-----------------------
+
+#. Edit your :mod:`repoze.bfg` application's ``setup.py`` file, adding
+   the following packages to the ``install_requires`` of the
+   application:
+
+   - ``repoze.session``
+
+   - ``repoze.browserid``
+
+   For example, the relevant portion of your application's
+   ``setup.py`` file might look like so when you're finished adding
+   the dependencies.
+
+   .. code-block:: python
+      :linenos:
+
+      setup(
+          # ... other elements left out for brevity
+          install_requires=[
+                'repoze.bfg',
+                'repoze.folder',
+                'repoze.retry',
+                'repoze.tm2',
+                'repoze.zodbconn',
+                'repoze.session'
+                'repoze.browserid',
+                ],
+          # ... other elements left out for brevity
+           )
+
+#. Rerun your application's ``setup.py`` file (e.g. using ``python
+   setup.py develop``) to get these packages installed.
+
+Configuration
+-------------
+
+#. Edit your application's Paste ``.ini`` file.
+
+   If you already have an ``app`` section in the ``.ini`` file named
+   ``main``, rename this section to ``myapp`` (e.g. ``app:main`` ->
+   ``app:myapp``).  Add a key to it named ``zodb_uri``, e.g.
+
+   .. code-block:: python
+      :linenos:
+
+      [app:myapp]
+      use = egg:myapp#app
+      zodb_uri = zeo://%(here)s/zeo.sock
+      reload_templates = true
+      debug_authorization = false
+      debug_notfound = false
+
+   Add a ``filter`` section to the ``.ini`` file named "browserid":
+
+   .. code-block:: python
+      :linenos:
+
+      [filter:browserid]
+      use = egg:repoze.browserid#browserid
+      secret_key = my-secret-key
+
+   Replace "my-secret-key" with any random string.
+
+   If a ``pipeline`` named ``main`` does not already exist in the
+   paste ``.ini`` file , add a ``pipeline`` section named ``main``.
+   Put the names ``connector``, ``egg:repoze.retry#retry``, and
+   ``egg:repoze.tm2#tm`` to the top of the pipeline.
+
+   .. code-block:: python
+      :linenos:
+
+      [pipeline:main]
+      pipeline = 
+             browserid
+             egg:repoze.retry#retry
+             egg:repoze.tm2#tm
+             myapp
+
+   When you're finished, your ``.ini`` file might look like so:
+
+   .. code-block:: ini
+      :linenos:
+
+      [DEFAULT]
+      debug = true
+
+      [app:myapp]
+      use = egg:myapp#app
+      zodb_uri = zeo://%(here)s/zeo.sock
+      reload_templates = true
+      debug_authorization = false
+      debug_notfound = false
+
+      [filter:browserid]
+      use = egg:repoze.browserid#browserid
+      secret_key = my-secret-key
+
+      [pipeline:main]
+      pipeline = 
+             browserid
+             egg:repoze.retry#retry
+             egg:repoze.tm2#tm
+             myapp
+
+      [server:main]
+      use = egg:Paste#http
+      host = 0.0.0.0
+      port = 6543
+
+   See :ref:`MyProject_ini` for more information about project Paste
+   ``.ini`` files.
+
+#.  Add a ``get_session`` API to your application.  I've chosed to add
+    it directly to my ``views.py`` file, although it can live anywhere.
+
+    .. code-block:: python
+       :linenos:
+
+       from repoze.session.manager import SessionDataManager
+       from repoze.bfg.traversal import find_root
+
+       def get_session(context, request):
+           root = find_root(context)
+           if not hasattr(root, '_sessions'):
+               root._sessions = SessionDataManager(3600, 5)
+           session = root._sessions.get(request.environ['repoze.browserid'])
+           return session
+
+    Note in the call to ``SessionDataManager`` that '3600' represents
+    the disuse timeout (5 minutes == 3600 seconds), and '5' above
+    represents a write granularity time (the session will be marked as
+    active at most every five seconds).  Vary these values as necessary.
+
+#.  Whenever you want to use a session in your application, call this API:
+
+    .. code-block:: python
+       :linenos:
+
+       from repoze.session.manager import SessionDataManager
+       from repoze.bfg.traversal import find_root
+       from repoze.bfg.chameleon_zpt import render_template_to_response
+
+       def my_view(context, request):
+           session = get_session(context, request)
+           session['abc'] = '123'
+           return render_template_to_response('templates/mytemplate.pt',
+                                              request = request,
+                                              project = 'sess')
+
+       def get_session(context, request):
+           root = find_root(context)
+           if not hasattr(root, '_sessions'):
+               root._sessions = SessionDataManager(3600, 5)
+           session = root._sessions.get(request.environ['repoze.browserid'])
+           return session
+
+For more information, see the `repoze.session documentation
+<http://docs.repoze.org/session/>`_ and the `repoze.browserid
+documentation <http://pypi.python.org/pypi/repoze.browserid>`_.