Beaker can be configured several different ways, depending on how it’s used. The most recommended style is to use a dictionary of preferences that are to be passed to either the SessionMiddleware or the CacheManager.
Since both Beaker’s sessions and caching use the same back-end container storage system, there’s some options that are applicable to both of them in addition to session and cache specific configuration.
Most options can be specified as a string (necessary to config options that are setup in INI files), and will be coerced to the appropriate value. Only datetime’s and timedelta’s cannot be coerced and must be the actual objects.
Frameworks using Beaker usually allow both caching and sessions to be configured in the same spot, Beaker assumes this condition as well and requires options for caching and sessions to be prefixed appropriately.
For example, to configure the cookie_expires option for Beaker sessions below, an appropriate entry in a Pylons INI file would be:
# Setting cookie_expires = true causes Beaker to omit the
# expires= field from the Set-Cookie: header, signaling the cookie
# should be discarded when the browser closes.
beaker.session.cookie_expires = true
Note
When using the options in a framework like Pylons or TurboGears2, these options must be prefixed by beaker., for example in a Pylons INI file:
beaker.session.data_dir = %(here)s/data/sessions/data
beaker.session.lock_dir = %(here)s/data/sessions/lock
Or when using stand-alone with the SessionMiddleware:
from beaker.middleware import SessionMiddleware
session_opts = {
'session.cookie_expires': True
}
app = SomeWSGIAPP()
app = SessionMiddleware(app, session_opts)
Or when using the CacheManager:
from beaker.cache import CacheManager
from beaker.util import parse_cache_config_options
cache_opts = {
'cache.type': 'file',
'cache.data_dir': '/tmp/cache/data',
'cache.lock_dir': '/tmp/cache/lock'
}
cache = CacheManager(**parse_cache_config_options(cache_opts))
Note
When using the CacheManager directly, all dict options must be run through the beaker.util.parse_cache_config_options() function to ensure they’re valid and of the appropriate type.
The name of the back-end to use for storing the sessions or cache objects.
Available back-ends supplied with Beaker: file, dbm, memory, ext:memcached, ext:database, ext:google
For sessions, the additional type of cookie is available which will store all the session data in the cookie itself. As such, size limitations apply (4096 bytes).
Some of these back-ends require the url option as listed below.
URL is specific to use of either ext:memcached or ext:database. When using one of those types, this option is required.
When used with ext:memcached, this should be either a single, or semi-colon separated list of memcached servers:
session_opts = {
'session.type': 'ext:memcached',
'session.url': '127.0.0.1:11211',
}
When used with ext:database, this should be a valid SQLAlchemy database string.
The Session handling takes a variety of additional options relevant to how it stores session id’s in cookies, and when using the optional encryption.
When set to True, the session will save itself anytime it is accessed during a request, negating the need to issue the save() method.
Defaults to False.
Determines when the cookie used to track the client-side of the session will expire. When set to a boolean value, it will either expire at the end of the browsers session, or never expire.
Setting to a datetime forces a hard ending time for the session (generally used for setting a session to a far off date).
Setting to an integer will result in the cookie being set to expire in that many seconds. I.e. a value of 300 will result in the cookie being set to expire in 300 seconds.
Defaults to never expiring.
What domain the cookie should be set to. When using sub-domains, this should be set to the main domain the cookie should be valid for. For example, if a cookie should be valid under www.nowhere.com and files.nowhere.com then it should be set to .nowhere.com.
Defaults to the current domain in its entirety.
Alternatively, the domain can be set dynamically on the session by calling, see Session Attributes / Keys.
Used with the HMAC to ensure session integrity. This value should ideally be a randomly generated string.
When using in a cluster environment, the secret must be the same on every machine.
Seconds until the session is considered invalid, after which it will be ignored and invalidated. This number is based on the time since the session was last accessed, not from when the session was created.
Defaults to never expiring.
These options should then be used instead of the secret option listed above.
Note
You may need to install additional libraries to use Beaker’s cookie-based session encryption. See the Encryption section for more information.
For caching, options may be directly specified on a per-use basis with the cache() decorator, with the rest of these options used as fallback should one of them not be specified in the call.
Only the lock_dir option is strictly required, unless using the file-based back-ends as noted with the sessions.
Starting in Beaker 1.3, cache regions are now supported. These can be thought of as bundles of configuration options to apply, rather than specifying the type and expiration on a per-usage basis.
Quick toggle to disable or enable caching across an entire application.
This should generally be used when testing an application or in development when caching should be ignored.
Defaults to True.
Names of the regions that are to be configured.
For each region, all of the other cache options are valid and will be read out of the cache options for that key. Options that are not listed under a region will be used globally in the cache unless a region specifies a different value.
For example, to specify two batches of options, one called long-term, and one called short-term:
cache_opts = {
'cache.data_dir': '/tmp/cache/data',
'cache.lock_dir': '/tmp/cache/lock'
'cache.regions': 'short_term, long_term',
'cache.short_term.type': 'ext:memcached',
'cache.short_term.url': '127.0.0.1.11211',
'cache.short_term.expire': '3600',
'cache.long_term.type': 'file',
'cache.long_term.expire': '86400',