Rename function icon to render_icon

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).

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"]

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()

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)

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

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),
             '<i class="user" title="user"></i>',
         )
-        user_icon = icon("user", title=_("user"), renderer=IconRenderer)
+
+    def test_render_icon(self):
+        self.assertEqual(
+            render_icon("user", title=_("user"), renderer=IconRenderer),
+            '<i class="user" title="user"></i>',
+        )
+
+    def test_laziness(self):
+        user_icon = render_icon("user", title=_("user"), renderer=IconRenderer)
         with translation.override("nl"):
             self.assertEqual(user_icon, '<i class="user" title="gebruiker"></i>')