Easy Thumbnails

https://easy-thumbnails.readthedocs.io/en/latest/
Admin
Easy Thumbnails is a Django thumbnailing application that is easy to use and customize, providing...
Tokens:10,938
Snippets:237
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install easy-thumbnails manually

Source: https://easy-thumbnails.readthedocs.io/en/latest/install

Manual installation by downloading and running the setup script.

```bash
python setup.py install

```

--------------------------------

### Install easy-thumbnails using pip

Source: https://easy-thumbnails.readthedocs.io/en/latest/install

The recommended way to install easy-thumbnails is by using pip.

```bash
pip install easy-thumbnails

```

--------------------------------

### THUMBNAIL_DEFAULT_OPTIONS Example

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Example of setting default options to make all images greyscale.

```python
THUMBNAIL_DEFAULT_OPTIONS = {'bw': True}
```

--------------------------------

### Run migrations

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/install.rst.txt

Command to run migrations for easy-thumbnails after adding it to INSTALLED_APPS.

```bash
python manage.py migrate easy_thumbnails
```

--------------------------------

### Custom Processor Example

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/ref/processors.rst.txt

An example of how to create a custom image processor function.

```python
def whizzbang_processor(image, bang=False, **kwargs):
    """
    Whizz bang the source image.

    """
    if bang:
        image = whizz(image)
    return image
```

--------------------------------

### THUMBNAIL_OPTIMIZE_COMMAND Example

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/optimize

Example configuration for THUMBNAIL_OPTIMIZE_COMMAND to specify optimization commands for different image types.

```python
THUMBNAIL_OPTIMIZE_COMMAND = {
    'png': '/usr/bin/optipng {filename}',
    'gif': '/usr/bin/optipng {filename}',
    'jpeg': '/usr/bin/jpegoptim {filename}'
}
```

--------------------------------

### THUMBNAIL_SUBDIR Example

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Example of how THUMBNAIL_SUBDIR affects the thumbnail filename.

```text
MEDIA_ROOT + 'photos/thumbs/1_jpg_150x150_q85.jpg'
```

--------------------------------

### THUMBNAIL_PREFIX Example

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Example of how THUMBNAIL_PREFIX affects the thumbnail filename.

```text
MEDIA_ROOT + 'photos/thumbs_1_jpg_150x150_q85.jpg'
```

--------------------------------

### Setting aliases for third-party apps

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

Example of how to dynamically set aliases for easy-thumbnails at runtime.

```python
from easy_thumbnails.alias import aliases
if not aliases.get('badge'):
    aliases.set('badge', {'size': (150, 80), 'crop': True})
```

--------------------------------

### THUMBNAIL_HIGH_RESOLUTION Python Example

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Example of overriding high resolution setting at a per-thumbnail level in Python.

```python
opts = {'size': (100, 100), 'crop': True, HIGH_RESOLUTION: False}
only_basic = get_thumbnailer(obj.image).get_thumbnail(opts)
```

--------------------------------

### THUMBNAIL_PRESERVE_EXTENSIONS Configuration

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Configuration example for preserving specific file extensions.

```python
THUMBNAIL_PRESERVE_EXTENSIONS = ('png',)
```

--------------------------------

### ThumbnailerImageField resize_source example

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Example of using resize_source with ThumbnailerImageField to thumbnail the original source image before saving.

```python
ThumbnailerImageField(
    ..., resize_source=dict(size=(100, 100), sharpen=True))


```

--------------------------------

### Thumbnail Aliases Configuration

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

Example of how to define thumbnail aliases in Django settings.

```python
THUMBNAIL_ALIASES = {
    <target>: {
        <alias name>: <alias options dictionary>,
        ...
    },
    ...
}
```

--------------------------------

### Django Settings Configuration

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/ref/optimize.rst.txt

Example of how to add the optimizing postprocessor to Django's INSTALLED_APP settings.

```python
INSTALLED_APP = (
    ...
    'easy_thumbnails',
    'easy_thumbnails.optimize',
    ...
)
```

--------------------------------

### Asynchronous thumbnail generation using Celery

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

Example of how to integrate easy-thumbnails with Celery for asynchronous thumbnail creation.

```python
from django.dispatch import receiver
from easy_thumbnails.signals import saved_file
from myapp import tasks

@receiver(saved_file)
def generate_thumbnails_async(sender, fieldfile, **kwargs):
    tasks.generate_thumbnails.delay(
        model=sender, pk=fieldfile.instance.pk,
        field=fieldfile.field.name)
```

