Add thumbnail aliases (#15)

Added thumbnail aliases

Makefile

@@ -1,5 +1,6 @@
 clean:
-	@find . -iname '*.pyc' -delete
+	@find . -iname '*.pyc' -delete  # py2
+	@find . -iname '__pycache__' -delete  # py3
 	@rm -rf dist/ django_thumbor.egg-info/
 test: clean
 	@./manage.py test

README.rst

@@ -44,6 +44,9 @@ On templates:
     {% load thumbor_tags %}
     <img src="{% thumbor_url model.image_field width=300 %}" width="300" />
 
+
+**Filters**
+
 Split `filters <https://github.com/thumbor/thumbor/wiki/Filters>`_ with
 ``:`` (or use a ``list`` object):
 
@@ -60,6 +63,43 @@ On code:
     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 %}
+    <img src="{% thumbor_url '/media/image.jpg' alias="thumb-square" %}" />
+
+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``.
 
@@ -127,6 +167,11 @@ Here are the default settings that you can override:
     # 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
 ------------

django_thumbor/__init__.py

@@ -50,17 +50,32 @@ def _handle_url_field(url):
         return getattr(url, "url", "")
     return url
 
-def generate_url(image_url, **kwargs):
+def generate_url(image_url, alias=None, **kwargs):
     image_url = _handle_empty(image_url)
     image_url = _handle_url_field(image_url)
     image_url = _prepend_media_url(image_url)
     image_url = _prepend_static_url(image_url)
     image_url = _remove_schema(image_url)
 
-    kwargs = dict(conf.THUMBOR_ARGUMENTS, **kwargs)
-    thumbor_server = kwargs.pop(
+    if alias:
+        if alias not in conf.THUMBOR_ALIASES:
+            raise RuntimeError(
+                'Alias "{}" not found in alias map THUMBOR_ALIASES. '
+                'Only found these: {}'
+                .format(alias, ", ".join(conf.THUMBOR_ALIASES.keys())))
+        alias_args = conf.THUMBOR_ALIASES[alias]
+    else:
+        alias_args = {}
+
+    final_args = dict(conf.THUMBOR_ARGUMENTS)
+    final_args.update(alias_args)
+    final_args.update(kwargs)
+
+    thumbor_server = final_args.pop(
         'thumbor_server', conf.THUMBOR_SERVER).rstrip('/')
 
-    encrypted_url = crypto.generate(image_url=image_url, **kwargs).strip('/')
+    encrypted_url = crypto.generate(
+        image_url=image_url,
+        **final_args).strip('/')
 
     return '%s/%s' % (thumbor_server, encrypted_url)

django_thumbor/conf.py

@@ -22,3 +22,8 @@
                                'MY_SECURE_KEY')
 
 THUMBOR_ARGUMENTS = getattr(settings, 'THUMBOR_ARGUMENTS', {})
+
+# An alias represents a named set of arguments which may be passed to
+# the url generating function instead of the arguments. Allows re-use
+# of thumbnail types across the app.
+THUMBOR_ALIASES = getattr(settings, 'THUMBOR_ALIASES', {})

testproject/tests/test_generate_url.py

@@ -8,6 +8,13 @@
 
 
 URL = 'domain.com/path/image.jpg'
+ALIASES = {
+    'thumb-square': {
+        'width': 300,
+        'height': 300,
+        'filters': ['brightness(10)']}
+}
+
 
 class MockImageField():
     @property
@@ -111,6 +118,20 @@ def test_should_allow_overriding_args_from_settings(self):
             generate_url(image_url=URL, smart=False)
             mock.assert_called_with(image_url=URL, smart=False)
 
+    @override_settings(THUMBOR_ALIASES=ALIASES)
+    def test_should_apply_alias(self):
+        imp.reload(conf)
+        with patch('django_thumbor.crypto.generate') as mock:
+            generate_url(image_url=URL, alias='thumb-square')
+            mock.assert_called_with(
+                image_url=URL, width=300, height=300,
+                filters=['brightness(10)'])
+
+    def test_should_raise_with_nonexistent_alias(self):
+        imp.reload(conf)
+        with self.assertRaises(RuntimeError):
+            generate_url(image_url=URL, alias='thumb-square')
+
 
 class TestURLFixing(TestCase):
 

testproject/tests/test_thumbor_url_ttag.py

@@ -51,3 +51,8 @@ def test_should_accept_filters_from_a_list(self, generate_url):
             'url filters=filters'.format(':'.join(filters)),
             context={'filters': filters})
         generate_url.assert_called_with(image_url=self.url, filters=filters)
+
+    def test_should_pass_alias_through(self, generate_url):
+        self.render("url alias='thumb-square'")
+        generate_url.assert_called_with(image_url=self.url, alias="thumb-square")
+