Quickstart¶

pip install pillow  # default image engine, not necessary if another engine is used
pip install python-thumbnails

from thumbnails import get_thumbnail

get_thumbnail('path/to/image.png', '300x300', crop='center')

INSTALLED_APPS = (
    # your other apps

    'thumbnails',
)

How python-thumbnail works¶

python-thumbnails have a single function that should be used for most thumbnail generations. It is thumbnails.get_thumbnail. That function will use the correct backends to fetch or create the thumbnail.

The first that will happen when that function is called is that a hash is generated based on the image path or url, the wanted size, the wanted crop and other options that are given that differ from the defaults [1]. That hash is used to lookup in cache and in the file path of the thumbnail.

After the hash is created the thumbnail info will be retrieved from the cache, if it is in the cache the function will return with the info about the thumbnail. In the case that the cache has no information about the given hash the storage system will be checked to se if there is a saved thumbnail for that hash. If there is, info about the thumbnail is returned.

If there exist no thumbnail file for the given hash the thumbnail will be created using the current image engine and saved with the storage engine before saving the information about the created thumbnail in the cache.

After creating the thumbnail an extra thumbnail will be created for every resolution listed in the alternative resolution setting. Note that the there is no check if the alternative resolution exists. The alternative resolution thumbnails will only be created if the standard resolution thumbnail does not exist.

Creating thumbnails¶

thumbnails.get_thumbnail should be used to generate thumbnails from python code. It takes the original image and size is positional arguments and needs to be passed each time the function is called. Other options can be passed as keyword arguments. The available options is listed below:

{% load thumbnails %}

{% get_thumbnail "image.jpg" "400x400" crop="center" as thumbnail %}
<img src="{{ thumbnail.url }}" alt="The thumbnail" style="width: {{ thumbnail.width }} />

{% load thumbnails %}

{{ content|markdown_thumbnails }}

{% load thumbnails %}

{{ content|html_thumbnails }}

{% load thumbnails %}

{{ content|safe_html_thumbnails }}

@register.filter
def html_thumbnails(value):
    return mark_safe(text_filter('<img(?: alt="(%(caption)s)?")? src="(%(image)s)"', value))

Image engines¶

python-thumbnails uses interchangeable image engines to make it possible to use the imaging framework you like the best. python-thumbnails should have a few to select from. However, if the framework you want to use is not supported. Extend BaseThumbnailEngine to create your own. If you think your engine is valuable to others a pull-request is always appreciated.

Cache backends¶

The cache backends is used to store references to already created thumbnails in order to avoid unnecessary disk or network usage. The Thumbnail object is cached and will be returned directly in get_thumbnail if the cache returns it.

Storage backends¶

Settings¶

THUMBNAIL_PATH

The path where thumbnails are saved.

Default: os.getcwd() + '/thumbnails-cache'

Default in Django: django.conf.settings.MEDIA_ROOT + '/thumbnails-cache'

THUMBNAIL_URL

The prefix for the url property of an Thumbnail object. The url property will contain this prefix and the relative path from THUMBNAIL_PATH.

Default: '/thumbnails/''

Default in Django: django.conf.settings.MEDIA_URL + '/thumbnails-cache'

THUMBNAIL_ENGINE

Default: thumbnails.engines.PillowEngine

THUMBNAIL_CACHE_BACKEND

Default: thumbnails.cache_backends.SimpleCacheBackend

Default in Django: thumbnails.cache_backends.DjangoCacheBackend

THUMBNAIL_CACHE_TIMEOUT

A timeout parameter for cache backends that does not support eternal items.

Default: 60 * 60 * 24 * 365 (a year in seconds)

THUMBNAIL_STORAGE_BACKEND

Default: thumbnails.storage_backends.FilesystemStorageBackend

Default in Django: thumbnails.storage_backends.DjangoStorageBackend

Changelog¶

Contributing¶

Contributions are highly appreciated, please follow the following guidelines in order to make the process of including the contributions easier.

It sums up to write tests, follow pep8 and the import-sorting guidelines. New features needs to be documented.

Please remember to add your change to the CHANGELOG.rst under the section “Changes since last release”.

@unittest.skipIf(not has_installed('pillow'), 'Pillow not installed')
class PillowEngineTestCase(EngineTestMixin, unittest.TestCase):
    ENGINE = PillowEngine

class SimpleCacheBackendTestCase(CacheBackendTestMixin, unittest.TestCase):
    BACKEND = SimpleCacheBackend