Skip to main content

Image field for Django

Project description

=================
django-imagefield
=================

.. image:: https://travis-ci.org/matthiask/django-imagefield.svg?branch=master
:target: https://travis-ci.org/matthiask/django-imagefield

.. image:: https://readthedocs.org/projects/django-imagefield/badge/?version=latest
:target: https://django-imagefield.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status

Version |release|

Heavily based on `django-versatileimagefield
<https://github.com/respondcreate/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

IMAGEFIELD_FORMATS = {
# 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 ``./manage.py 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
images.
- ``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.

@register
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 = get_image(image, context)

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

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

An example processor which converts images to grayscale would look as
follows:

.. code-block:: python

from PIL import ImageOps
from imagefield.processing import register

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

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


The processing context
======================

The ``context`` is a namespace with the following attributes (feel free
to add your own):

- ``processors``: The list of processors.
- ``name``: The name of the resulting image relative to its storages'
root.
- ``extension``: The extension of the source and target.
- ``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
``PIL.Image.save``.

The ``ppoi``, ``extension``, ``processors`` and ``name`` attributes
cannot be modified when running processors anymore. Under some
circumstances ``extension`` and ``name`` will not even be there.

If you want to modify the extension or file type, or create a different
processing pipeline depending on facts not known when configuring
settings you can use a callable instead of the list of processors. The
callable will receive the fieldfile and the context instance and must at
least set the context's ``processors`` attribute to something sensible.
Just as an example here's an image field which always returns JPEG
thumbnails:

.. code-block:: python

from imagefield.processing import register

@register
def force_jpeg(get_image, args):
def processor(image, context):
image = get_image(image, context)
context.save_kwargs["format"] = "JPEG"
context.save_kwargs["quality"] = 90
return image
return processor

def jpeg_processor_spec(fieldfile, context):
context.extension = ".jpg"
context.processors = [
"force_jpeg",
"autorotate",
("thumbnail", (200, 200)),
]

class Model(...):
image = ImageField(..., formats={"thumb": jpeg_processor_spec})

Of course you can also access the model instance through the field file
by way of its ``fieldfile.instance`` attribute and use those
informations to customize the pipeline.


Development
===========

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: https://django-imagefield.readthedocs.io/en/latest/
.. _Pillow: https://pillow.readthedocs.io/en/latest/
.. _tox: https://tox.readthedocs.io/


Project details


Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
django_imagefield-0.7.0-py2.py3-none-any.whl (15.4 kB) Copy SHA256 hash SHA256 Wheel py2.py3
django-imagefield-0.7.0.tar.gz (14.0 kB) Copy SHA256 hash SHA256 Source None

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 SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page