TileStache.Caches module¶
The cache bits of TileStache.
A Cache is the part of TileStache that stores static files to speed up future requests. A few default caches are found here, but it’s possible to define your own and pull them into TileStache dynamically by class name.
Built-in providers: - test - disk - multi - memcache - s3
Example built-in cache, for JSON configuration file:
- “cache”: {
- “name”: “Disk”, “path”: “/tmp/stache”, “umask”: “0000”
}
Example external cache, for JSON configuration file:
- “cache”: {
- “class”: “Module:Classname”, “kwargs”: {“frob”: “yes”}
}
- The “class” value is split up into module and classname, and dynamically included. If this doesn’t work for some reason, TileStache will fail loudly to let you know.
- The “kwargs” value is fed to the class constructor as a dictionary of keyword args. If your defined class doesn’t accept any of these keyword arguments, TileStache will throw an exception.
A cache must provide these methods: lock(), unlock(), read(), and save(). Each method accepts three arguments:
- layer: instance of a Layer.
- coord: single Coordinate that represents a tile.
- format: string like “png” or “jpg” that is used as a filename extension.
The save() method accepts an additional argument before the others:
- body: raw content to save to the cache.
TODO: add stale_lock_timeout and cache_lifespan to cache API in v2.
-
class
TileStache.Caches.Disk(path, umask=18, dirs='safe', gzip=['txt', 'text', 'json', 'xml'])¶ Caches files to disk.
Example configuration:
- “cache”: {
- “name”: “Disk”, “path”: “/tmp/stache”, “umask”: “0000”, “dirs”: “portable”
}
Extra parameters: - path: required local directory path where files should be stored. - umask: optional string representation of octal permission mask
for stored files. Defaults to 0022.- dirs: optional string saying whether to create cache directories that are safe, portable or quadtile. For an example tile 12/656/1582.png, “portable” creates matching directory trees while “safe” guarantees directories with fewer files, e.g. 12/000/656/001/582.png. Defaults to safe.
- gzip: optional list of file formats that should be stored in a compressed form. Defaults to “txt”, “text”, “json”, and “xml”. Provide an empty list in the configuration for no compression.
If your configuration file is loaded from a remote location, e.g. “http://example.com/tilestache.cfg”, the path must be an unambiguous filesystem path, e.g. “file:///tmp/cache“
-
lock(layer, coord, format)¶ Acquire a cache lock for this tile.
Returns nothing, but blocks until the lock has been acquired. Lock is implemented as an empty directory next to the tile file.
-
read(layer, coord, format)¶ Read a cached tile.
-
remove(layer, coord, format)¶ Remove a cached tile.
-
save(body, layer, coord, format)¶ Save a cached tile.
-
unlock(layer, coord, format)¶ Release a cache lock for this tile.
Lock is implemented as an empty directory next to the tile file.
-
class
TileStache.Caches.Multi(tiers)¶ Caches tiles to multiple, ordered caches.
Multi cache is well-suited for a speed-to-capacity gradient, for example a combination of Memcache and S3 to take advantage of the high speed of memcache and the high capacity of S3. Each tier of caching is checked sequentially when reading from the cache, while all tiers are used together for writing. Locks are only used with the first cache.
Example configuration:
- “cache”: {
“name”: “Multi”, “tiers”: [
- {
- “name”: “Memcache”, “servers”: [“127.0.0.1:11211”]
}, {
“name”: “Disk”, “path”: “/tmp/stache”}
]
}
Multi cache parameters:
- tiers
- Required list of cache configurations. The fastest, most local cache should be at the beginning of the list while the slowest or most remote cache should be at the end. Memcache and S3 together make a great pair.
-
lock(layer, coord, format)¶ Acquire a cache lock for this tile in the first tier.
Returns nothing, but blocks until the lock has been acquired.
-
read(layer, coord, format)¶ Read a cached tile.
Start at the first tier and work forwards until a cached tile is found. When found, save it back to the earlier tiers for faster access on future requests.
-
remove(layer, coord, format)¶ Remove a cached tile from every tier.
-
save(body, layer, coord, format)¶ Save a cached tile.
Every tier gets a saved copy.
-
unlock(layer, coord, format)¶ Release a cache lock for this tile in the first tier.
-
class
TileStache.Caches.Test(logfunc=None)¶ Simple cache that doesn’t actually cache anything.
Activity is optionally logged, though.
Example configuration:
- “cache”: {
- “name”: “Test”, “verbose”: true
}
Extra configuration parameters: - verbose: optional boolean flag to write cache activities to a logging
function, defaults to False if omitted.-
lock(layer, coord, format)¶ Pretend to acquire a cache lock for this tile.
-
read(layer, coord, format)¶ Pretend to read a cached tile.
-
remove(layer, coord, format)¶ Pretend to remove a cached tile.
-
save(body, layer, coord, format)¶ Pretend to save a cached tile.
-
unlock(layer, coord, format)¶ Pretend to release a cache lock for this tile.
-
TileStache.Caches.getCacheByName(name)¶ Retrieve a cache object by name.
Raise an exception if the name doesn’t work out.