Namers

easy-thumbnails allows you to customize how thumbnail filenames are generated by setting THUMBNAIL_NAMER to the dotted path of a namer function.

Built-in namers

easy_thumbnails.namers.alias(thumbnailer, thumbnail_options, source_filename, thumbnail_extension, **kwargs)

Generate filename based on thumbnail alias name (option THUMBNAIL_ALIASES).

For example: source.jpg.medium_large.jpg

easy_thumbnails.namers.alias_or_size(thumbnailer, thumbnail_options, source_filename, thumbnail_extension, **kwargs)

Generate filename based on thumbnail alias name (option THUMBNAIL_ALIASES). If no alias is available only the size will be used (as it is a required option). The source file suffix/extension is removed from the name.

For example: source.medium_large.jpg or source.800x600.jpg

easy_thumbnails.namers.default(thumbnailer, prepared_options, source_filename, thumbnail_extension, **kwargs)

Easy-thumbnails’ default name processor.

For example: source.jpg.100x100_q80_crop_upscale.jpg

easy_thumbnails.namers.hashed(source_filename, prepared_options, thumbnail_extension, **kwargs)

Generate a short hashed thumbnail filename.

Creates a 12 character url-safe base64 sha1 filename (plus the extension), for example: 6qW1buHgLaZ9.jpg.

easy_thumbnails.namers.source_hashed(source_filename, prepared_options, thumbnail_extension, **kwargs)

Generate a thumbnail filename of the source filename and options separately hashed, along with the size.

The format of the filename is a 12 character base64 sha1 hash of the source filename, the size surrounded by underscores, and an 8 character options base64 sha1 hash of the thumbnail options. For example: 1xedFtqllFo9_100x100_QHCa6G1l.jpg.

Note

The alias and alias_or_size namers don’t name a thumbnail by its options, so use them for plain aliases only. Other thumbnails, such as {% thumbnail source '30x30' %} or an alias with overriding options, share a single file with the alias namer, and share a file with thumbnails of the same size with the alias_or_size namer.

Custom namers

To write a custom namer, always catch all other keyword arguments (with **kwargs). You have access to the following arguments: thumbnailer, source_filename, thumbnail_extension (does not include the '.'), thumbnail_options, prepared_options. The namer must return a filename.

The thumbnail_options are a copy of the options dictionary used to build the thumbnail, prepared_options is a list of options prepared as text, and excluding options that shouldn’t be included in the filename:

ThumbnailOptions.prepared_options()

Return the options as a list of strings used to name the thumbnail.

The first item is the size ('100x50'). The second item is the quality ('q76'). It gets an ss part with the subsampling, if it is not the default ('q76ss0'). The default is 4:2:0, which Pillow indicates with subsampling=2. It is left out if there is neither a quality nor a non-default subsampling (e.g. for formats without a configured default quality).

The remaining options follow in key order. A True value is added as key. Any other value is added as key-value. Sequences are comma-joined.

Falsy values and uppercase keys are skipped, they don’t affect the filename. The format key is skipped too: it already determines the file extension, so it is not repeated in the name.

This is only used for naming: Thumbnailer.get_thumbnail_name joins the list with _ for the %(opts)s basedir/subdir templates and passes it to the namer as prepared_options.

Image generation does not use it; the processors, source generators and engine.save_pil_image read the full options dict.

The size must stay the first item, since the built-in source_hashed namer relies on it!