How sorl-thumbnail operates¶
When you use the
thumbnail template tag sorl-thumbnail looks up the
thumbnail in a Key Value Store. 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.
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
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
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 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.
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.