cs-django-thumbnails 0.3.6
A simple Django app to manage image/photo thumbnails. Supports remote/cloud storage systems like Amazon S3.
License: MIT

|Build Status|

Design:

* Uses Django Storage API
* Uses flexible meta data store. Supports DB and Redis backend.

Installation
------------

* Add `thumbnails` to `INSTALLED_APPS` in `settings.py`.
* Run `python manage.py migrate` to create database metadata backend.


Usage
-----

settings.py:

.. code-block:: python

    THUMBNAILS = {
        'METADATA': {
            'BACKEND': 'thumbnails.backends.metadata.DatabaseBackend',
        },
        'STORAGE': {
            'BACKEND': 'django.core.files.storage.FileSystemStorage',
            # You can also use Amazon S3 or any other Django storage backends
        },
        'SIZES': {
            'small': {
                'PROCESSORS': [
                    {'PATH': 'thumbnails.processors.resize', 'width': 10, 'height': 10},
                    {'PATH': 'thumbnails.processors.crop', 'width': 80, 'height': 80}
                ],
                'POST_PROCESSORS': [
                    {
                        {'PATH': 'thumbnails.post_processors.optimize', 'png_command': 'optipng %(filename)s'},
                    },
                ],
            },
            'large': {
                'PROCESSORS': [
                    {'PATH': 'thumbnails.processors.resize', 'width': 20, 'height': 20},
                    {'PATH': 'thumbnails.processors.flip', 'direction': 'horizontal'}
                ],
            }
        }
    }

If you prefer to use Redis as your metadata storage backend (like I do :):

.. code-block:: python

    THUMBNAILS = {
        'METADATA': {
            'PREFIX': 'thumbs',
            'BACKEND': 'thumbnails.backends.metadata.RedisBackend',
            'db': 2,
            'port': 6379,
            'host': 'localhost',
        },
    }


In python:

.. code-block:: python

    from thumbnails.fields import ImageField

    class Food(models.Model):
        image = ImageField()


    food = Food.objects.latest('id')
    food.image.thumbnails.all()
    food.image.thumbnails.small  # Generates "small" sized thumbnail
    food.image.thumbnails.large  # Generates "large" sized thumbnail
    food.image.thumbnails.small.url  # Returns "small" sized thumbnail URL



`django-thumbnails` comes with a few builtin image processors::

    # To use the following processors, put the arguments of processors in SIZES definition
    thumbnails.processors.resize(width, height)
    thumbnails.processors.rotate(degrees)
    thumbnails.processors.flip(direction)
    thumbnails.processors.crop(width, height, center)

    Processors are applied sequentially in the same order of definition.


Performance
-----------

If you need to fetch multiple thumbnails at once, use ``fetch`` function for better performance. ``fetch`` uses Redis pipeline to retrieve thumbnail metadata in one go, avoiding multiple round trips to Redis.

.. code-block:: python

    from thumbnails.field import fetch_thumbnails

    food_a = Food.objects.get(id=1)
    food_b = Food.objects.get(id=2)

    fetch_thumbnails([food_a.image, food_b.image], ['small', 'large'])

This way, when we get thumbnails like `thumbnail1.size_small` or even `thumbnail1.all()` we won't query to `redis` anymore.
This feature is currently only available for `RedisBackend`.

Management Commands
-------------------
If you changed your size definition and want to regenerate the thumbnails, use::

    python manage.py delete_thumbnails --model=app.Model --size=thumbnail_size_to_delete


Running Tests
-------------
To run tests::

    `which django-admin.py` test thumbnails --settings=thumbnails.tests.settings --pythonpath=.


=========
Changelog
=========

Version 0.3.6
-------------
* Just some code cleanup nothing changed.
* Fixed wrong config on Readme.

Version 0.3.5
-------------
* Dropped support for python 3.5
* Dropped support for Django versions: 2.0, 2.1 (it still works just dropping further development.)

Version 0.3.4
-------------
* Removed support for python 2.
* Fixed project breaking if redis not installed.
* Fixed breaking on wrong configuration.
* Added support for django 3.

Version 0.3.3
-------------
* Just made small changes to check things out

Version 0.3.2
-------------
* Fixed another bug in `fetch_thumbnails()` bug. Thanks @marsha97!

Version 0.3.1
-------------
* Fixed `fetch_thumbnails()` bug. Thanks @marsha97!

Version 0.3.0
-------------
* Added `fetch_thumbnails()` command to fetch multiple thumbnail metadata from Redis. Thanks @marsha97!

Version 0.2.2
-------------
* Fixed `RedisBackend.get_thumbnail()` bug that may cause excessive trips to Redis. Thanks @marsha97!

Version 0.2.1
-------------
* Add support for Django 1.11, 2.0 and 2.1

Version 0.2.0
-------------
* Improves performance on fields that have a large number of thumbnails
* Add support for Django 1.8, 1.9 and 1.10

Version 0.1.3
-------------
* Fixes deprecation warning in Django 1.8

Version 0.1.2
-------------
* Fixes deprecation warning in Django 1.8

Version 0.1.1
-------------
* Use `shortuuid <https://github.com/stochastic-technologies/shortuuid>`_ instead of `uuid4()` to be more space efficient

Version 0.1.0
-------------
* First public release


As of February 2015, this library is suitable for production use and has been used for more than a year in `Stamps <http://stamps.co.id>`_, an Indonesian based CRM/loyalty system.


.. |Build Status| image:: https://travis-ci.org/ui/django-thumbnails.png?branch=master
   :target: https://travis-ci.org/ui/django-thumbnails