Skip to main content

The easiest way to create thumbnails for your images with Django. Works with any storage backend.

Project description


# django-thumbs

Create thumbnails for your images with Django.

## Fork

Forked from <https://code.google.com/p/django-thumbs/>.

## Features

* Easy to integrate in your code (no database changes, works as an `ImageField`)
* Works with any storage backend
* Generates thumbnails after image is uploaded into memory
* Deletes thumbnails when the image file is deleted
* Provides easy access to the thumbnails' URLs (similar method as with `ImageField`)

## Example

from django.db import models
from django_thumbs.fields import ImageThumbsField

class Person(models.Model):

SIZES = (
{'code': 'avatar', 'wxh': '125x125', 'resize': 'crop'},
{'code': 'm', 'wxh': '640x480', 'resize': 'scale'},
{'code': '150', 'wxh': '150x150'}, # 'resize' defaults to 'scale'
)
photo = ImageThumbsField(upload_to='images', sizes=SIZES)

The field `photo` has a `sizes` attribute specifying desired sizes for the thumbnails. This field works the same way as `ImageField` but it also creates the desired thumbnails when uploading a new file and deletes the thumbnails when deleting the file.

With `ImageThumbsField` you retrieve the URL for every thumbnail specifying its size code. In this example we use `someone.photo.url_avatar`, `someone.photo.url_150` or `someone.photo.url_m` to get the thumbnail URL.

## Install

Install django-thumbs into a virtualenv using pip:

(env)$ pip install git+https://github.com/rrmerugu/django-thumbs-v2.git#egg=django-thumbs-v2

Add `thumbs` to your installed apps:

INSTALLED_APPS = (
# ...
'django_thumbs',
)

## Usage

* Import it in your `models.py` and replace `ImageField` with `ImageThumbsField` in your model
* Add a `sizes` attribute with a list of sizes you want to use for the thumbnails
* Make sure you have defined `STATIC_URL` in your settings.py

## Sizes

Each size is a dictionary that defines a thumbnail. For example,

SIZES = (
{'code': 'avatar', 'wxh': '125x125', 'resize': 'crop'},
{'code': 'm', 'wxh': '640x480', 'resize': 'scale'},
{'code': 'flatrow', 'wxh': 'x120'},
{'code': '150', 'wxh': '150x150'}, # 'resize' defaults to 'scale'
)

Size validation errors will raise `SizeError`.

### code (required)

matches re: `RE_CODE`

`code` is the size name. It appears in the thumb filename separated by `THUMBS_DELIMITER`. For example, `'original.jpg'` becomes `'original-small.jpg'` for the default delimiter `'-'` and code `'small'`.

### wxh (required)

matches re: `RE_WXH`

`wxh` is the width x height as a string.

Fixed width images are supported with `240x`. The thumbnail will be scaled
down *or up* to a 240 pixel width. Fixed height images are similarly
supported with `90x`.

### resize (optional)

default: `'scale'`
options: `'scale'` or `'crop'`

`resize` determines how the image will be resized.

`'scale'` resizes the thumb to `wxh`. For example, a 2000 x 1000 image will become 500 x 250 for `'scale'` and a `wxh` of `'500x500'`. `'scale'` does not enlarge a photo. A 200 x 100 image will remain 200 x 100 for `'scale'` and `wxh` of `'500x500'`. `'scale'` does not crop.

`'crop'` crops and centers the image fit `wxh` exactly. For example, a 2000 x 1000 image will become 500 x 500 for `'crop'` and a `wxh` of `'500x500'`. `'crop'` will enlarge a photo to exactly fit `wxh`. A 200 x 100 image will enlarge and crop to 500 x 500 for `'crop'` and `wxh` of `'500x500'`.

## Settings

`django-thumbs` will use default settings unless these settings are found in Django settings.

### THUMBS_DELIMITER

default: `'-'`

`THUMBS_DELIMITER` sets the delimiter between the original image base name and the thumb size `code`. For example, `'original.jpg'` becomes `'original-small.jpg'` for the default delimiter `'-'` and code `'small'`.

### THUMBS_JPG

default: `False`

Set `THUMBS_JPG` to `True` to force all thumbnails to `.jpg` format and file extension regardless of original image format or file extension.

### THUMBS_QUALITY

default: `75`

`THUMBS_QUALITY` sets PIL quality. See <http://www.pythonware.com/library/pil/handbook/format-jpeg.htm>

### THUMBS_OPTIMIZE

default: `True`

`THUMBS_OPTIMIZE` sets PIL optimize option on JPG or PNG images.

### THUMBS_PROGRESSIVE

default: `False`

`THUMBS_PROGRESSIVE` sets PIL progressive option on JPG images.

### THUMBS_AUTOROTATE

default: `True`

`THUMBS_AUTOROTATE` rotates thumbnails based on original EXIF data, if any.

## PublicS3BotoStorage

`PublicS3BotoStorage` generates clean URLs for Amazon S3 in code--without calling Amazon and without S3 querystring auth and expires. Hooray! URLs are `'public-read'`.

`PublicS3BotoStorage` is based on `S3BotoStorage_AllPublic` from <https://github.com/duointeractive/django-athumb>.

Add to `requirements.txt`:

django-storages==1.1.4
boto==2.5.2

In Django settings, instead of

DEFAULT_FILE_STORAGE = 'storages.backends.s3boto.S3BotoStorage'

use `PublicS3BotoStorage`:

DEFAULT_FILE_STORAGE = 'django_thumbs.backends.PublicS3BotoStorage'

`PublicS3BotoStorage` looks for `AWS_S3_SECURE_URLS` and `AWS_S3_CUSTOM_DOMAIN` settings. `AWS_S3_SECURE_URLS` sets `https` or `http`. `AWS_S3_CUSTOM_DOMAIN` sets custom domain or `s3.amazonaws.com`.

## Uninstall

At any time you can go back and use `ImageField` again without altering the database or anything else. Just replace `ImageThumbsField` with `ImageField` again and make sure you delete the `sizes` attribute. Everything will work the same way it worked before using django-thumbs. Just remember to delete generated thumbnails in the case you don't want to have them anymore.



Project details


Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-thumbs-v2, version 0.4.1
Filename, size File type Python version Upload date Hashes
Filename, size django_thumbs_v2-0.4.1-py2.py3-none-any.whl (11.7 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size django_thumbs_v2-0.4.1-py3-none-any.whl (11.7 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size django-thumbs-v2-0.4.1.tar.gz (7.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page