Thumbnail Files and Generators

Following is some basic documentation of the classes and methods related to thumbnail files and lower level generation.

class easy_thumbnails.files.ThumbnailFile(name, file=None, storage=None, thumbnail_options=None, *args, **kwargs)

A thumbnailed file.

This can be used just like a Django model instance’s property for a file field (i.e. an ImageFieldFile object).

property image

Get a PIL Image instance of this file.

The image is cached to avoid the file needing to be read again if the function is called again.

set_image_dimensions(thumbnail)

Set image dimensions from the cached dimensions of a Thumbnail model instance.

tag(alt='', use_size=None, **attrs)

Return a standard XHTML <img ... /> tag for this field.

Parameters

  • alt – The alt="" text for the tag. Defaults to ''.

  • use_size – Whether to get the size of the thumbnail image for use in the tag attributes. If None (default), the size will only be used it if won’t result in a remote file retrieval.

All other keyword parameters are added as (properly escaped) extra attributes to the img tag.

class easy_thumbnails.files.Thumbnailer(file=None, name=None, source_storage=None, thumbnail_storage=None, remote_source=False, generate=True, *args, **kwargs)

A file-like object which provides some methods to generate thumbnail images.

You can subclass this object and override the following properties to change the defaults (pulled from the default settings):

  • source_generators

  • thumbnail_processors

generate_thumbnail(thumbnail_options, high_resolution=False, silent_template_exception=False)

Return an unsaved ThumbnailFile containing a thumbnail image.

The thumbnail image is generated using the thumbnail_options dictionary.

get_existing_thumbnail(thumbnail_options, high_resolution=False)

Return a ThumbnailFile containing an existing thumbnail for a set of thumbnail options, or None if not found.

get_options(thumbnail_options, **kwargs)

Get the thumbnail options that includes the default options for this thumbnailer (and the project-wide default options).

get_thumbnail(thumbnail_options, save=True, generate=None, silent_template_exception=False)

Return a ThumbnailFile containing a thumbnail.

If a matching thumbnail already exists, it will simply be returned.

By default (unless the Thumbnailer was instanciated with generate=False), thumbnails that don’t exist are generated. Otherwise None is returned.

Force the generation behaviour by setting the generate param to either True or False as required.

The new thumbnail image is generated using the thumbnail_options dictionary. If the save argument is True (default), the generated thumbnail will be saved too.

get_thumbnail_name(thumbnail_options, transparent=False, high_resolution=False)

Return a thumbnail filename for the given thumbnail_options dictionary and source_name (which defaults to the File’s name if not provided).

save_thumbnail(thumbnail)

Save a thumbnail to the thumbnail_storage.

Also triggers the thumbnail_created signal and caches the thumbnail values and dimensions for future lookups.

source_generators = None

A list of source generators to use. If None, will use the default generators defined in settings.

thumbnail_exists(thumbnail_name)

Calculate whether the thumbnail already exists and that the source is not newer than the thumbnail.

If the source and thumbnail file storages are local, their file modification times are used. Otherwise the database cached modification times are used.

thumbnail_processors = None

A list of thumbnail processors. If None, will use the default processors defined in settings.

class easy_thumbnails.files.ThumbnailerFieldFile(*args, **kwargs)

A field file which provides some methods for generating (and returning) thumbnail images.

delete(*args, **kwargs)

Delete the image, along with any generated thumbnails.

delete_thumbnails(source_cache=None)

Delete any thumbnails generated from the source image.

Parameters

source_cache – An optional argument only used for optimisation where the source cache instance is already known.

Returns

The number of files deleted.

get_thumbnails(*args, **kwargs)

Return an iterator which returns ThumbnailFile instances.

save(name, content, *args, **kwargs)

Save the file, also saving a reference to the thumbnail cache Source model.

class easy_thumbnails.files.ThumbnailerImageFieldFile(*args, **kwargs)

A field file which provides some methods for generating (and returning) thumbnail images.

save(name, content, *args, **kwargs)

Save the image.

The image will be resized down using a ThumbnailField if resize_source (a dictionary of thumbnail options) is provided by the field.

easy_thumbnails.files.database_get_image_dimensions(file, close=False, dimensions=None)

Returns the (width, height) of an image, given ThumbnailFile. Set ‘close’ to True to close the file at the end if it is initially in an open state.

Will attempt to get the dimensions from the file itself if they aren’t in the db.

easy_thumbnails.files.generate_all_aliases(fieldfile, include_global)

Generate all of a file’s aliases.

Parameters

  • fieldfile – A FieldFile instance.

  • include_global – A boolean which determines whether to generate thumbnails for project-wide aliases in addition to field, model, and app specific aliases.

easy_thumbnails.files.get_thumbnailer(obj, relative_name=None)

Get a Thumbnailer for a source file.

The obj argument is usually either one of the following:

  • FieldFile instance (i.e. a model instance file/image field property).

  • A string, which will be used as the relative name (the source will be set to the default storage).

  • Storage instance - the relative_name argument must also be provided.

Or it could be:

  • A file-like instance - the relative_name argument must also be provided.

    In this case, the thumbnailer won’t use or create a cached reference to the thumbnail (i.e. a new thumbnail will be created for every Thumbnailer.get_thumbnail() call).

If obj is a Thumbnailer instance, it will just be returned. If it’s an object with an easy_thumbnails_thumbnailer then the attribute is simply returned under the assumption it is a Thumbnailer instance)