pyramid_beaker

Overview

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

Installation

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

$ easy_install pyramid_beaker

Setup

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

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

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

pyramid.includes = pyramid_beaker

Usage

Session management

If you have included pyramid_beaker in your Pyramid project's configuration as shown above then pyramid_beaker.session_factory_from_settings() is called automatically and you need do nothing else. Otherwise you will need to create a Pyramid session factory by adding a call to either the pyramid_beaker.BeakerSessionFactoryConfig() function or the pyramid_beaker.session_factory_from_settings() function in the configuration code of your Pyramid project's __init__.py file and subsequently register that session factory with Pyramid. At that point, accessing request.session will provide a Pyramid session using Beaker as a backend.

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:

[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 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.

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.

Additionally, the constant_csrf_token option can be set to override the CSRF token value with some constant value. This is useful for testing but should not be set in production.

Beaker cache region support

In the configuration portion of your Pyramid app, if you are not using the default activation setup, use the 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.

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:

[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 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.

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.