Skip to main content

Image field for Django

Project description


.. image::

.. image::
:alt: Documentation Status

Version |release|

Heavily based on `django-versatileimagefield
<>`_, but
with a few important differences:

- The amount of code is kept at a minimum. django-versatileimagefield
has several times as much code (without tests).
- Generating images on-demand inside rendering code is made hard on
purpose. Instead, images are generated when models are saved and also
by running the management command ``process_imagefields``.
- django-imagefield does not depend on a fast storage or a cache to be
and stay fast, at least as long as the image width and height is saved
in the database. An important part of this is never determining
whether a processed image exists in the hot path at all (except if you
``force`` it).
- django-imagefield fails early when image data is incomplete or not
processable by Pillow_ for some reason.
- django-imagefield allows adding width, height and PPOI (primary point
of interest) fields to the model by adding ``auto_add_fields=True`` to
the field instead of boringly and verbosingly adding them yourself.

Replacing existing uses of django-versatileimagefield requires the
following steps:

- ``from imagefield.fields import ImageField as VersatileImageField, PPOIField``
- Specify the image sizes by either providing ``ImageField(formats=...)`` or
adding the ``IMAGEFIELD_FORMATS`` setting. The latter overrides the
former if given.
- Convert template code to access the new properties (e.g.
``instance.image.square`` instead of ``instance.image.crop.200x200``
when using the ``IMAGEFIELD_FORMATS`` setting below).
- When using django-imagefield with a PPOI, make sure that the PPOI
field is also added to ``ModelAdmin`` or ``InlineModelAdmin``
fieldsets, otherwise you'll just see the image, but no PPOI picker.
Contrary to django-versatileimagefield the PPOI field is editable
itself, which avoids apart from other complexities a pitfall with
inline form change detection.
- Add ``"imagefield"`` to ``INSTALLED_APPS``.

If you used e.g. ``instance.image.crop.200x200`` and
``instance.image.thumbnail.800x500`` before, you should add the
following setting:

.. code-block:: python

# image field path, lowercase
'yourapp.yourmodel.image': {
'square': ['default', ('crop', (200, 200))],
'full': ['default', ('thumbnail', (800, 500))],

# The 'full' spec is equivalent to the following format
# specification in terms of image file produced (the
# resulting file name is different though):
# 'full': [
# 'autorotate', 'process_jpeg', 'process_gif', 'autorotate',
# ('thumbnail', (800, 500)),
# ],
# Note that the exact list of default processors may
# change in the future.

After running ``./ process_imagefields`` once you can now
use use ``instance.image.square`` and ``instance.image.thumbnail`` in
templates instead. Note that the properties on the ``image`` file do by
design not check whether thumbs exist.

Image processors

django-imagefield uses an image processing pipeline modelled after
Django's middleware.

The following processors are available out of the box:

- ``autorotate``: Autorotates an image by reading the EXIF data.
- ``process_jpeg``: Converts non-RGB images to RGB, activates
progressive encoding and sets quality to a higher value of 90.
- ``process_gif``: Preserves transparency and palette data in resized
- ``preserve_icc_profile``: As the name says.
- ``thumbnail``: Resizes images to not exceed a bounding box.
- ``crop``: Crops an image to the given dimensions, also takes the PPOI
(primary point of interest) information into account if provided.
- ``default``: The combination of ``autorotate``, ``process_jpeg``,
``process_gif`` and ``preserve_icc_profile``. Additional default
processors may be added in the future. It is recommended to use
``default`` instead of adding the processors one-by-one.

Processors can be specified either using their name alone, or if they
take arguments, using a tuple ``(processor_name, args...)``.

You can easily register your own processors or even override built-in
processors if you want to:

.. code-block:: python

from imagefield.processing import register

# You could also write a class with a __call__ method, but I really
# like the simplicity of functions.

def my_processor(get_image, args):
# args is either a list of arguments to the processor or an
# empty list
def processor(image, context):
# read some information from the image...
# or maybe modify it, but it's mostly recommended to modify
# the image after calling get_image

image, context = get_image(image, context)

# modify the image, and return it...
modified_image = ...
# maybe modify the context...
return modified_image, context
return processor

The processor's name is taken directly from the registered object.

The ``context`` is a ``types.SimpleNamespace`` containing the following
variables (but feel free to add your own):

- ``ppoi``: The primary point of interest as a list of two floats
between 0 and 1.
- ``save_kwargs``: A dictionary of keyword arguments to pass to

An example processor which converts images to grayscale would look as

.. code-block:: python

from PIL import ImageOps
from imagefield.processing import register

def grayscale(get_image, args):
def processor(image, context):
image, context = get_image(image, context)
return ImageOps.grayscale(image), context
return processor

Now include ``"grayscale"`` in the processing spec for the image where
you want to use it.


django-imagefield uses flake8 and black to keep the code clean and
formatted. Run both using tox_:

.. code-block:: bash

tox -e style

The easiest way to build the documentation and run the test suite is
also by using tox_:

.. code-block:: bash

tox -e docs # Open docs/build/html/index.html
tox -e tests

.. _documentation:
.. _Pillow:
.. _tox:

Project details

Download files

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

Files for django-imagefield, version 0.6.0
Filename, size File type Python version Upload date Hashes
Filename, size django_imagefield-0.6.0-py2.py3-none-any.whl (16.9 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size django-imagefield-0.6.0.tar.gz (12.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page