An open API service indexing awesome lists of open source software.

https://github.com/ricobl/django-thumbor

A django app with templatetags for resizing images with thumbor
https://github.com/ricobl/django-thumbor

Last synced: 29 days ago
JSON representation

A django app with templatetags for resizing images with thumbor

Awesome Lists containing this project

README

        

django-thumbor
==============

.. |build| image:: https://github.com/ricobl/django-thumbor/actions/workflows/test.yml/badge.svg?branch=master
:target: https://github.com/ricobl/django-thumbor/actions/workflows/test.yml
:alt: Test Build Status

.. |version| image:: http://img.shields.io/pypi/v/django-thumbor.svg
:target: https://pypi.python.org/pypi/django-thumbor/
:alt: Latest django-thumbor PyPI version

.. |downloads| image:: https://img.shields.io/pypi/dm/django-thumbor.svg
:target: https://pypi.python.org/pypi/django-thumbor/
:alt: Number of downloads for django-thumbor on PyPI

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

|build| |version| |downloads| |docs|

A django application to resize images using the
`thumbor `_ service.

Usage
-----

Both ``thumbor_url`` templatetag and the ``generate_url`` helper uses the same
arguments as `libthumbor `_, you can
check the `wiki `_ for more info.

On templates:

.. code-block:: html

{% load thumbor_tags %}

or

{% load thumbor_tags %}

If you need the result in a template variable, use `assign_thumbor_url` instead.

.. code-block:: html

{% load thumbor_tags %}
{% assign_thumbor_url '/media/image.jpg' width=300 as thumb_url %}

**Filters**

Split `filters `_ with
``:`` (or use a ``list`` object):

.. code-block:: html

{% load thumbor_tags %}

On code:

.. code-block:: python

from django_thumbor import generate_url
resized = generate_url("/media/image.jpg", width=300)

**Re-using argument sets (aliases)**

You can re-use argument sets through globally defined aliases. This prevents
repeating thumbnail parameters all over the code and can improve thumbor
performance because thumbnails are re-used as well. If you're migrating
from django-easy-thumbnails, you'll find the pattern very familiar, and it
should make porting much more straight-forward.

On templates:

.. code-block:: html

{% load thumbor_tags %}

On code:

.. code-block:: python

from django_thumbor import generate_url
resized = generate_url("/media/image.jpg", alias="thumb-square")

And in your ``settings.py``:

.. code-block:: python

THUMBOR_ALIASES = {
'thumb-square': {
'width': 300,
'height': 300,
'filters': ['brightness(10)']}
}

**Override server address**

There is an extra parameter to specify a custom server to be used instead of
``settings.THUMBOR_SERVER``.

On templates:

.. code-block:: html

{% load thumbor_tags %}

On code:

.. code-block:: python

from django_thumbor import generate_url
custom_server = "http://localhost:8888/foo"
resized = generate_url(
"/media/image.jpg", thumbor_server=custom_server, width=300)

Installation
------------

.. code-block:: bash

pip install django-thumbor

Configuration
-------------

Add the app to the ``INSTALLED_APPS``:

.. code-block:: python

INSTALLED_APPS = (
# ...
'django_thumbor',
)

Here are the default settings that you can override:

.. code-block:: python

# The host serving the thumbor resized images
THUMBOR_SERVER = 'http://localhost:8888'

# The prefix for the host serving the original images
# This must be a resolvable address to allow thumbor to reach the images
THUMBOR_MEDIA_URL = 'http://localhost:8000/media'

# If you want the static to be handled by django thumbor
# default as False, set True to handle it if you host your statics
THUMBOR_STATIC_ENABLED = False

# The prefix for the host serving the original static images
# this must be a resolvable address to allow thumbor to reach the images
THUMBOR_STATIC_URL = 'http://localhost:8000/static'

# The same security key used in the thumbor service to
# match the URL construction
THUMBOR_SECURITY_KEY = 'MY_SECURE_KEY'

# Default arguments passed to the `generate_url` helper or
# the `thumbor_url` templatetag
THUMBOR_ARGUMENTS = {}

# An alias represents a named set of arguments to the generate_url function
# or thumbor_url template tag. Use it to share general thumbnail
# configurations without repeating yourself.
THUMBOR_ALIASES = {}

Contributing
------------

Install
.......

Fork, clone, create a virtualenv and run:

.. code-block:: bash

git clone git://github.com/ricobl/django-thumbor.git
cd django-thumbor
pipenv shell
make install

Test
....

Add tests on ``testproject/tests``, add code and run:

.. code-block:: bash

make test

Test Server
...........

- Instal thumbor server: ``pip install thumbor``
- Run thumbor: ``thumbor``
- Run local server: ``make run``
- visit `http://127.0.0.1:8000/ `_:

Releasing
---------

Refer to the `.pypirc reference `_
for details on setting up API tokens.

Install ``build`` to build a package and ``twine`` to upload:

.. code-block:: bash

make setup_build

Upload to the `test server `_:

.. code-block:: bash

make upload_test

If everything goes well, release to the real PyPI server:

.. code-block:: bash

make release