Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Branch: master
Fetching contributors…

Cannot retrieve contributors at this time

204 lines (152 sloc) 6.069 kB

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 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 :mod:`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 :func:`pyramid_beaker.session_factory_from_settings` is called automatically and you need do nothing else. Otherwise you will need to create a Pyramid :term:`session factory` by adding a call to either the :func:`pyramid_beaker.BeakerSessionFactoryConfig` function or the :func:`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.

: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:

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

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 :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:

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

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

Indices and tables

Jump to Line
Something went wrong with that request. Please try again.