From e2c34fe2e8e44fb03cecd46cc7607d4539f59ded Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 19 Sep 2009 19:55:20 +0000 Subject: - Added a tutorial which explains how to use ``repoze.session`` (ZODB-based sessions) in a ZODB-based repoze.bfg app. --- docs/tutorials/zeo/index.rst | 33 +++--- docs/tutorials/zodbsessions/index.rst | 183 ++++++++++++++++++++++++++++++++++ 2 files changed, 203 insertions(+), 13 deletions(-) create mode 100644 docs/tutorials/zodbsessions/index.rst (limited to 'docs/tutorials') 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 `_. + +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 +`_ and the `repoze.browserid +documentation `_. -- cgit v1.2.3