1 # -*- coding: utf-8 -*-
6 This module implements the bytecode cache system Jinja is optionally
7 using. This is useful if you have very complex template situations and
8 the compiliation of all those templates slow down your application too
11 Situations where this is useful are often forking web applications that
12 are initialized on the first request.
14 :copyright: Copyright 2008 by Armin Ronacher.
17 from os import path, listdir
20 import cPickle as pickle
22 from cStringIO import StringIO
24 from hashlib import sha1
26 from sha import new as sha1
27 from jinja2.utils import open_if_exists
31 bc_magic = 'j2' + pickle.dumps(bc_version, 2)
35 """Buckets are used to store the bytecode for one template. It's created
36 and initialized by the bytecode cache and passed to the loading functions.
38 The buckets get an internal checksum from the cache assigned and use this
39 to automatically reject outdated cache material. Individual bytecode
40 cache subclasses don't have to care about cache invalidation.
43 def __init__(self, environment, key, checksum):
44 self.environment = environment
46 self.checksum = checksum
50 """Resets the bucket (unloads the bytecode)."""
53 def load_bytecode(self, f):
54 """Loads bytecode from a file or file like object."""
55 # make sure the magic header is correct
56 magic = f.read(len(bc_magic))
60 # the source code of the file changed, we need to reload
61 checksum = pickle.load(f)
62 if self.checksum != checksum:
65 # now load the code. Because marshal is not able to load
66 # from arbitrary streams we have to work around that
67 if isinstance(f, file):
68 self.code = marshal.load(f)
70 self.code = marshal.loads(f.read())
72 def write_bytecode(self, f):
73 """Dump the bytecode into the file or file like object passed."""
75 raise TypeError('can\'t write empty bucket')
77 pickle.dump(self.checksum, f, 2)
78 if isinstance(f, file):
79 marshal.dump(self.code, f)
81 f.write(marshal.dumps(self.code))
83 def bytecode_from_string(self, string):
84 """Load bytecode from a string."""
85 self.load_bytecode(StringIO(string))
87 def bytecode_to_string(self):
88 """Return the bytecode as string."""
90 self.write_bytecode(out)
94 class BytecodeCache(object):
95 """To implement your own bytecode cache you have to subclass this class
96 and override :meth:`load_bytecode` and :meth:`dump_bytecode`. Both of
97 these methods are passed a :class:`~jinja2.bccache.Bucket`.
99 A very basic bytecode cache that saves the bytecode on the file system::
103 class MyCache(BytecodeCache):
105 def __init__(self, directory):
106 self.directory = directory
108 def load_bytecode(self, bucket):
109 filename = path.join(self.directory, bucket.key)
110 if path.exists(filename):
111 with file(filename, 'rb') as f:
112 bucket.load_bytecode(f)
114 def dump_bytecode(self, bucket):
115 filename = path.join(self.directory, bucket.key)
116 with file(filename, 'wb') as f:
117 bucket.write_bytecode(f)
119 A more advanced version of a filesystem based bytecode cache is part of
123 def load_bytecode(self, bucket):
124 """Subclasses have to override this method to load bytecode into a
125 bucket. If they are not able to find code in the cache for the
126 bucket, it must not do anything.
128 raise NotImplementedError()
130 def dump_bytecode(self, bucket):
131 """Subclasses have to override this method to write the bytecode
132 from a bucket back to the cache. If it unable to do so it must not
133 fail silently but raise an exception.
135 raise NotImplementedError()
138 """Clears the cache. This method is not used by Jinja2 but should be
139 implemented to allow applications to clear the bytecode cache used
140 by a particular environment.
143 def get_cache_key(self, name, filename=None):
144 """Returns the unique hash key for this template name."""
145 hash = sha1(name.encode('utf-8'))
146 if filename is not None:
147 if isinstance(filename, unicode):
148 filename = filename.encode('utf-8')
149 hash.update('|' + filename)
150 return hash.hexdigest()
152 def get_source_checksum(self, source):
153 """Returns a checksum for the source."""
154 return sha1(source.encode('utf-8')).hexdigest()
156 def get_bucket(self, environment, name, filename, source):
157 """Return a cache bucket for the given template. All arguments are
158 mandatory but filename may be `None`.
160 key = self.get_cache_key(name, filename)
161 checksum = self.get_source_checksum(source)
162 bucket = Bucket(environment, key, checksum)
163 self.load_bytecode(bucket)
166 def set_bucket(self, bucket):
167 """Put the bucket into the cache."""
168 self.dump_bytecode(bucket)
171 class FileSystemBytecodeCache(BytecodeCache):
172 """A bytecode cache that stores bytecode on the filesystem. It accepts
173 two arguments: The directory where the cache items are stored and a
174 pattern string that is used to build the filename.
176 If no directory is specified the system temporary items folder is used.
178 The pattern can be used to have multiple separate caches operate on the
179 same directory. The default pattern is ``'__jinja2_%s.cache'``. ``%s``
180 is replaced with the cache key.
182 >>> bcc = FileSystemBytecodeCache('/tmp/jinja_cache', '%s.cache')
184 This bytecode cache supports clearing of the cache using the clear method.
187 def __init__(self, directory=None, pattern='__jinja2_%s.cache'):
188 if directory is None:
189 directory = tempfile.gettempdir()
190 self.directory = directory
191 self.pattern = pattern
193 def _get_cache_filename(self, bucket):
194 return path.join(self.directory, self.pattern % bucket.key)
196 def load_bytecode(self, bucket):
197 f = open_if_exists(self._get_cache_filename(bucket), 'rb')
200 bucket.load_bytecode(f)
204 def dump_bytecode(self, bucket):
205 f = file(self._get_cache_filename(bucket), 'wb')
207 bucket.write_bytecode(f)
212 # imported lazily here because google app-engine doesn't support
213 # write access on the file system and the function does not exist
215 from os import remove
216 files = fnmatch.filter(listdir(self.directory), self.pattern % '*')
217 for filename in files:
219 remove(path.join(self.directory, filename))
224 class MemcachedBytecodeCache(BytecodeCache):
225 """This class implements a bytecode cache that uses a memcache cache for
226 storing the information. It does not enforce a specific memcache library
227 (tummy's memcache or cmemcache) but will accept any class that provides
228 the minimal interface required.
230 Libraries compatible with this class:
232 - `werkzeug <http://werkzeug.pocoo.org/>`_.contrib.cache
233 - `python-memcached <http://www.tummy.com/Community/software/python-memcached/>`_
234 - `cmemcache <http://gijsbert.org/cmemcache/>`_
236 (Unfortunately the django cache interface is not compatible because it
237 does not support storing binary data, only unicode. You can however pass
238 the underlying cache client to the bytecode cache which is available
239 as `django.core.cache.cache._client`.)
241 The minimal interface for the client passed to the constructor is this:
243 .. class:: MinimalClientInterface
245 .. method:: set(key, value[, timeout])
247 Stores the bytecode in the cache. `value` is a string and
248 `timeout` the timeout of the key. If timeout is not provided
249 a default timeout or no timeout should be assumed, if it's
250 provided it's an integer with the number of seconds the cache
255 Returns the value for the cache key. If the item does not
256 exist in the cache the return value must be `None`.
258 The other arguments to the constructor are the prefix for all keys that
259 is added before the actual cache key and the timeout for the bytecode in
260 the cache system. We recommend a high (or no) timeout.
262 This bytecode cache does not support clearing of used items in the cache.
263 The clear method is a no-operation function.
266 def __init__(self, client, prefix='jinja2/bytecode/', timeout=None):
269 self.timeout = timeout
271 def load_bytecode(self, bucket):
272 code = self.client.get(self.prefix + bucket.key)
274 bucket.bytecode_from_string(code)
276 def dump_bytecode(self, bucket):
277 args = (self.prefix + bucket.key, bucket.bytecode_to_string())
278 if self.timeout is not None:
279 args += (self.timeout,)
280 self.client.set(*args)