Bytecode Cache

Jinja 2.1 and higher support external bytecode caching. Bytecode caches makeit possible to store the generated bytecode on the file system or a differentlocation to avoid parsing the templates on first use.

This is especially useful if you have a web application that is initialized onthe first request and Jinja compiles many templates at once which slows downthe application.

To use a bytecode cache, instantiate it and pass it to the Environment.

• class jinja2.BytecodeCache
• To implement your own bytecode cache you have to subclass this classand override load_bytecode() and dump_bytecode(). Both ofthese methods are passed a Bucket.

A very basic bytecode cache that saves the bytecode on the file system:

from os import path
class MyCache(BytecodeCache):
    def __init__(self, directory):
        self.directory = directory
    def load_bytecode(self, bucket):
        filename = path.join(self.directory, bucket.key)
        if path.exists(filename):
            with open(filename, 'rb') as f:
                bucket.load_bytecode(f)
    def dump_bytecode(self, bucket):
        filename = path.join(self.directory, bucket.key)
        with open(filename, 'wb') as f:
            bucket.write_bytecode(f)

A more advanced version of a filesystem based bytecode cache is part ofJinja2.

• clear()

• Clears the cache. This method is not used by Jinja2 but should beimplemented to allow applications to clear the bytecode cache usedby a particular environment.

• dumpbytecode(_bucket)

• Subclasses have to override this method to write the bytecodefrom a bucket back to the cache. If it unable to do so it must notfail silently but raise an exception.

• loadbytecode(_bucket)

• Subclasses have to override this method to load bytecode into abucket. If they are not able to find code in the cache for thebucket, it must not do anything.

• class jinja2.bccache.Bucket(environment, key, checksum)
• Buckets are used to store the bytecode for one template. It’s createdand initialized by the bytecode cache and passed to the loading functions.

The buckets get an internal checksum from the cache assigned and use thisto automatically reject outdated cache material. Individual bytecodecache subclasses don’t have to care about cache invalidation.

• environment

• The Environment that created the bucket.

• key

• The unique cache key for this bucket

• code

• The bytecode if it’s loaded, otherwise None.

• bytecodefrom_string(_string)

• Load bytecode from a string.

• bytecode_to_string()

• Return the bytecode as string.

• loadbytecode(_f)

• Loads bytecode from a file or file like object.

• reset()

• Resets the bucket (unloads the bytecode).

• writebytecode(_f)

• Dump the bytecode into the file or file like object passed.

Builtin bytecode caches:

• class jinja2.FileSystemBytecodeCache(directory=None, pattern='__jinja2%s.cache'_)
• A bytecode cache that stores bytecode on the filesystem. It acceptstwo arguments: The directory where the cache items are stored and apattern string that is used to build the filename.

If no directory is specified a default cache directory is selected. OnWindows the user’s temp directory is used, on UNIX systems a directoryis created for the user in the system temp directory.

The pattern can be used to have multiple separate caches operate on thesame directory. The default pattern is '_jinja2%s.cache'. %sis replaced with the cache key.

>>> bcc = FileSystemBytecodeCache('/tmp/jinja_cache', '%s.cache')

This bytecode cache supports clearing of the cache using the clear method.

• class jinja2.MemcachedBytecodeCache(client, prefix='jinja2/bytecode/', timeout=None, ignore_memcache_errors=True)
• This class implements a bytecode cache that uses a memcache cache forstoring the information. It does not enforce a specific memcache library(tummy’s memcache or cmemcache) but will accept any class that providesthe minimal interface required.

Libraries compatible with this class:

• cachelib

• python-memcached

(Unfortunately the django cache interface is not compatible because itdoes not support storing binary data, only unicode. You can however passthe underlying cache client to the bytecode cache which is availableas django.core.cache.cache._client.)

The minimal interface for the client passed to the constructor is this:

• class MinimalClientInterface
• • set(key, value[, timeout])

  • Stores the bytecode in the cache. value is a string andtimeout the timeout of the key. If timeout is not provideda default timeout or no timeout should be assumed, if it’sprovided it’s an integer with the number of seconds the cacheitem should exist.

  • get(key)

  • Returns the value for the cache key. If the item does notexist in the cache the return value must be None.

The other arguments to the constructor are the prefix for all keys thatis added before the actual cache key and the timeout for the bytecode inthe cache system. We recommend a high (or no) timeout.

This bytecode cache does not support clearing of used items in the cache.The clear method is a no-operation function.

Changelog

New in version 2.7: Added support for ignoring memcache errors through theignore_memcache_errors parameter.