Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!


Project description

This is a simple file-based cache implementation that is meant for simple cases where you want to cache some data (maybe you want to avoid hammering an API server with repeated requests) but you don’t want the features and associated configuration tasks associated with a more feature-ful cache module.

## Usage

To get yourself a cache:

>>> from thecache.cache import Cache
>>> mycache = Cache(__name__)

To use the cache for small amounts of data (for memory efficient operations, read the more detailed explanations below):

>>> mycache.put('some key', 'a chunk of data')
>>> if mycache.has('some key'):
...   print 'Content:', mycache.get('some key')
... else:
...   print 'Key "some key" was not in cache'
Content: a chunk of data


>>> try:
...   print 'Content:', mycache.get('some key')
... except KeyError:
...   print 'Key "some key" was not in cache'
Content: a chunk of data

## Storing data

  • store (also put)

    This will write the content of a Python variable to the cache.

  • store_fd

    This will read from an open file in chunksize byte chunks and write the data to the cache.

  • store_iter

    This will iterate over content, writing each chunk of data to the cache. This is a good choice for handling a response from the requests library in streaming mode:

    >>> import requests
    >>> r = requests.get(url, stream=True)
    >>> c.store_iter(url, r.iter_content(chunk_size=8192))
  • store_lines

    This is almost exactly like store_iter, except it appends a newline after writing each chunk of data. This is useful for writing a list of strings to the cache to be read back using the load_lines method:

    >>> mydata = ['one', 'two', 'three', 'four']
    >>> c.store_lines('mykey', mydata)

## Reading data

All of the following functions raise KeyError if you request a key that cannot be found in the cache.

  • load (also get)

    This will read data from the cache into memory and return the data to the caller.

  • load_lines

    This will return an iterator over the lines store in the cache. The underlying file will be closed automatically when all lines have been read.

  • load_iter

    This will return an iterator that yields data in chunksize byte chunks. The underlying file will be closed automatically when all the data has been read.

  • load_fd

    This will return an open file to the caller. Is is the caller’s job to close the file when it is no longer needed.

## Contributing

To report problems with this code, use the [issue tracker][]. Changes may be submitted as GitHub pull requests.

[issue tracker]:

## License

thecache, a simple Python cache implementation Copyright (C) 2016 Lars Kellogg-Stedman <>

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <>.

Project details

Release history Release notifications

This version
History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
thecache-0.3.tar.gz (16.9 kB) Copy SHA256 hash SHA256 Source None Feb 22, 2016

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page