```python
from celery import task
from easy_thumbnails.files import generate_all_aliases

@task
def generate_thumbnails(model, pk, field):
    instance = model._default_manager.get(pk=pk)
    fieldfile = getattr(instance, field)
    generate_all_aliases(fieldfile, include_global=True)
```

--------------------------------

### Thumbnailer filter with object

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Example usage of the thumbnailer filter to get a thumbnailer from an object.

```django
{% with photo=person.photo|thumbnailer %}
{% if photo %}
    <a href="{{ photo.large.url }}">
        {{ photo.square.tag }}
    </a>
{% else %}
    <img src="{% static 'template/fallback.png' %}" alt="" />
{% endif %}
{% endwith %}


```

--------------------------------

### Using the thumbnail_url filter

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Example of using the `thumbnail_url` filter to get the URL of a thumbnail based on an alias.

```html
<img src="{{ person.photo|thumbnail_url:'small' }}" alt="">

```

--------------------------------

### Add easy-thumbnails to Django INSTALLED_APPS

Source: https://easy-thumbnails.readthedocs.io/en/latest/install

Configure your Django project's settings to include easy-thumbnails.

```python
INSTALLED_APPS = (
    ...
    'easy_thumbnails',
)

```

--------------------------------

### Django AppConfig ready method to connect signal

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/webp

Example of connecting the `store_as_webp` function to the `thumbnail_created` signal within an AppConfig's `ready()` method.

```python
def ready(self):
    from easy_thumbnails.signals import thumbnail_created
    thumbnail_created.connect(store_as_webp)

```

--------------------------------

### Accessing thumbnail properties

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Example of accessing properties like URL, width, and height of a generated thumbnail when using the 'as' variable.

```html
{% thumbnail obj.picture 200x200 upscale as thumb %}
<img src="{{ thumb.url }}"
     width="{{ thumb.width }}"
     height="{{ thumb.height }}" />

```

--------------------------------

### THUMBNAIL_HIGH_RESOLUTION Template Tag Example

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Examples of enabling or disabling high resolution thumbnails in template tags.

```django
{% thumbnail obj.image 50x50 crop HIGH_RESOLUTION=0 %}  {# no hires #}
{% thumbnail obj.image 50x50 crop HIGH_RESOLUTION %}  {# force hires #}
```

--------------------------------

### THUMBNAIL_BASEDIR Example

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Illustrates how THUMBNAIL_BASEDIR affects the thumbnail filename.

```text
MEDIA_ROOT + 'thumbs/photos/1_jpg_150x150_q85.jpg'
```

--------------------------------

### Registering Signal Handler

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Example of registering a signal handler for pregenerating thumbnails when a file is uploaded.

```python
from easy_thumbnails.signals import saved_file
from easy_thumbnails.signal_handlers import generate_aliases_global

saved_file.connect(generate_aliases_global)

```

--------------------------------

### get_thumbnailer utility function

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

Example of using get_thumbnailer to create a Thumbnailer instance and generate thumbnails.

```python
from easy_thumbnails.files import get_thumbnailer

thumbnailer = get_thumbnailer('animals/aardvark.jpg')

thumbnail_options = {'crop': True}
for size in (50, 100, 250):
    thumbnail_options.update({'size': (size, size)})
    thumbnailer.get_thumbnail(thumbnail_options)

# or to get a thumbnail by alias
thumbnailer['large']
```

--------------------------------

### Adding Custom Processor to Settings

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/ref/processors.rst.txt

An example of how to add a custom processor to the THUMBNAIL_PROCESSORS setting.

```python
from easy_thumbnails.conf import Settings as easy_thumbnails_defaults

THUMBNAIL_PROCESSORS = easy_thumbnails_defaults.THUMBNAIL_PROCESSORS + (
    'wb_project.thumbnail_processors.whizzbang_processor',
)
```

--------------------------------

### Using the {% thumbnail %} tag with 'as' variable

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Example of using the `thumbnail` tag to place a `ThumbnailFile` object in the context for accessing its properties.

```django-template
{% thumbnail [source] [size] [options] as [variable] %}

```

--------------------------------

### Fallback images in templates

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

Example of using a default image when the primary image is not available.

```django
{% thumbnail object.image|default:'img/default_image.png' 50x50 %}
```

--------------------------------

