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.