Metadata-Version: 2.1
Name: easy-thumbnails
Version: 2.7.1
Summary: Easy thumbnails for Django
Home-page: http://github.com/SmileyChris/easy-thumbnails
Author: Chris Beaven
Author-email: smileychris@gmail.com
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.11
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.0
Classifier: Framework :: Django :: 3.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.5
License-File: LICENSE

===============
Easy Thumbnails
===============

.. image:: https://img.shields.io/pypi/v/easy-thumbnails.svg
    :target: https://pypi.python.org/pypi/easy-thumbnails/

.. image:: https://secure.travis-ci.org/SmileyChris/easy-thumbnails.svg?branch=master
    :alt: Build Status
    :target: http://travis-ci.org/SmileyChris/easy-thumbnails


A powerful, yet easy to implement thumbnailing application for Django 1.11+

Below is a quick summary of usage. For more comprehensive information, view the
`full documentation`__ online or the peruse the project's ``docs`` directory.

__ http://easy-thumbnails.readthedocs.org/en/latest/index.html


Installation
============

Run ``pip install easy-thumbnails``.

Add ``easy_thumbnails`` to your ``INSTALLED_APPS`` setting::

    INSTALLED_APPS = (
        ...
        'easy_thumbnails',
    )

Run ``manage.py migrate easy_thumbnails``.


Example usage
=============

Thumbnail options can be predefined in ``settings.THUMBNAIL_ALIASES`` or just
specified in the template or Python code when run.

Using a predefined alias
------------------------

Given the following setting::

    THUMBNAIL_ALIASES = {
        '': {
            'avatar': {'size': (50, 50), 'crop': True},
        },
    }

Template::

    {% load thumbnail %}
    <img src="{{ profile.photo|thumbnail_url:'avatar' }}" alt="" />

Python::

    from easy_thumbnails.files import get_thumbnailer
    thumb_url = get_thumbnailer(profile.photo)['avatar'].url

Manually specifying size / options
----------------------------------

Template::

    {% load thumbnail %}
    <img src="{% thumbnail profile.photo 50x50 crop %}" alt="" />

Python::

    from easy_thumbnails.files import get_thumbnailer
    options = {'size': (100, 100), 'crop': True}
    thumb_url = get_thumbnailer(profile.photo).get_thumbnail(options).url

Using in combination with other thumbnailers
--------------------------------------------

Alternatively, you load the templatetags by {% load easy_thumbnails_tags %} 
instead of traditional {% load thumbnail %}. It's especially useful in 
projects that do make use of multiple thumbnailer libraries that use the 
same name (`thumbnail`) for the templatetag module::

    {% load easy_thumbnails_tags %}
    <img src="{% thumbnail profile.photo 50x50 crop %}" alt="" />

Fields
======

You can use ``ThumbnailerImageField`` (or ``ThumbnailerField``) for easier
access to retrieve or generate thumbnail images.

For example::

    from easy_thumbnails.fields import ThumbnailerImageField

    class Profile(models.Model):
        user = models.OneToOneField('auth.User')
        photo = ThumbnailerImageField(upload_to='photos', blank=True)

Accessing the field's predefined alias in a template::

    {% load thumbnail %}
    <img src="{{ profile.photo.avatar.url }}" alt="" />

Accessing the field's predefined alias in Python code::

    thumb_url = profile.photo['avatar'].url


Thumbnail options
=================

``crop``
--------

Before scaling the image down to fit within the ``size`` bounds, it first cuts
the edges of the image to match the requested aspect ratio.

Use ``crop="smart"`` to try to keep the most interesting part of the image,

Use ``crop="0,10"`` to crop from the left edge and a 10% offset from the
top edge. Crop from a single edge by leaving dimension empty (e.g.
``crop=",0"``). Offset from the right / bottom by using negative numbers
(e.g., crop="-0,-10").

Often used with the ``upscale`` option, which will allow enlarging of the image
during scaling.

``quality=XX``
--------------

Changes the quality of the output JPEG thumbnail. Defaults to ``85``.

In Python code, this is given as a separate option to the ``get_thumbnail``
method rather than just alter the other

Other options
-------------

Valid thumbnail options are determined by the "thumbnail processors" installed.

See the `reference documentation`__ for a complete list of options provided by
the default thumbnail processors.

__ http://easy-thumbnails.readthedocs.org/en/latest/ref/processors/


Changes
=======

2.7.1 (2020-11-23)
------------------

* Add support for Django 3.1


2.7.0 (2019-12-15)
------------------

* Add support for Django 3.0
* Drop support for Python 2
* Drop support for Django < 1.11
* Drop support for Django 2.0, 2.1

2.6.0 (2019-02-03)
------------------

* Added testing for Django 2.2 (no code changes required).

2.5.0 (2017-10-31)
------------------

* Support Django versions up to 1.11. Version 2.0 is in beta.

* Fix: Pickle/unpickle machine. The ThumbnailerField fields no longer
  generated thumbnails.

* Removed all references to South migrations.


2.4.2 (2017-09-14)
------------------

* Supported Django versions are now 1.8 or 1.10+, Python 2.7 minimum.

* Fix IOError saving JPEG files with transparency on Pillow 4.2+.