### Registering Signal Handler for Alias Generation

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

Example of connecting a signal handler to generate aliases when a file is saved.

```python
from easy_thumbnails.signals import saved_file
from easy_thumbnails.signal_handlers import generate_aliases_global

saved_file.connect(generate_aliases_global)
```

--------------------------------

### Processing non-Django file objects

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

Example of using get_thumbnailer with standard file-like objects.

```python
picture = open('/home/zookeeper/pictures/my_anteater.jpg')
thumbnailer = get_thumbnailer(picture, relative_name='animals/anteater.jpg')
thumb = thumbnailer.get_thumbnail({'size': (100, 100)})
```

--------------------------------

### Django AppConfig for Signal Registration

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/ref/webp.rst.txt

Example of registering the WebP signal handler in the AppConfig's ready() method.

```python
...

def ready(self):
    from easy_thumbnails.signals import thumbnail_created
    thumbnail_created.connect(store_as_webp)
```

--------------------------------

### Admin configuration for ImageClearableFileInput

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Example of using ImageClearableFileInput widget automatically with ThumbnailerField in Django admin.

```python
class MyModelAdmin(admin.ModelAdmin):
    formfield_overrides = {
        ThumbnailerField: {'widget': ImageClearableFileInput},
    }


```

--------------------------------

### Using the {% thumbnail %} tag with an alias

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Example showing how to use the `thumbnail` tag with an alias, potentially overriding alias options.

```django-template
{% thumbnail [source] [alias_name] [options] %}

```

--------------------------------

### Thumbnailer filter with relative name

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Example usage of the thumbnailer filter passing a relative name.

```django
{% with photo=storage|thumbnailer:'some/file.jpg' %}...{% endwith %}

```

--------------------------------

### HTML Picture Element for WebP

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/ref/webp.rst.txt

Example of using the HTML <picture> element to serve WebP images alongside a fallback JPEG.

```html
<picture>
  <source srcset="/path/to/image.webp" type="image/webp">
  <img src="/path/to/image.jpg">
</picture>
```

--------------------------------

### Data URI filter

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Example usage of the data_uri filter to insert an image inline as a data URI.

```django
{% thumbnail sample_image 25x25 crop as thumb %}
<img src="{{ thumb|data_uri }}">

```

--------------------------------

### Thumbnailer passive filter

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Example usage of the thumbnailer_passive filter which won't generate new thumbnails.

```django
{% with avatar=person.avatar|thumbnailer_passive %}
    {% with avatar_thumb=avatar.small %}
        {% if avatar_thumb %}
            <img src="{{ avatar_thumb.url }}" alt="" />
        {% else %}
            <img src="{% static 'img/default-avatar-small.png' %}"
                alt="" />
        {% endif %}
    {% endwith %}
{% endwith %}

```

--------------------------------

### Django Template for WebP Rendering

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/ref/webp.rst.txt

Example of how to modify Django templates to use the <picture> element with Easy-Thumbnails for WebP support.

```django
{% load thumbnail %}
...
<picture>
  {% thumbnail image 400x300 as thumb %}
  <source srcset="{{ thumb.url }}.webp" type="image/webp" />
  <img src="{{ thumb.url }}" width="{{ thumb.width }}" height="{{ thumb.height }}" />
</picture>
```

--------------------------------

### Example Processor Function

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/processors

Defines a sample processor function named 'whizzbang_processor' that takes an image and an optional 'bang' argument. It demonstrates how to modify the image and the required return type.

```python
def whizzbang_processor(image, bang=False, **kwargs):
    """
    Whizz bang the source image.

    """
    if bang:
        image = whizz(image)
    return image

```

--------------------------------

### Basic {% thumbnail %} tag syntax

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Demonstrates the basic syntax for the `thumbnail` template tag to create a thumbnail with specified size and options.

```django-template
{% thumbnail [source] [size] [options] %}

```

--------------------------------

### Loading the thumbnail template library

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

How to make the easy-thumbnail template library available in Django templates.

```django
{% load thumbnail %}
```

--------------------------------

### THUMBNAIL_SOURCE_GENERATORS Configuration

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Configuration for source generators.

```python
THUMBNAIL_SOURCE_GENERATORS = ('easy_thumbnails.source_generators.pil_image',)
```

--------------------------------

### THUMBNAIL_PROCESSORS Default Configuration

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Default configuration for image processors.

