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.