pyramid_beaker
==============

Overview
--------

A :term:`Beaker` session factory backend for :term:`Pyramid`, also cache
configurator.

Installation
------------

Install using setuptools, e.g. (within a virtualenv)::

  $ easy_install pyramid_beaker

Setup
-----

Once :mod:`pyramid_beaker` is installed, you must use the ``config.include`` 
mechanism to include it into your Pyramid project's configuration. In your 
Pyramid project's ``__init__.py``:

.. code-block:: python

   config = Configurator(.....)
   config.include('pyramid_beaker')

Alternately, instead of using the Configurator's ``include`` method, you can
activate Pyramid by changing your application's ``.ini`` file, use the
following line:

.. code-block:: ini

   pyramid.includes = pyramid_beaker

Usage
-----

Session management
``````````````````

In the configuration portion of your :term:`Pyramid` app, if you are not using 
the default activation setup, use the 
:func:`pyramid_beaker.BeakerSessionFactoryConfig` function or the
:func:`pyramid_beaker.session_factory_from_settings` function to
create a Pyramid :term:`session factory`.  Subsequently register that
session factory with Pyramid.  At that point, accessing
``request.session`` will provide a Pyramid session using Beaker as a
backend.

:func:`pyramid_beaker.session_factory_from_settings` obtains session
settings from the ``**settings`` dictionary passed to the
Configurator.  It assumes that you've placed session configuration
parameters prefixed with ``session.`` in your Pyramid application's
``.ini`` file.  For example:

.. code-block:: ini

   [app:myapp]
   .. other settings ..
   session.type = file
   session.data_dir = %(here)s/data/sessions/data
   session.lock_dir = %(here)s/data/sessions/lock
   session.key = mykey
   session.secret = mysecret
   session.cookie_on_exception = true

If your ``.ini`` file has such settings, you can use
:func:`pyramid_beaker.session_factory_from_settings` in your
application's configuration.  For example, let's assume this code is
in the ``__init__.py`` of your Pyramid application that uses an
``.ini`` file with the ``session.`` settings above to obtain its
``**settings`` dictionary.

.. code-block:: python

   from pyramid_beaker import session_factory_from_settings
   from pyramid.config import Configurator

   def app(global_config, **settings):
       """ This function returns a WSGI application.
       
       It is usually called by the PasteDeploy framework during 
       ``paster serve``.
       """
       session_factory = session_factory_from_settings(settings)
       config = Configurator(root_factory=get_root, settings=settings)
       config.set_session_factory(session_factory)
       # ... other configuration stuff...
       return config.make_wsgi_app()

The ``cookie_on_exception`` option is specific to ``pyramid_beaker`` (as
opposed to all other options, which are specific to Beaker itself).  It
indicates that the session cookie should be set even when a Pyramid exception
view is being rendered.  The default is ``True``, meaning that session
cookies will be sent back in responses generated by exception views.

Beaker cache region support
```````````````````````````

In the configuration portion of your :term:`Pyramid` app, if you are not using 
the default activation setup, use the 
:func:`pyramid_beaker.set_cache_regions_from_settings` function to
set Beaker's cache regions. At that point, you can use Beaker's `cache_region`
functionality to enable caching for Your application. 

:func:`pyramid_beaker.set_cache_regions_from_settings` obtains region
settings from the ``**settings`` dictionary passed to the
Configurator.  It assumes that you've placed cache configuration
parameters prefixed with ``cache.`` in your Pyramid application's
``.ini`` file.  For example:

.. code-block:: ini

   [app:myapp]
   .. other settings ..
   cache.regions = default_term, second, short_term, long_term
   cache.type = memory
   cache.second.expire = 1
   cache.short_term.expire = 60
   cache.default_term.expire = 300
   cache.long_term.expire = 3600

If your ``.ini`` file has such settings, you can use
:func:`pyramid_beaker.set_cache_regions_from_settings` in your
application's configuration.  For example, let's assume this code is
in the ``__init__.py`` of your Pyramid application that uses an
``.ini`` file with the ``cache.`` settings above to obtain its
``**settings`` dictionary.

.. code-block:: python

   from pyramid_beaker import set_cache_regions_from_settings
   from pyramid.configuration import configurator

   def app(global_config, **settings):
       """ This function returns a WSGI application.
       
       It is usually called by the PasteDeploy framework during 
       ``paster serve``.
       """
       set_cache_regions_from_settings(settings)
       config = Configurator(root_factory=get_root, settings=settings)
       # ... other configuration stuff...
       return config.make_wsgi_app()

Inherited region settings
~~~~~~~~~~~~~~~~~~~~~~~~~

The following optional region settings inherit from the main cache
configuration or default as specified:

``data_dir``
  Inherits if specified.

``enabled``
	Inherits or defaults to True.

``expire``
  Inherits or defaults to 60 seconds.

``key_length``
  Inherits or defaults to 250 characters.

``lock_dir``
  Inherits if specified.

``type``
  Inherits or defaults to ``memory``.

``url``
  Inherits if specified.

API
---

.. toctree::
   :maxdepth: 2

   api.rst

Indices and tables
------------------

* :ref:`glossary`
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. toctree::
   :hidden:

   glossary