When you use the thumbnail
template tag sorl-thumbnail looks up the
thumbnail in a :ref:`kvstore-requirements`. The key for a thumbnail is
generated from its filename and storage. The thumbnail filename in turn is
generated from the source and requested thumbnail size and options. If the key
for the thumbnail is found in the Key Value Store, the serialized thumbnail
information is fetched from it and returned. If the thumbnail key is not found
there sorl-thumbnail continues to generate the thumbnail and stores necessary
information in the Key Value Store. It is worth noting that sorl-thumbnail does not
check if source or thumbnail exists if the thumbnail key is found in the
Key Value Store.
Note
This means that if you change or delete a source file or delete the thumbnail, sorl-thumbnail will still fetch from the Key Value Store. Therefore it is important that if you delete or change a source or thumbnail file notify the Key Value Store.
If you change or delete a source or a thumbnail for some reason, you can use
the delete
method of the ThumbnailBackend
class or subclass:
from sorl.thumbnail import delete
# Delete the Key Value Store reference but **not** the file.
# Use this if you have changed the source
delete(my_file, delete_file=False)
# Delete the Key Value Store reference and the file
# Use this if you want to delete the source file
delete(my_file) # delete_file=True is default
The sorl.thumbnail.delete
method always deletes the input files thumbnail
Key Value Store references as well as thumbnail files. You can use this method
on thumbnails as well as source files. Alternatively if you have deleted a
file you can use the management command :ref:`thumbnail-cleanup`. Deleting an
image using the sorl.thumbnail.ImageField
will notify the Key Value Store to
delete references to it and delete all of its thumbnail references and files,
exactly like the above code example.
Why you ask? Why go through all the trouble with a Key Value Store and risk stale cache? Why not use a database to cache if you are going to do that?
The reason is speed and especially with storages other than local file storage. Checking if a file exists before serving it will cost too much. Speed is also the reason for not choosing to use a standard database for this kind of persistent caching. However sorl-thumbnail does ship with a cached database Key Value Store.
Note
We have to assume the thumbnail exists if the thumbnail key exists in the Key Value Store
There are bonuses. We can store meta data in the Key Value Store that would be too costly to retrieve even for local file storage. Today this meta data consists only of the image size but this could be expanded to for example EXIF data. The other bonus is that we can keep track of what thumbnails has been generated from a particular source and deleting them too when the source is deleted.