```python
THUMBNAIL_PROCESSORS = (
    'easy_thumbnails.processors.colorspace',
    'easy_thumbnails.processors.autocrop',
    'easy_thumbnails.processors.scale_and_crop',
    'easy_thumbnails.processors.filters',
    'easy_thumbnails.processors.background',
)
```

--------------------------------

### Enabling thumbnail debug mode

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

Configuration setting to display errors during thumbnail generation instead of failing silently.

```python
THUMBNAIL_DEBUG = True

```

--------------------------------

### Using the '{% thumbnail %}' tag

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

Reference to the thumbnail template tag for generating thumbnails.

```django
.. autofunction:: easy_thumbnails.templatetags.thumbnail.thumbnail
```

--------------------------------

### THUMBNAIL_WIDGET_OPTIONS Configuration

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Default options for the ImageClearableFileInput widget.

```python
THUMBNAIL_WIDGET_OPTIONS = {'size': (80, 80)}
```

--------------------------------

### Loading the thumbnail template tag library

Source: https://easy-thumbnails.readthedocs.io/en/latest/usage

How to make the easy-thumbnail template tags available in your Django templates.

```django-template
{% load thumbnail %}

```

--------------------------------

### THUMBNAIL_TRANSPARENCY_EXTENSION Setting

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Setting for the image type for thumbnails with transparency.

```text
THUMBNAIL_TRANSPARENCY_EXTENSION = 'png'
```

--------------------------------

### THUMBNAIL_PROGRESSIVE Setting

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Setting for using progressive JPGs.

```text
THUMBNAIL_PROGRESSIVE = 100
```

--------------------------------

### Adding Processor to Settings

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/processors

Shows how to add a custom processor to the `THUMBNAIL_PROCESSORS` setting in Django's settings module.

```python
from easy_thumbnails.conf import Settings as easy_thumbnails_defaults

THUMBNAIL_PROCESSORS = easy_thumbnails_defaults.THUMBNAIL_PROCESSORS + (
    'wb_project.thumbnail_processors.whizzbang_processor',
)

```

--------------------------------

### Using the 'thumbnail_url' filter

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

Reference to the thumbnail_url template filter.

```django
.. autofunction:: easy_thumbnails.templatetags.thumbnail.thumbnail_url
```

--------------------------------

### THUMBNAIL_QUALITY Setting

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/settings

Setting for the default quality level for JPG images.

```text
THUMBNAIL_QUALITY = 85
```

--------------------------------

### Python Signal Handler for WebP Generation

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/ref/webp.rst.txt

Python function to be connected to the Easy-Thumbnails signal handler to generate a WebP version of a thumbnail.

```python
def store_as_webp(sender, **kwargs):
    webp_path = sender.storage.path('.'.join([sender.name, 'webp']))
    sender.image.save(webp_path, 'webp')
```

--------------------------------

### Python function to store image as WebP

Source: https://easy-thumbnails.readthedocs.io/en/latest/ref/webp

A Python function that can be connected to the `thumbnail_created` signal to save a WebP version of the generated thumbnail.

```python
def store_as_webp(sender, **kwargs):
    webp_path = sender.storage.path('.'.join([sender.name, 'webp']))
    sender.image.save(webp_path, 'webp')

```

--------------------------------

### ThumbnailerField and ThumbnailerImageField

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

References to Django model fields for easier thumbnail management.

```django
.. autoclass:: easy_thumbnails.fields.ThumbnailerField
```

```django
.. autoclass:: easy_thumbnails.fields.ThumbnailerImageField
```

--------------------------------

### Other 'thumbnailer' filters

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

References to thumbnailer filters for direct access to thumbnailer objects in templates.

```django
.. autofunction:: easy_thumbnails.templatetags.thumbnail.thumbnailer
```

```django
.. autofunction:: easy_thumbnails.templatetags.thumbnail.thumbnailer_passive
```

--------------------------------

### ImageClearableFileInput widget

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

Reference to the ImageClearableFileInput widget for forms.

```django
.. autoclass:: easy_thumbnails.widgets.ImageClearableFileInput
   :members: __init__
```

--------------------------------

### Data URI filter

Source: https://easy-thumbnails.readthedocs.io/en/latest/_sources/usage.rst.txt

Reference to the data_uri filter for inserting images as data URIs.

```django
.. autofunction:: easy_thumbnails.templatetags.thumbnail.data_uri
```
Tokens:
Raw