Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
document cache and state conventions
  • Loading branch information
ralsina committed Jan 26, 2016
1 parent 38ef60c commit cd8b5ea
Showing 1 changed file with 26 additions and 0 deletions.
26 changes: 26 additions & 0 deletions docs/extending.txt
Expand Up @@ -592,3 +592,29 @@ So, for example::
Will cause a call like this::

foo_handler("bar", "beep", baz="bat", data="Some text", site=whatever)

State and Cache
===============

Sometimes your plugins will need to cache things to speed up further actions. Here are the conventions for that:

* If it's a file, put it somewhere in ```self.site.config['CACHE_FOLDER']``` (defaults to ```cache/```.
* If it's a value, use ```self.site.cache.set(key, value)``` to set it and ```self.site.cache.get(key)``` to get it.
The key should be a string, the value should be json-encodable (so, be careful with datetime objects)

The values and files you store there can **and will** be deleted sometimes by the user. They should always be
things you can reconstruct without lossage. They are throwaways.

On the other hand, sometimes you want to save something that is **not** a throwaway. These are things that may
change the output, so the user should not delete them. We call that **state**. To save state:

* If it's a file, put it somewhere in the working directory. Try not to do that please.
* If it's a value, use ```self.site.state.set(key, value)``` to set it and ```self.state.cache.get(key)``` to get it.
The key should be a string, the value should be json-encodable (so, be careful with datetime objects)

The ```cache``` and ```state``` objects are rather simplistic, and that's intentional. They have no default values: if
the key is not there, you will get ```None``` and like it. They are meant to be both threadsafe, but hey, who can
guarantee that sort of thing?

There are no sections, and no access protection, so let's not use it to store passwords and such. Use responsibly.

0 comments on commit cd8b5ea

Please sign in to comment.