From 7e0f41bd089203c22ad114925f000a843f356572 Mon Sep 17 00:00:00 2001 From: Dylan Verheul Date: Sat, 5 Jun 2021 10:07:11 +0200 Subject: [PATCH] Rename function `icon` to `render_icon` --- CHANGELOG.md | 1 + src/django_icons/__init__.py | 41 +-------------------- src/django_icons/core.py | 51 ++++++++++++++++++++++++++ src/django_icons/templatetags/icons.py | 6 +-- src/django_icons/utils.py | 1 + tests/test_core.py | 20 +++++++--- 6 files changed, 72 insertions(+), 48 deletions(-) create mode 100644 src/django_icons/core.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ae8b8f0..6d887ee0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## In development +- Deprecate `icon` because of frequent name collisions, use `render_icon` instead. - Fix CI. - Drop support for Django 3.1 (EOL). - Drop support for Python 3.6 (EOL). diff --git a/src/django_icons/__init__.py b/src/django_icons/__init__.py index 62f82d2c..2607923c 100644 --- a/src/django_icons/__init__.py +++ b/src/django_icons/__init__.py @@ -1,41 +1,4 @@ -from django.utils.functional import keep_lazy_text - from .__about__ import __version__ -from .utils import get_icon_kwargs, get_icon_renderer - -__all__ = ["__version__", "icon"] - - -@keep_lazy_text -def icon(name, *args, **kwargs): - """ - Render an icon. - - **Parameters**: - - name - The name of the icon to be rendered - - title - The title attribute for the icon - - :default: None (no title attribute rendered) - - renderer - The renderer to use for the icon - - :default: The default renderer as per ``settings.py``, or ultimately `FontAwesome4Renderer`. - - **Usage**:: - - icon(name) - - **Example**:: +from .core import icon, render_icon - icon('pencil') - icon('trash', title='Delete') - """ - icon_kwargs = get_icon_kwargs(name, *args, **kwargs) - renderer_class = get_icon_renderer(icon_kwargs.get("renderer", None)) - renderer = renderer_class(**icon_kwargs) - return renderer.render() +__all__ = ["__version__", "icon", "render_icon"] diff --git a/src/django_icons/core.py b/src/django_icons/core.py new file mode 100644 index 00000000..a83295fa --- /dev/null +++ b/src/django_icons/core.py @@ -0,0 +1,51 @@ +import warnings + +from django.utils.functional import keep_lazy_text + +from .utils import get_icon_kwargs, get_icon_renderer + + +@keep_lazy_text +def icon(name, *args, **kwargs): + """ + Render an icon. + + Deprecated because of frequent name collisions. + """ + warnings.warn("The `icon` function is deprecated, user `render_icon` instead.", DeprecationWarning) + return render_icon(name, *args, **kwargs) + + +@keep_lazy_text +def render_icon(name, *args, **kwargs): + """ + Render an icon. + + **Parameters**: + + name + The name of the icon to be rendered + + title + The title attribute for the icon + + :default: None (no title attribute rendered) + + renderer + The renderer to use for the icon + + :default: The default renderer as per ``settings.py``, or ultimately `FontAwesome4Renderer`. + + **Usage**:: + + icon(name) + + **Example**:: + + render_icon('pencil') + render_icon('trash', title='Delete') + """ + icon_kwargs = get_icon_kwargs(name, *args, **kwargs) + renderer_class = get_icon_renderer(icon_kwargs.get("renderer", None)) + renderer = renderer_class(**icon_kwargs) + return renderer.render() diff --git a/src/django_icons/templatetags/icons.py b/src/django_icons/templatetags/icons.py index 3931cfa5..254498ba 100644 --- a/src/django_icons/templatetags/icons.py +++ b/src/django_icons/templatetags/icons.py @@ -1,12 +1,12 @@ from django import template -from .. import icon +from ..core import render_icon register = template.Library() @register.simple_tag(name="icon") -def do_icon(name, *args, **kwargs): +def icon_tag(name, *args, **kwargs): """ Render an icon. @@ -41,4 +41,4 @@ def do_icon(name, *args, **kwargs): {% icon 'pencil' 'fa-big' %} {% icon 'trash' title='Delete' %} """ - return icon(name, *args, **kwargs) + return render_icon(name, *args, **kwargs) diff --git a/src/django_icons/utils.py b/src/django_icons/utils.py index 3c39d2bd..71bba057 100644 --- a/src/django_icons/utils.py +++ b/src/django_icons/utils.py @@ -46,6 +46,7 @@ def get_icon_kwargs(name, *args, **kwargs): extra_classes = icon_kwargs.get("extra_classes", "") icon_kwargs.update(kwargs) + extra_classes = merge_css_list(extra_classes, args, kwargs.get("extra_classes", "")) if extra_classes: icon_kwargs["extra_classes"] = extra_classes diff --git a/tests/test_core.py b/tests/test_core.py index 3fab568f..d8182242 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -2,7 +2,7 @@ from django.utils import translation from django.utils.translation import gettext_lazy as _ -from django_icons import icon +from django_icons.core import render_icon from django_icons.renderers import IconRenderer @@ -16,14 +16,22 @@ def test_version(self): self.assertEqual(len(parts), 2) -class IconFunctionTest(TestCase): - """Test the icon function.""" +class RenderIconFunctionTest(TestCase): + """Test the `render_icon` function.""" - def test_laziness(self): + def test_icon(self): self.assertEqual( - icon("user", title=_("user"), renderer=IconRenderer), + render_icon("user", title=_("user"), renderer=IconRenderer), '', ) - user_icon = icon("user", title=_("user"), renderer=IconRenderer) + + def test_render_icon(self): + self.assertEqual( + render_icon("user", title=_("user"), renderer=IconRenderer), + '', + ) + + def test_laziness(self): + user_icon = render_icon("user", title=_("user"), renderer=IconRenderer) with translation.override("nl"): self.assertEqual(user_icon, '')