Enhanced ImageField with automatically generate thumbnail of the specified image
Project description
django-thumbnailfield
===============================================================================
.. image:: https://secure.travis-ci.org/lambdalisue/django-thumbnailfield.png
:target: http://travis-ci.org/lambdalisue/django-thumbnailfield
:alt: Build status
.. image:: https://coveralls.io/repos/lambdalisue/django-thumbnailfield/badge.png
:target: https://coveralls.io/r/lambdalisue/django-thumbnailfield/
:alt: Coverage
.. image:: https://pypip.in/d/django-thumbnailfield/badge.png
:target: https://pypi.python.org/pypi/django-thumbnailfield/
:alt: Downloads
.. image:: https://pypip.in/v/django-thumbnailfield/badge.png
:target: https://pypi.python.org/pypi/django-thumbnailfield/
:alt: Latest version
.. image:: https://pypip.in/wheel/django-thumbnailfield/badge.png
:target: https://pypi.python.org/pypi/django-thumbnailfield/
:alt: Wheel Status
.. image:: https://pypip.in/egg/django-thumbnailfield/badge.png
:target: https://pypi.python.org/pypi/django-thumbnailfield/
:alt: Egg Status
.. image:: https://pypip.in/license/django-thumbnailfield/badge.png
:target: https://pypi.python.org/pypi/django-thumbnailfield/
:alt: License
Author
Alisue <lambdalisue@hashnote.net>
Supported python versions
2.6, 2.7, 3.2, 3.3, 3.4
Supported django versions
1.3 - 1.6 and 1.7c1
django-thumbnailfield is a enhanced ImageField of Django.
It has the follwing features
- Using Django storage system to store the image (Not like other Thumbnail library)
- Automatically remove previous file from storage
- Automatically generate thumbnails
- Automatically remove generated previous thumbnail files from storage
- Easy to use custom method to generate thumbnails
Install
===========================================
::
sudo pip install django-thumbnailfield
Prepare to use
==========================================
1. Append 'thumbnailfield' to ``INSTALLED_APPS``
2. Set ``MEDIA_ROOT`` correctly.
For example::
MEDIA_ROOT = os.path.join(os.path.dirname(__file__), '../static')
Example mini blog app
=========================================
``models.py``::
from django.db import models
from django.contrib.auth.models import User
from thumbnailfield.fields import ThumbnailField
class Entry(models.Model):
PUB_STATES = (
('public', 'public entry'),
('protected', 'login required'),
('private', 'secret entry'),
)
pub_state = models.CharField('publish status', choices=PUB_STATES)
title = models.CharField('title', max_length=140)
body = models.TextField('body')
#
# This is a usage of ThumbnailField.
# You have to set ``patterns`` to generate thumbnails
#
thumbnail = ThumbnailField(_('thumbnail'), upload_to='img/thumbnails', null=True, blank=True,
pil_save_options={
# Options of PIL Image.save() method.
# e.g. quality control
'quality': 100,
},
patterns={
# Pattern Format:
# <Name>: (
# (<square_size>,), # with defautl process_method
# (<width>, <height>,), # with default process_method
# (<width>, <height>, <method or method_name>),
# (<width>, <height>, <method or method_name>, <method options>),
# )
#
# If Name is ``None`` that mean original image will be processed
# with the pattern
#
# Convert original image to sepia and resize it to 800x400 (original
# size is 804x762)
None: ((None, None, 'sepia'), (800, 400, 'resize')),
# Create 640x480 resized thumbnail as large.
'large': ((640, 480, 'resize'),),
# Create 320x240 cropped thumbnail as small. You can write short
# pattern if the number of appling pattern is 1
'small': (320, 240, 'crop', {'left': 0, 'upper': 0}),
# Create 160x120 thumbnail as tiny (use default process_method to
# generate)
'tiny': (160, 120),
#
# These thumbnails are not generated while accessed. These can be
# accessed with the follwoing code::
#
# entry.thumbnail.large
# entry.thumbnail.small
# entry.thumbnail.tiny
#
# # shortcut properties
# entry.thumbnail.large_file # as entry.thumbnail.large.file
# entry.thumbnail.large_path # as entry.thumbnail.large.path
# entry.thumbnail.large_url # as entry.thumbnail.large.url
# entry.thumbnail.large.size # as entry.thumbnail.large.size
#
})
# ...
``entry_detail.html``::
<html>
<head>
<title>django-thumbnailfield example</title>
</head>
<body>
<dl>
<dt>Original</dt>
<dd><img src="{{ MEDIA_URL }}{{ object.thumbnail }}"></dd>
<dt>Thumbnail "large"</dt>
<dd><img src="{{ MEDIA_URL }}{{ object.thumbnail.large }}"></dd>
<dt>Thumbnail "small"</dt>
<dd><img src="{{ MEDIA_URL }}{{ object.thumbnail.small }}"></dd>
<dt>Thumbnail "tiny"</dt>
<dd><img src="{{ MEDIA_URL }}{{ object.thumbnail.tiny }}"></dd>
</dl>
</body>
</html>
How to use custom process method
================================================================
Create your own custom process method like below::
from django.core.exceptions import ImproperlyConfigured
from thumbnailfield.process_methods import get_sepia_image
from thumbnailfield.process_methods import get_cropped_image
def get_sepia_and_cropped_image(img, width, height, **options):
# do something with img
img = get_sepia_image(img, None, None, **options)
img = get_cropped_image(img, width, height, **options)
return img
def _sepia_and_cropped_error_check(f, img, width, height, **options):
# do some error check
if 'left' not in options:
raise ImproperlyConfigured(f, "'left' is required")
if 'upper' not in options:
raise ImproperlyConfigured(f, "'upper' is required")
# Apply error check function
# Error check is recommended if your process method required any options
# otherwise just forget about this.
get_sepia_and_cropped_image.error_check = _sepia_and_cropped_error_check
Use defined method in pattern like below::
# models.py
# ...
thumbnail = ThumbnailField('thumbnail', upload_to='thumbnails', patterns = {
'large': (400, 500, get_sepia_and_cropped_image, {'left': 0, 'upper': 0})
}
# ...
Or define the method in THUMBNAILFIELD_PROCESS_METHOD_TABLE and use as a string anme::
# settings.py
from thumbnailfield import DEFAULT_PROCESS_METHOD_TABLE
THUMBNAILFIELD_PROCESS_METHOD_TABLE = DEFAULT_PROCESS_METHOD_TABLE
THUMBNAILFIELD_PROCESS_METHOD_TABLE['sepia_and_crop'] = get_sepia_and_cropped_image
# models.py
# ...
thumbnail = ThumbnailField('thumbnail', upload_to='thumbnails', patterns = {
'large': (400, 500, 'sepia_and_crop', {'left': 0, 'upper': 0})
}
# ...
If ``None`` is specified, that mean do nothing.
# models.py
# ...
thumbnail = ThumbnailField('thumbnail', upload_to='thumbnails', patterns = {
'original': None,
}
# ...
Settings
=========================================
``THUMBNAILFIELD_REMOVE_PREVIOUS``
Remove previous files (include original file) when new file is applied to
the ThumbnailField.
Default: ``False``
``THUMBNAILFIELD_DEFAULT_PROCESS_METHOD``
Used when no process_method is applied in process pattern.
Default: ``thumbnail``
``THUMBNAILFIELD_DEFAULT_PROCESS_OPTIONS``
Used when no process_options is applied in process pattern.
Default: ``{'resample': Image.ANTIALIAS}``
``THUMBNAILFIELD_FILENAME_PATTERN``
Used to determine thumbnail filename. ``root``, ``filename``, ``name``
and ``ext`` is passed to the string. The generated filename of the
thumbnail named 'large' of '/some/where/test.png' will be
``/some/where/test.large.png`` in default.
Default: ``r"%(root)s/%(filename)s.%(name)s.%(ext)s"``
``THUMBNAILFIELD_PROCESS_METHOD_TABLE``
Used to determine process method from string name. The key of this dictionary
is a name of the method and value is a method.
``thumbnail``, ``resize``, ``crop``, ``grayscale`` and ``sepia`` are defined
as default.
Default: See ``thumbnailfield.__init__.DEFAULT_PROCESS_METHOD_TABLE``
``THUMBNAILFIELD_DEFAULT_PIL_SAVE_OPTIONS``
Options used in PIL image save method.
Default: ``{}``
===============================================================================
.. image:: https://secure.travis-ci.org/lambdalisue/django-thumbnailfield.png
:target: http://travis-ci.org/lambdalisue/django-thumbnailfield
:alt: Build status
.. image:: https://coveralls.io/repos/lambdalisue/django-thumbnailfield/badge.png
:target: https://coveralls.io/r/lambdalisue/django-thumbnailfield/
:alt: Coverage
.. image:: https://pypip.in/d/django-thumbnailfield/badge.png
:target: https://pypi.python.org/pypi/django-thumbnailfield/
:alt: Downloads
.. image:: https://pypip.in/v/django-thumbnailfield/badge.png
:target: https://pypi.python.org/pypi/django-thumbnailfield/
:alt: Latest version
.. image:: https://pypip.in/wheel/django-thumbnailfield/badge.png
:target: https://pypi.python.org/pypi/django-thumbnailfield/
:alt: Wheel Status
.. image:: https://pypip.in/egg/django-thumbnailfield/badge.png
:target: https://pypi.python.org/pypi/django-thumbnailfield/
:alt: Egg Status
.. image:: https://pypip.in/license/django-thumbnailfield/badge.png
:target: https://pypi.python.org/pypi/django-thumbnailfield/
:alt: License
Author
Alisue <lambdalisue@hashnote.net>
Supported python versions
2.6, 2.7, 3.2, 3.3, 3.4
Supported django versions
1.3 - 1.6 and 1.7c1
django-thumbnailfield is a enhanced ImageField of Django.
It has the follwing features
- Using Django storage system to store the image (Not like other Thumbnail library)
- Automatically remove previous file from storage
- Automatically generate thumbnails
- Automatically remove generated previous thumbnail files from storage
- Easy to use custom method to generate thumbnails
Install
===========================================
::
sudo pip install django-thumbnailfield
Prepare to use
==========================================
1. Append 'thumbnailfield' to ``INSTALLED_APPS``
2. Set ``MEDIA_ROOT`` correctly.
For example::
MEDIA_ROOT = os.path.join(os.path.dirname(__file__), '../static')
Example mini blog app
=========================================
``models.py``::
from django.db import models
from django.contrib.auth.models import User
from thumbnailfield.fields import ThumbnailField
class Entry(models.Model):
PUB_STATES = (
('public', 'public entry'),
('protected', 'login required'),
('private', 'secret entry'),
)
pub_state = models.CharField('publish status', choices=PUB_STATES)
title = models.CharField('title', max_length=140)
body = models.TextField('body')
#
# This is a usage of ThumbnailField.
# You have to set ``patterns`` to generate thumbnails
#
thumbnail = ThumbnailField(_('thumbnail'), upload_to='img/thumbnails', null=True, blank=True,
pil_save_options={
# Options of PIL Image.save() method.
# e.g. quality control
'quality': 100,
},
patterns={
# Pattern Format:
# <Name>: (
# (<square_size>,), # with defautl process_method
# (<width>, <height>,), # with default process_method
# (<width>, <height>, <method or method_name>),
# (<width>, <height>, <method or method_name>, <method options>),
# )
#
# If Name is ``None`` that mean original image will be processed
# with the pattern
#
# Convert original image to sepia and resize it to 800x400 (original
# size is 804x762)
None: ((None, None, 'sepia'), (800, 400, 'resize')),
# Create 640x480 resized thumbnail as large.
'large': ((640, 480, 'resize'),),
# Create 320x240 cropped thumbnail as small. You can write short
# pattern if the number of appling pattern is 1
'small': (320, 240, 'crop', {'left': 0, 'upper': 0}),
# Create 160x120 thumbnail as tiny (use default process_method to
# generate)
'tiny': (160, 120),
#
# These thumbnails are not generated while accessed. These can be
# accessed with the follwoing code::
#
# entry.thumbnail.large
# entry.thumbnail.small
# entry.thumbnail.tiny
#
# # shortcut properties
# entry.thumbnail.large_file # as entry.thumbnail.large.file
# entry.thumbnail.large_path # as entry.thumbnail.large.path
# entry.thumbnail.large_url # as entry.thumbnail.large.url
# entry.thumbnail.large.size # as entry.thumbnail.large.size
#
})
# ...
``entry_detail.html``::
<html>
<head>
<title>django-thumbnailfield example</title>
</head>
<body>
<dl>
<dt>Original</dt>
<dd><img src="{{ MEDIA_URL }}{{ object.thumbnail }}"></dd>
<dt>Thumbnail "large"</dt>
<dd><img src="{{ MEDIA_URL }}{{ object.thumbnail.large }}"></dd>
<dt>Thumbnail "small"</dt>
<dd><img src="{{ MEDIA_URL }}{{ object.thumbnail.small }}"></dd>
<dt>Thumbnail "tiny"</dt>
<dd><img src="{{ MEDIA_URL }}{{ object.thumbnail.tiny }}"></dd>
</dl>
</body>
</html>
How to use custom process method
================================================================
Create your own custom process method like below::
from django.core.exceptions import ImproperlyConfigured
from thumbnailfield.process_methods import get_sepia_image
from thumbnailfield.process_methods import get_cropped_image
def get_sepia_and_cropped_image(img, width, height, **options):
# do something with img
img = get_sepia_image(img, None, None, **options)
img = get_cropped_image(img, width, height, **options)
return img
def _sepia_and_cropped_error_check(f, img, width, height, **options):
# do some error check
if 'left' not in options:
raise ImproperlyConfigured(f, "'left' is required")
if 'upper' not in options:
raise ImproperlyConfigured(f, "'upper' is required")
# Apply error check function
# Error check is recommended if your process method required any options
# otherwise just forget about this.
get_sepia_and_cropped_image.error_check = _sepia_and_cropped_error_check
Use defined method in pattern like below::
# models.py
# ...
thumbnail = ThumbnailField('thumbnail', upload_to='thumbnails', patterns = {
'large': (400, 500, get_sepia_and_cropped_image, {'left': 0, 'upper': 0})
}
# ...
Or define the method in THUMBNAILFIELD_PROCESS_METHOD_TABLE and use as a string anme::
# settings.py
from thumbnailfield import DEFAULT_PROCESS_METHOD_TABLE
THUMBNAILFIELD_PROCESS_METHOD_TABLE = DEFAULT_PROCESS_METHOD_TABLE
THUMBNAILFIELD_PROCESS_METHOD_TABLE['sepia_and_crop'] = get_sepia_and_cropped_image
# models.py
# ...
thumbnail = ThumbnailField('thumbnail', upload_to='thumbnails', patterns = {
'large': (400, 500, 'sepia_and_crop', {'left': 0, 'upper': 0})
}
# ...
If ``None`` is specified, that mean do nothing.
# models.py
# ...
thumbnail = ThumbnailField('thumbnail', upload_to='thumbnails', patterns = {
'original': None,
}
# ...
Settings
=========================================
``THUMBNAILFIELD_REMOVE_PREVIOUS``
Remove previous files (include original file) when new file is applied to
the ThumbnailField.
Default: ``False``
``THUMBNAILFIELD_DEFAULT_PROCESS_METHOD``
Used when no process_method is applied in process pattern.
Default: ``thumbnail``
``THUMBNAILFIELD_DEFAULT_PROCESS_OPTIONS``
Used when no process_options is applied in process pattern.
Default: ``{'resample': Image.ANTIALIAS}``
``THUMBNAILFIELD_FILENAME_PATTERN``
Used to determine thumbnail filename. ``root``, ``filename``, ``name``
and ``ext`` is passed to the string. The generated filename of the
thumbnail named 'large' of '/some/where/test.png' will be
``/some/where/test.large.png`` in default.
Default: ``r"%(root)s/%(filename)s.%(name)s.%(ext)s"``
``THUMBNAILFIELD_PROCESS_METHOD_TABLE``
Used to determine process method from string name. The key of this dictionary
is a name of the method and value is a method.
``thumbnail``, ``resize``, ``crop``, ``grayscale`` and ``sepia`` are defined
as default.
Default: See ``thumbnailfield.__init__.DEFAULT_PROCESS_METHOD_TABLE``
``THUMBNAILFIELD_DEFAULT_PIL_SAVE_OPTIONS``
Options used in PIL image save method.
Default: ``{}``
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Close
Hashes for django-thumbnailfield-0.2.5.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0a4a6960fc0086cf51a9c7c2b38352385c5b94d3deda740597155646517b77c7 |
|
MD5 | 6cc7e43da0050d73995148221a61e989 |
|
BLAKE2b-256 | 2c47dc3b93d0c30bb946ebb143b272d49cc4cf8d4742e158b0c8a2b75c065715 |