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.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 or portable. For an example tile 12/656/1582.png, "portable"
creates matching directory trees while "portable" 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.`