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).-
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.
- alt – The
-
-
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, orNone
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 withgenerate=False
), thumbnails that don’t exist are generated. OtherwiseNone
is returned.Force the generation behaviour by setting the
generate
param to eitherTrue
orFalse
as required.The new thumbnail image is generated using the
thumbnail_options
dictionary. If thesave
argument isTrue
(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 andsource_name
(which defaults to the File’sname
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
ifresize_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.
- fieldfile – A
-
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 - therelative_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 aThumbnailer
instance, it will just be returned. If it’s an object with aneasy_thumbnails_thumbnailer
then the attribute is simply returned under the assumption it is a Thumbnailer instance)