`beaker` – Caching¶

Beaker¶

Cache¶

This package contains the “front end” classes and functions for Beaker caching.

Included are the Cache and CacheManager classes, as well as the function decorators region_decorate(), region_invalidate().

class beaker.cache.Cache(namespace, type='memory', expiretime=None, starttime=None, expire=None, **nsargs)¶

Front-end to the containment API implementing a data cache.

Parameters:	namespace – the namespace of this Cache type – type of cache to use expire – seconds to keep cached data expiretime – seconds to keep cached data (legacy support) starttime – time when cache was cache was

clear()¶: Clear all the values from the namespace

get(key, **kw)¶: Retrieve a cached value from the container

get_value(key, **kw)¶: Retrieve a cached value from the container

class beaker.cache.CacheManager(**kwargs)¶

cache(*args, **kwargs)¶

Decorate a function to cache itself with supplied parameters

Parameters:	args – Used to make the key unique for this function, as in region() above. kwargs – Parameters to be passed to get_cache(), will override defaults

Example:

# Assuming a cache object is available like:
cache = CacheManager(dict_of_config_options)


def populate_things():

    @cache.cache('mycache', expire=15)
    def load(search_term, limit, offset):
        return load_the_data(search_term, limit, offset)

    return load('rabbits', 20, 0)

Note

The function being decorated must only be called with positional arguments.

invalidate(func, *args, **kwargs)¶

Invalidate a cache decorated function

This function only invalidates cache spaces created with the cache decorator.

Parameters:	func – Decorated function to invalidate args – Used to make the key unique for this function, as in region() above. kwargs – Parameters that were passed for use by get_cache(), note that this is only required if a `type` was specified for the function

Example:

# Assuming a cache object is available like:
cache = CacheManager(dict_of_config_options)


def populate_things(invalidate=False):

    @cache.cache('mycache', type="file", expire=15)
    def load(search_term, limit, offset):
        return load_the_data(search_term, limit, offset)

    # If the results should be invalidated first
    if invalidate:
        cache.invalidate(load, 'mycache', 'rabbits', 20, 0, type="file")
    return load('rabbits', 20, 0)

region(region, *args)¶

Decorate a function to cache itself using a cache region

The region decorator requires arguments if there are more than two of the same named function, in the same module. This is because the namespace used for the functions cache is based on the functions name and the module.

Example:

# Assuming a cache object is available like:
cache = CacheManager(dict_of_config_options)


def populate_things():

    @cache.region('short_term', 'some_data')
    def load(search_term, limit, offset):
        return load_the_data(search_term, limit, offset)

    return load('rabbits', 20, 0)

Note

The function being decorated must only be called with positional arguments.

region_invalidate(namespace, region, *args)¶

Invalidate a cache region namespace or decorated function

This function only invalidates cache spaces created with the cache_region decorator.

Parameters:	namespace – Either the namespace of the result to invalidate, or the cached function region – The region the function was cached to. If the function was cached to a single region then this argument can be None args – Arguments that were used to differentiate the cached function as well as the arguments passed to the decorated function

Example:

# Assuming a cache object is available like:
cache = CacheManager(dict_of_config_options)

def populate_things(invalidate=False):

    @cache.region('short_term', 'some_data')
    def load(search_term, limit, offset):
        return load_the_data(search_term, limit, offset)

    # If the results should be invalidated first
    if invalidate:
        cache.region_invalidate(load, None, 'some_data',
                                'rabbits', 20, 0)
    return load('rabbits', 20, 0)

Container¶

Container and Namespace classes

beaker.container.ContainerContext¶: alias of __builtin__.dict

class beaker.container.Container¶

Implements synchronization and value-creation logic for a ‘value’ stored in a NamespaceManager.

Container and its subclasses are deprecated. The Value class is now used for this purpose.

class beaker.container.MemoryContainer¶

class beaker.container.DBMContainer¶

class beaker.container.NamespaceManager(namespace)¶

