README.rst

django-ok-images

WebP sizers and filters for django-versatileimagefield. Custom image field with direct access to created images through readable names and model mixin to inherit. Helper utils to delete created images, clear cache and warm images.

Installation

Install with pip:

$ pip install django-ok-images django-versatileimagefield

Update INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'versatileimagefield',
    ...
]

Available settings

IMAGE_ALLOWED_EXTENSIONS - Extensions for OptimizedImageField's FileExtensionValidator.

IMAGE_MAX_FILE_SIZE - Max file size of uploaded images in megabytes. Default to 10.

IMAGE_OPTIMIZE_QUALITY - Quality to optimize an uploaded image.

IMAGE_CREATE_ON_DEMAND - Custom value for django-versatileimagefield create_images_on_demand setting.

IMAGE_PLACEHOLDER_PATH - Default placeholder path for django-versatileimagefield.

IMAGE_RGBA_CHANGE_BACKGROUND - Changes background of RGBA images to white color.

IMAGE_LOSSLESS - Image lossless configuration. Default to False.

How to enable image optimization through TinyPNG:

TINYPNG_API_KEY_FUNCTION - Path to function, which returns TinyPNG api key.

TINYPNG_API_KEY - TinyPNG api key.

How to use

WebP sizers and filter:

Add next file in any app to register sizers and filters (more about sizers and filters):

# versatileimagefield.py

from ok_images.contrib.versatileimagefield.versatileimagefield import *

Fields:

There is an OptimizedImageField, inherited from VersatileImageField.

Example of usage:

Add next settings (more about rendition key sets):

# settings.py

VERSATILEIMAGEFIELD_RENDITION_KEY_SETS = {
    'product': [
        ('full_size', 'url'),
        ('desktop', 'crop__460x430'),
        ('catalog_preview', 'crop__180x180'),

        # webp
        ('desktop_webp', 'crop_webp__460x430'),
        ('catalog_preview_webp', 'crop_webp__180x180'),
    ],
}

Define a model like this:

# models.py
from ok_images.fields import OptimizedImageField


class Product(models.Model):
    image_sizes = 'product'  # could be set as a global rendition key set for an each image field

    image = OptimizedImageField(
        _('Image'),
        ppoi_field='ppoi',
        blank=True,
        null=True,
        # Optional keyword arguments with default values
        image_sizes_serializer=VersatileImageFieldSerializer,  # from versatileimagefield.serializers import VersatileImageFieldSerializer
        image_sizes='product',  # some of keys, defined in VERSATILEIMAGEFIELD_RENDITION_KEY_SETS setting
        create_on_demand=True,  # enables or disables on-demand image creation
    )
    ppoi = PPOIField(
        verbose_name=_('PPOI')
    )

If image_sizes is not defined, uses next default rendition key set:

IMAGE_DEFAULT_RENDITION_KEY_SET = [
    ('full_size', 'url'),
]

How to access generated previews:

product.image.full_size
product.image.catalog_preview
product.image.desktop_webp

Utils:

delete_all_created_images - delete all created images (can be skipped with delete_images argument) and clear cache for passed models.

warm_images - creates all sized images for a given instance or queryset with passed rendition key set.

# anywhere.py
from ok_images.utils import delete_all_created_images, warm_images


delete_all_created_images(Product, delete_images = False)
warm_images(product, 'product')

# `rendition_key_set` could be taken from field's or model's attrbiute `image_sizes`, otherwise uses default key set
warm_images(Product.objects.all())

Async image warming:

tasks.py:

from ok_images.utils import warm_images

@app.task
def images_warmer_task(product_pk: int):
    from store.models import Product
    product = Product.objects.get(pk=product_pk)
    warm_images(
        instance_or_queryset=product,
        image_attr='image'
    )

models.py:

from .tasks import images_warmer_task


def images_warmer(product):
    images_warmer_task.delay(product.pk)


class Product(models.Model):
    image_sizes = 'product'

    image = OptimizedImageField(
        _('Image'),
        ppoi_field='ppoi',
        blank=True,
        null=True,
        images_warmer=images_warmer
    )