django-eximagination

Fetch external images directly from templates.

A Django template tag library which allows to download external images, store them locally and return the local path to locally stored image to a desired context variable, along with width and height attributes of the image fetched. Caches the fetched images locally for the given time (set in settings).

You could, for example, use this app to solve the problems with displaying of a mixed content (assets loaded from HTTP and HTTPS sources).

Prerequisites

  • Django 1.8, 1.9, 1.10
  • Python >=2.7, >=3.4

Installation

  1. Install django-eximagination

Latest stable version on PyPI:

pip install django-eximagination

Latest stable version from GitHub:

  1. Add eximagination to INSTALLED_APPS.
INSTALLED_APPS = (
    # ...
    'eximagination',
    # ...
)
  1. Configure

By default, django-eximagination expects your files to be stored in /media/external_images directory. If location varies, redefine the directories in your Django settings, make sure the path is writable and that www-data (or whatever is applicable) has rights to write into it.

import os

BASE_DIR = os.path.dirname(os.path.dirname(__file__))
MEDIA_ROOT = os.path.join(BASE_DIR, '..', '..', 'media')
EXIMAGINATION_MEDIA_ROOT = os.path.join(MEDIA_ROOT, 'external_images')
EXIMAGINATION_MEDIA_URL = '/media/external_images'
EXIMAGINATION_MEDIA_RELATIVE_ROOT = 'external_images/'
# After 30 days we re-fetch the file anyway.
EXIMAGINATION_EXPIRATION_INTERVAL = 2592000

Usage example (in a Django template)

See the example directory for working code example.

Example #1:

{% load eximaginate %}

<img src="{{ MEDIA_URL }}{% eximaginate 'http://www.google.com/intl/en/images/logo.gif' %}">

Example #2:

{% load eximaginate thumbnail %}

{% eximaginate 'http://www.google.com/intl/en/images/logo.gif' as original %}

<img src="{% thumbnail original 100x100 %}">

In both cases there are two additional context variables added:

  • ei_width - Width of the image
  • ei_height - Height of the image

License

GPL 2.0/LGPL 2.1

Support

For any issues contact me at the e-mail given in the Author section or open an issue on BitBucket/GitHub.

Documentation

Contents:

eximagination package

Subpackages

eximagination.templatetags package
Submodules
eximagination.templatetags.eximaginate module
eximagination.templatetags.eximaginate.eximaginate(parser, token)[source]

Copy an external image locally.

To just output the absolute url to the thumbnail:

{% load eximaginate %}

<img src="{{ MEDIA_URL }}
   {% eximaginate 'http://www.google.com/intl/en/images/logo.gif' %}">

To put the the downloaded image URL on the context instead of just rendering the relative url, finish the tag with as [context_var_name]:

{% load eximaginate thumbnail %}

{% eximaginate ‘http://www.google.com/intl/en/images/logo.gif‘
as original %}

<img src=”{% thumbnail original 100x100 %}”>

Eximagination will automatically add “ei_width” and “ei_height” variables to the content - those are the original width and height values of the obtained image.

TODO: Implement force_update feature (some extra tokens parsing)

Module contents

Submodules

eximagination.apps module

Apps.

class eximagination.apps.Config(app_name, app_module)[source]

Bases: django.apps.config.AppConfig

Config.

label = 'eximagination'
name = 'eximagination'

eximagination.conf module

eximagination.conf.get_setting(setting, override=None)[source]

Get setting.

Get a setting from eximagination conf module, falling back to the default.

If override is not None, it will be used instead of the setting.

Parameters:
  • setting – String with setting name
  • override – Value to use when no setting is available. Defaults to None.
Returns:

Setting value.

eximagination.defaults module

eximagination.helpers module

eximagination.helpers.project_dir(base)[source]

Get path to directory/file from current path.

eximagination.helpers.PROJECT_DIR(base)

Get path to directory/file from current path.

eximagination.settings module

eximagination.tests module

class eximagination.tests.EximaginationUtilsTest(methodName='runTest')[source]

Bases: unittest.case.TestCase

Tests of eximagination.utils.obtain_image function.

setUp()[source]

Set up.

test_01_obtain_image(*args, **kwargs)[source]
eximagination.tests.log_info(func)[source]

Log some useful info.

eximagination.utils module

eximagination.utils.obtain_image(image_source='', save_to='', media_url='', force_update=False, expiration_interval=None, debug=False)[source]

Get an image from absolute url and saves it locally.

Check whether image already exists in local directory and only if not - try to download it and save it. Validate validity of the image (rely on PIL Image class validation).

Parameters:
  • image_source (str) –
  • save_to (str) –
  • media_url (str) –
  • force_update (bool) –
  • expiration_interval (int) – Expiration interval in seconds.
  • debug (bool) –
Return list:

(relative_url_of_the_image, original_image_width, original_image_height)

Module contents

A Django template tag library which allows to download external images, store them locally and return the local path to locally stored image to a desired context variable, along with width and height of the image fetched. Caches the fetched images locally for the given time (set in settings). You could, for example, use this app to solve the problems with displaying of a mixed content (assets loaded from HTTP and HTTPS sources).

  • default_app_config: Default Django app config.
eximagination.obtain_image(image_source='', save_to='', media_url='', force_update=False, expiration_interval=None, debug=False)[source]

Get an image from absolute url and saves it locally.

Check whether image already exists in local directory and only if not - try to download it and save it. Validate validity of the image (rely on PIL Image class validation).

Parameters:
  • image_source (str) –
  • save_to (str) –
  • media_url (str) –
  • force_update (bool) –
  • expiration_interval (int) – Expiration interval in seconds.
  • debug (bool) –
Return list:

(relative_url_of_the_image, original_image_width, original_image_height)