TileStache.Caches
index

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.

 
Modules
       
TileStache.Memcache
TileStache.Redis
TileStache.S3
gzip
os
sys
time

 
Classes
       
Disk
Multi
Test

 
class Disk
    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"
 
  Methods defined here:
__init__(self, path, umask=18, dirs='safe', gzip=['txt', 'text', 'json', 'xml'])
lock(self, 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(self, layer, coord, format)
Read a cached tile.
remove(self, layer, coord, format)
Remove a cached tile.
save(self, body, layer, coord, format)
Save a cached tile.
unlock(self, layer, coord, format)
Release a cache lock for this tile.
 
Lock is implemented as an empty directory next to the tile file.

 
class Multi
    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.
 
  Methods defined here:
__init__(self, tiers)
lock(self, 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(self, 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(self, layer, coord, format)
Remove a cached tile from every tier.
save(self, body, layer, coord, format)
Save a cached tile.
 
Every tier gets a saved copy.
unlock(self, layer, coord, format)
Release a cache lock for this tile in the first tier.

 
class Test
    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.
 
  Methods defined here:
__init__(self, logfunc=None)
lock(self, layer, coord, format)
Pretend to acquire a cache lock for this tile.
read(self, layer, coord, format)
Pretend to read a cached tile.
remove(self, layer, coord, format)
Pretend to remove a cached tile.
save(self, body, layer, coord, format)
Pretend to save a cached tile.
unlock(self, layer, coord, format)
Pretend to release a cache lock for this tile.

 
Functions
       
getCacheByName(name)
Retrieve a cache object by name.
 
Raise an exception if the name doesn't work out.