Handles dictionary operations and locking for a namespace of values.

NamespaceManager provides a dictionary-like interface, implementing __getitem__(), __setitem__(), and __contains__(), as well as functions related to lock acquisition.

The implementation for setting and retrieving the namespace data is handled by subclasses.

NamespaceManager may be used alone, or may be accessed by one or more Value objects. Value objects provide per-key services like expiration times and automatic recreation of values.

Multiple NamespaceManagers created with a particular name will all share access to the same underlying datasource and will attempt to synchronize against a common mutex object. The scope of this sharing may be within a single process or across multiple processes, depending on the type of NamespaceManager used.

The NamespaceManager itself is generally threadsafe, except in the case of the DBMNamespaceManager in conjunction with the gdbm dbm implementation.

class beaker.container.MemoryNamespaceManager(namespace, **kwargs)¶: NamespaceManager that uses a Python dictionary for storage.

class beaker.container.DBMNamespaceManager(namespace, dbmmodule=None, data_dir=None, dbm_dir=None, lock_dir=None, digest_filenames=True, **kwargs)¶: NamespaceManager that uses dbm files for storage.

class beaker.container.FileContainer¶

class beaker.container.FileNamespaceManager(namespace, data_dir=None, file_dir=None, lock_dir=None, digest_filenames=True, **kwargs)¶

NamespaceManager that uses binary files for storage.

Each namespace is implemented as a single file storing a dictionary of key/value pairs, serialized using the Python pickle module.

class beaker.container.CreationAbortedError¶: Deprecated.

Database¶

class beaker.ext.database.DatabaseNamespaceManager(namespace, url=None, sa_opts=None, optimistic=False, table_name='beaker_cache', data_dir=None, lock_dir=None, schema_name=None, **params)¶

class beaker.ext.database.DatabaseContainer¶

Memcached¶

class beaker.ext.memcached.MemcachedNamespaceManager(namespace, url, memcache_module='auto', data_dir=None, lock_dir=None, **kw)¶: Provides the NamespaceManager API over a memcache client library.

class beaker.ext.memcached.MemcachedContainer¶: Container class which invokes MemcacheNamespaceManager.

Middleware¶

class beaker.middleware.CacheMiddleware(app, config=None, environ_key='beaker.cache', **kwargs)¶

class beaker.middleware.SessionMiddleware(wrap_app, config=None, environ_key='beaker.session', **kwargs)¶

Session¶

class beaker.session.SignedCookie(secret, input=None)¶: Extends python cookie to give digital signature support

class beaker.session.Session(request, id=None, invalidate_corrupt=False, use_cookies=True, type=None, data_dir=None, key='beaker.session.id', timeout=None, save_accessed_time=True, cookie_expires=True, cookie_domain=None, cookie_path='/', data_serializer='pickle', secret=None, secure=False, namespace_class=None, httponly=False, encrypt_key=None, validate_key=None, encrypt_nonce_bits=128, crypto_type='default', samesite='Lax', **namespace_args)¶

Session object that uses container package for storage.

Parameters:

invalidate_corrupt (bool) – How to handle corrupt data when loading. When set to True, then corrupt data will be silently invalidated and a new session created, otherwise invalid data will cause an exception.
use_cookies (bool) – Whether or not cookies should be created. When set to False, it is assumed the user will handle storing the session on their own.
type – What data backend type should be used to store the underlying session data
key – The name the cookie should be set to.
timeout (int or None) – How long session data is considered valid. This is used regardless of the cookie being present or not to determine whether session data is still valid. Can be set to None to disable session time out.
save_accessed_time – Whether beaker should save the session’s access time (True) or only modification time (False). Defaults to True.
cookie_expires – Expiration date for cookie
cookie_domain – Domain to use for the cookie.
cookie_path – Path to use for the cookie.
data_serializer – If "json" or "pickle" should be used to serialize data. Can also be an object with loads` and ``dumps methods. By default "pickle" is used.
secure – Whether or not the cookie should only be sent over SSL.
httponly – Whether or not the cookie should only be accessible by the browser not by JavaScript.
encrypt_key – The key to use for the local session encryption, if not provided the session will not be encrypted.
validate_key – The key used to sign the local encrypted session
encrypt_nonce_bits – Number of bits used to generate nonce for encryption key salt. For security reason this is 128bits be default. If you want to keep backward compatibility with sessions generated before 1.8.0 set this to 48.
crypto_type – encryption module to use
samesite – SameSite value for the cookie – should be either ‘Lax’, ‘Strict’, or None.

class beaker.session.SessionObject(environ, **params)¶

Session proxy/lazy creator

This object proxies access to the actual session object, so that in the case that the session hasn’t been used before, it will be setup. This avoid creating and loading the session from persistent storage unless its actually used during the request.

beaker.session.b64decode(s, altchars=None)¶

Decode a Base64 encoded string.

s is the string to decode. Optional altchars must be a string of at least length 2 (additional characters are ignored) which specifies the alternative alphabet used instead of the ‘+’ and ‘/’ characters.

The decoded string is returned. A TypeError is raised if s is incorrectly padded. Characters that are neither in the normal base-64 alphabet nor the alternative alphabet are discarded prior to the padding check.

beaker.session.b64encode(s, altchars=None)¶

Encode a string using Base64.

s is the string to encode. Optional altchars must be a string of at least length 2 (additional characters are ignored) which specifies an alternative alphabet for the ‘+’ and ‘/’ characters. This allows an application to e.g. generate url or filesystem safe Base64 strings.

The encoded string is returned.

Synchronization¶

Synchronization functions.

File- and mutex-based mutual exclusion synchronizers are provided, as well as a name-based mutex which locks within an application based on a string name.

class beaker.synchronization.NameLock(identifier=None, reentrant=False)¶

a proxy for an RLock object that is stored in a name based registry.

Multiple threads can get a reference to the same RLock based on the name alone, and synchronize operations related to that name.

class beaker.synchronization.SynchronizerImpl¶: Base class for a synchronization object that allows multiple readers, single writers.

class beaker.synchronization.FileSynchronizer(identifier, lock_dir)¶: A synchronizer which locks using flock().

class beaker.synchronization.ConditionSynchronizer(identifier)¶: a synchronizer using a Condition.

Util¶

Beaker utilities

class beaker.util.SyncDict¶

An efficient/threadsafe singleton map algorithm, a.k.a. “get a value based on this key, and create if not found or not valid” paradigm:

exists && isvalid ? get : create

Designed to work with weakref dictionaries to expect items to asynchronously disappear from the dictionary.

Use python 2.3.3 or greater ! a major bug was just fixed in Nov. 2003 that was driving me nuts with garbage collection/weakrefs in this section.

class beaker.util.WeakValuedRegistry¶

class beaker.util.ThreadLocal¶: stores a value on a per-thread basis

beaker.util.verify_directory(dir)¶: verifies and creates a directory. tries to ignore collisions with other threads and processes.

beaker.util.encoded_path(root, identifiers, extension='.enc', depth=3, digest_filenames=True)¶: Generate a unique file-accessible path from the given list of identifiers starting at the given root directory.

beaker.util.verify_options(opt, types, error)¶

beaker.util.verify_rules(params, ruleset)¶

beaker.util.coerce_session_params(params)¶

beaker.util.coerce_cache_params(params)¶

Table of Contents

Previous topic

Next topic

`beaker` – Caching¶

Beaker¶

Cache¶

Container¶

Database¶

Memcached¶

Middleware¶

Session¶

Synchronization¶

Util¶

beaker – Caching¶

Beaker¶

Cache¶

Container¶

Database¶

Memcached¶

Middleware¶

Session¶

Synchronization¶

Util¶

`beaker` – Caching¶