FileCache

class FileCache(**properties: Any)

Superclasses: Object

A cache that stores and retrieves tiles from the file system. It is mainly used by TileDownloader, but can also be used by custom data sources.

The cache will be filled up to a certain size limit. When this limit is reached, the cache can be purged, and the tiles that are accessed least are deleted.

ETags

The cache can optionally store an ETag string with each tile. This is useful to avoid redownloading old tiles that haven’t changed (for example, using the HTTP If-None-Match header).

Constructors

class FileCache
classmethod new_full(size_limit: int, cache_key: str, cache_dir: str | None = None) → FileCache

Constructor of FileCache.

Parameters:

  • size_limit – maximum size of the cache in bytes

  • cache_key – an ID for the tileset to store/retrieve

  • cache_dir – the directory where the cache is created. When cache_dir == NULL, a cache in ~/.cache/shumate is used.

Methods

class FileCache
get_cache_dir() → str

Gets the directory where the cache database is stored.

get_cache_key() → str

Gets the key used to store and retrieve tiles from the cache. Different keys can be used to store multiple tilesets in the same cache directory.

get_size_limit() → int

Gets the cache size limit in bytes.

get_tile_async(x: int, y: int, zoom_level: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Gets tile data from the cache, if it is available.

Parameters:

  • x – the X coordinate of the tile

  • y – the Y coordinate of the tile

  • zoom_level – the zoom level of the tile

  • cancellable – a Cancellable

  • callback – a AsyncReadyCallback to execute upon completion

  • user_data – closure data for callback

get_tile_finish(result: AsyncResult) → tuple[Bytes, str, DateTime]

Gets the tile data from a completed get_tile_async() operation.

modtime will be set to the time the tile was added to the cache, or the latest time it was confirmed to be up to date.

etag will be set to the data’s ETag, if present.

Parameters:

result – a AsyncResult provided to callback

mark_up_to_date(x: int, y: int, zoom_level: int) → None

Marks a tile in the cache as being up to date, without changing its data.

For example, a network source might call this function when it gets an HTTP 304 Not Modified response.

Parameters:

  • x – the X coordinate of the tile

  • y – the Y coordinate of the tile

  • zoom_level – the zoom level of the tile

purge_cache_async(cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Removes less used tiles from the cache, if necessary, until it fits in the size limit.

Parameters:

  • cancellable – a Cancellable

  • callback – a AsyncReadyCallback to execute upon completion

  • user_data – closure data for callback

purge_cache_finish(result: AsyncResult) → bool

Gets the result of an async operation started using purge_cache_async().

Parameters:

result – a AsyncResult provided to callback

set_size_limit(size_limit: int) → None

Sets the cache size limit in bytes.

Parameters:

size_limit – the cache limit in bytes

store_tile_async(x: int, y: int, zoom_level: int, bytes: Bytes, etag: str | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Stores a tile in the cache.

Parameters:

  • x – the X coordinate of the tile

  • y – the Y coordinate of the tile

  • zoom_level – the zoom level of the tile

  • bytes – a Bytes

  • etag – an ETag string, or None

  • cancellable – a Cancellable

  • callback – a AsyncReadyCallback to execute upon completion

  • user_data – closure data for callback

store_tile_finish(result: AsyncResult) → bool

Gets the success value of a completed store_tile_async() operation.

Parameters:

result – a AsyncResult provided to callback

Properties

class FileCache
props.cache_dir: str

The directory where the tile database is stored.

props.cache_key: str

The key used to store and retrieve tiles from the cache. Different keys can be used to store multiple tilesets in the same cache directory.

props.size_limit: int

The cache size limit in bytes.

Note: this new value will not be applied until you call shumate_file_cache_purge()