Thumbnail Options

The options for a thumbnail are held in a ThumbnailOptions dictionary, which applies the default options and is used to build the thumbnail’s file name.

class easy_thumbnails.options.ThumbnailOptions(*args, **kwargs)

A dictionary of thumbnail options (e.g. {'size': (100, 100), 'crop': True}), as passed to the source generators, the processors and engine.save_pil_image. Thumbnailer.get_options and the engine wrap plain dictionaries in it. See Usage and Image Processors for the available options.

On creation, it:

adds the entries of THUMBNAIL_DEFAULT_OPTIONS that aren’t given,
sets subsampling to 4:2:0 (JPEG_CSS_420) if it isn’t given,
normalizes format: lowercased, without a leading ., and jpeg becomes jpg. It must be one of OUTPUT_FORMATS (jpg, webp, avif), otherwise a ValueError is raised.

It doesn’t add a quality; Thumbnailer.resolve_quality adds the default quality of the output format from THUMBNAIL_IMAGE_SAVE_OPTIONS. It doesn’t parse a size string either (the {% thumbnail %} tag does).

prepared_options() turns the options into the parts of the thumbnail file name.

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!