Usage

Let’s learn how to use fcache.

Create a Cache

fcache consists of a single class, Cache.

>>> import fcache
>>> cache = fcache.Cache("hello", "hello_goodbye")

By creating an instance of Cache, you’ve created a cache file on the file system that is identified as “hello” and associated with the “hello_goodbye” application.

Store Data in the Cache

>>> cache.set("english", "Hello!")
>>> cache.set("spanish", u"¡Hola!")
>>> cache.set("chinese", u"你好!")

By calling the method set(), you associate a value with a key, just like with a Python dictionary. In your cache file, there is now three key/value pairs.

Get Data from the Cache

>>> print cache.get("english")
Hello!
>>> print cache.get("spanish")
¡Hola!
>>> print cache.get("chinese")
你好!

By calling the method get(), you can retrieve the value of a key.

Store Other Types of Data

>>> english_greetings = {"ordinary": "Hello!", "friendly": "Hey there!"}
>>> cache.set("english", english_greetings)
>>> print cache.get("english")
{'ordinary': 'Hello!', 'friendly': 'Hey there!'}

The data stored doesn’t have to be a string. It can be any type that the pickle module supports. In this case, we used a dictionary to store multiple English greetings.

Set Data to Expire After a Certain Time

>>> cache.set("norwegian", "Hallo!", 30)
>>> print cache.get("norwegian")
Hallo!
>>> import time
>>> time.sleep(30)
>>> print cache.get("norwegian")
None

Data can be set to expire after a certain amount of seconds. By setting data to expire in 30 seconds, you can fetch the data anytime in the next 30 seconds; after that, the data will return as None. We used the time.sleep() function to wait 30 seconds so that the data would expire.

Invalidate Data

>>> print cache.get("english")
{'ordinary': 'Hello!', 'friendly': 'Hey there!'}
>>> cache.invalidate("english")
>>> print cache.get("english")
None

Data can be forced to expire, even if it doesn’t have an expiration time. Once data is invalidated, calling get() on its key will return None.

Remove Data From the Cache

>>> cache.remove("chinese")
>>> cache.get("chinese")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/tsr/.virtualenvs/fcache/lib/python2.7/site-packages/fcache-0.1-py2.7.egg/fcache.py", line 163, in get
    if ((data[name]["expires"] is None) or
KeyError: 'chinese'

Data can be easily removed from a cache by calling the remove() method. If you try to retrieve a key that doesn’t exist, a KeyError is raised.

Cached Data is Persistent

>>> exit()
$ python
>>> import fcache
>>> cache = fcache.Cache("hello", "hello_goodbye")
>>> print cache.get("spanish")
¡Hola!

fcache provides persistent cache files. In other words, your cached data is saved even after you stop using it.

Clear Cached Data

>>> cache.flush()
>>> print cache.get("spanish")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/tsr/.virtualenvs/fcache/lib/python2.7/site-packages/fcache-0.1-py2.7.egg/fcache.py", line 163, in get
    if ((data[name]["expires"] is None) or
KeyError: 'spanish'

Using the flush() method, you can clear all the data in a cache without deleting the cache file itself.

Delete a Cache

>>> import os.path
>>> os.path.exists(cache.filename)
True
>>> cache.delete()
>>> os.path.exists(cache.filename)
False

The os.path.exists() function returns True if a file exists. In our case, we used it to show that the cache file does indeed exist. Then, we called the delete() method, which deletes the cache file.