django-thumborstorage

March 8, 2022 · View on GitHub

===================== django-thumborstorage

.. image:: https://coveralls.io/repos/github/Starou/django-thumborstorage/badge.svg?branch=master :target: https://coveralls.io/github/Starou/django-thumborstorage?branch=master

.. image:: https://img.shields.io/pypi/v/django-thumborstorage.svg :target: https://pypi.python.org/pypi/django-thumborstorage

A Django custom storage for Thumbor.

Provides 2 custom storages classes: ThumborStorage and ThumborMigrationStorage.

Use ThumborMigrationStorage on an Imagefield that started with a classic FileSystemStorage you want to upgrade to Thumbor without migrating your old media. That way, Django continues to serve them from the file system until the image is changed.

Install

pip install django-thumborstorage

Dependencies ''''''''''''

Python 3.6+
Django 2.1 to 3.2
Requests_
Libthumbor_

Recommended:

Django-thumbor_ (to manage thumbnails).
Thumbor_

Usage

settings.py '''''''''''

Add django_thumborstorage in INSTALLED_APPS.

And set the following with your values:

.. code-block:: python

THUMBOR_SERVER = 'https://my.thumbor.server.com:8888'
THUMBOR_SECURITY_KEY = 'MY_SECURE_KEY'
# This may be a different host than THUMBOR_SERVER
# only reachable by your Django server.
THUMBOR_RW_SERVER = 'https://my.rw.thumbor.server.local:8888'

models.py '''''''''

Just set the storage parameter in the ImageField you want to manage with Thumbor:

.. code-block:: python

from django_thumborstorage.storages import ThumborStorage

class Stuff(models.Model):
    def upload_path(instance, filename):
        return 'stuffs/%s' % filename
    photo = models.ImageField(upload_to=upload_path,
                              storage=ThumborStorage(),
                              height_field='photo_height',
                              width_field='photo_width')
    photo_height = models.IntegerField(blank=True, null=True)
    photo_width = models.IntegerField(blank=True, null=True)

In the code '''''''''''

You can get the Thumbor uuid from the <ImageField> instance using:

.. code-block:: python

my_stuff.photo.storage.key(my_stuff.photo.name)

This is useful to generate_url() with Django-thumbor_ when original files are stored on Thumbor. Thus, you can pass the key as url parameter.

CHANGELOG

2.0.0 '''''

Add support for Django 3.2.

Possible breaking change

The leading / in the path of the file stored in the database has been removed due to a breaking change introduced un Django 3.2.11.

https://docs.djangoproject.com/en/4.0/releases/3.2.11/#cve-2021-45452-potential-directory-traversal-via-storage-save

That release handle seamlessly both pre-2.0.0 style (/image/...) and post-2.0.0 style paths (image/...) so there is not need to migrate your database to replace /image/... with image/....

1.13.0 ''''''