* Fix #450, #473: fixed int/string is not a callable in management command.

* Fix #456: Delete method of ThumbnailerFieldFile is called twice.


2.4.1 (2017-04-05)
------------------

* New minimum requirement of Django 1.4 or 1.7+.

* Fix EXIF orientation to use transpose.

* Upgrades to avoid deprecation warnings.

* Fix app settings not working in Django 1.11.

* Fix a bad conditional check causing incorrect behaviour in autocropping
  transparent images.

* Django 1.8+ compatibility for ``thumbnail_cleanup`` command.

* Add ``easy_thumbnails_tags`` template tag mirror to allow multiple
  thumbnailer libraries to coexist happily.

* Limit pillow to its final compatible version when on Python 2.6

* Fix tests.

2.3 (2015-12-11)
----------------

* New ``Alias`` namer.

* Avoid a potential concurrency issue with creating the cache.

* Fix incorrect use of select_related for source thumbnail model.

* Removed some vestigal processor arguments.

* Allow ``HIGH_RESOLUTION`` argument on thumbnail template tag.

* Add logic to correctly handle thumbnail images on deferred models (e.g. when
  using ``.only()``).

* Add a ``data_uri`` filter to allow rendering of an image inline as a data
  uri.

2.2.1 (2014-12-30)
------------------

* Fixed: Option ``zoom`` can also be used by itself, without combining it with
  ``crop``.

2.2 (2014-10-04)
----------------

* Fix migrations for Django 1.7 final.

* Fix contain bad image EXIFs being able to still raise an exception.

2.1 (2014-08-13)
----------------

* Fix Python 3.4 installation issue.

* Avoid an OverflowError due to invalid EXIF data.

* Fix bug causing JPEG images to be saved without optimization :(

* JPEG files can now be saved with progressive encoding. By default, any image
  with a dimension larger than 100px will be saved progressively. Configured
  with the ``THUMBNAILER_PROGRESSIVE`` setting.

2.0.1 (2014-04-26)
------------------

* Fix packaging issue with old south migrations.

2.0 (2014-04-25)
----------------

* Use Django 1.7 migrations. Thanks Trey Hunner.
  **Note**: if using South, read the installation docs for required settings
  changes.

* Make ThumbnailerImageField.resize_source reflect change in extension.

* Add ``target`` option to the scale_and_crop processor, allowing for image
  focal points when cropping (or zooming) an image.

* Add a THUMBNAIL_NAMER option which takes a function used to customize
  the thumbnail filename.

* New ``subsampling`` option to reduce color subsampling of JPEG images,
  providing sharper color borders for a small increase in file size.

* Reimplementation of the ``thumbnail_cleanup`` command. Thanks Jørgen
  Abrahamsen

* More efficient thumbnail default storage. Thanks Sandip Agarwal.

1.5 (2014-03-05)
----------------

* Better support for multiple source generators.

* Update method used to check for modification dates of source and thumbnail
  images. Thanks Ben Roberts.

* Better thumbnail_high_resolution handling, including the ability to switch on
  and off explicitly with a ``HIGH_RESOLUTION`` thumbnail option.

* Added configuration option to specify the infix used for high resolution
  image handling.

* Optional postprocessor for image optimization. Thanks Jacob Rief!

* More remote storages optimization

* Thumbnail dimensions can now optionally be cached. Thanks David Novakovic.

* New ``zoom`` option to generate a thumbnail of a source image with a
  percentage clipped off each side.

* New ``background`` source processor that can add a border color to ensure
  scaled images fit within the exact dimensions given.

1.4 (2013-09-23)
----------------

* Considerable speed up for remote storages by reducing queries.
  Brent O'Connor spent a lot of time debugging this, so thank you epicserve!

* Allow the ``{% thumbnail %}`` tag to also accept aliases. Thanks Simon Meers!

* Make ``replace_alpha`` actually work correctly.

* Fixes exception being raised when image exists in cache but is doesn't
  actually exist in the storage.

* Fixes Python 2.5 compatibility.

1.3 (2013-06-17)
----------------

* Some more Django 1.5 fixes.

* Fix an issue with ``Thumbnail.url`` not working correctly.

* Add the ability to generate retina quality thumbnails in addition to the
  standard ones (off by default).

1.2 (2013-01-23)
----------------

* Django 1.5 compatibility.

* Fixed a problem with the ``ImageClearableFileInput`` widget.

1.1 (2012-08-29)
----------------

* Added a way to avoid generating thumbnails if they don't exist already (with
  a signal to deal with them elsewhere).

* Added a ``thumbnailer_passive`` filter to allow templates to use the
  non-generating thumbnails functionality when dealing with aliases.

1.0.3 (2012-05-30)
------------------

* Changed the exception to catch from 1.0.2 to IOError.

1.0.2 (2012-05-29)
------------------

* Catch an OSError exception when trying to get the EXIF data of a touchy
  image.

1.0.1 (2012-05-23)
------------------

* Fix a Django 1.2 backwards incompatibility in ``easy_thumbnails.conf``

* Introduced a ``thumbnail_created`` signal.

1.0 (2012-05-07)
----------------

* Introduction of aliased thumbnails.

* Start of sane versioning numbers.
