django-easy-icons 0.2.3__tar.gz

django_easy_icons-0.2.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_easy_icons-0.2.3/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.1
+Name: django-easy-icons
+Version: 0.2.3
+Summary: Easy, flexible icons for Django
+Home-page: https://github.com/SamuelJennings/django-easy-icons
+License: MIT
+Author: Sam
+Author-email: samuel.scott.jennings@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: django
+Description-Content-Type: text/markdown
+
+# Django Easy Icons
+
+Easy, flexible icons for Django templates with support for multiple rendering backends.
+
+## Overview
+
+Django Easy Icons provides a simple, consistent way to include icons in your Django templates. It supports multiple icon sources including SVG files, font icon libraries (like Font Awesome), and SVG sprite sheets.
+
+## Features
+
+- **Multiple Renderers**: Support for SVG files, font icons, and sprite sheets
+- **Template Integration**: Simple `{% icon %}` template tag
+- **Flexible Configuration**: Configure multiple icon sets with different renderers
+- **Attribute Merging**: Easily add classes and attributes to icons
+- **Caching**: Built-in renderer caching for performance
+
+## Installation
+
+```bash
+pip install django-easy-icons
+```
+
+Add `easy_icons` to your `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ... other apps
+    'easy_icons',
+]
+```
+
+## Quick Start
+
+### 1. Configure Icon Renderers
+
+Add configuration to your Django settings:
+
+```python
+EASY_ICONS = {
+    "default": {
+        "renderer": "easy_icons.renderers.SvgRenderer",
+        "config": {
+            "svg_dir": "icons",  # Template directory for SVG files
+            "default_attrs": {
+                "height": "1em",
+                "fill": "currentColor"
+            }
+        },
+        "icons": {
+            "home": "home.svg",
+            "user": "user.svg",
+            "settings": "cog.svg"
+        }
+    }
+}
+```
+
+### 2. Use in Templates
+
+```html
+{% load easy_icons %}
+
+<!-- Basic usage -->
+{% icon "home" %}
+
+<!-- With additional attributes -->
+{% icon "user" class="nav-icon" height="2em" %}
+
+<!-- Using specific renderer -->
+{% icon "heart" renderer="fontawesome" %}
+```
+
+### 3. Use in Python Code
+
+```python
+from easy_icons import icon
+
+# Basic usage
+home_icon = icon("home")
+
+# With attributes
+user_icon = icon("user", **{"class": "large", "data-role": "button"})
+
+# Using specific renderer
+fa_icon = icon("heart", renderer="fontawesome")
+```
+
+## Renderers
+
+### SVG Renderer
+
+Renders icons from SVG template files:
+
+```python
+EASY_ICONS = {
+    "svg": {
+        "renderer": "easy_icons.renderers.SvgRenderer",
+        "config": {
+            "svg_dir": "icons",
+            "default_attrs": {"class": "svg-icon"}
+        },
+        "icons": {
+            "home": "house.svg",
+            "user": "person.svg"
+        }
+    }
+}
+```
+
+### Provider Renderer
+
+For font icon libraries like Font Awesome:
+
+```python
+EASY_ICONS = {
+    "fontawesome": {
+        "renderer": "easy_icons.renderers.ProviderRenderer",
+        "config": {
+            "tag": "i"
+        },
+        "icons": {
+            "home": "fas fa-home",
+            "user": "fas fa-user",
+            "heart": "fas fa-heart"
+        }
+    }
+}
+```
+
+### Sprites Renderer
+
+For SVG sprite sheets:
+
+```python
+EASY_ICONS = {
+    "sprites": {
+        "renderer": "easy_icons.renderers.SpritesRenderer",
+        "config": {
+            "sprite_url": "/static/icons.svg"
+        },
+        "icons": {
+            "logo": "brand-logo",
+            "menu": "hamburger-menu"
+        }
+    }
+}
+```
+
+## Configuration
+
+### Multiple Renderers
+
+You can configure multiple renderers and choose which one to use:
+
+```python
+EASY_ICONS = {
+    "default": {
+        "renderer": "easy_icons.renderers.SvgRenderer",
+        "config": {"svg_dir": "icons"},
+        "icons": {"home": "home.svg"}
+    },
+    "fontawesome": {
+        "renderer": "easy_icons.renderers.ProviderRenderer",
+        "config": {"tag": "i"},
+        "icons": {"heart": "fas fa-heart"}
+    },
+    "sprites": {
+        "renderer": "easy_icons.renderers.SpritesRenderer",
+        "config": {"sprite_url": "/static/icons.svg"},
+        "icons": {"logo": "brand"}
+    }
+}
+```
+
+Use in templates:
+
+```html
+{% icon "home" %}  <!-- Uses default renderer -->
+{% icon "heart" renderer="fontawesome" %}
+{% icon "logo" renderer="sprites" %}
+```
+
+### Default Attributes
+
+Configure default attributes that will be applied to all icons from a renderer:
+
+```python
+"config": {
+    "default_attrs": {
+        "class": "icon",
+        "aria-hidden": "true",
+        "height": "1em"
+    }
+}
+```
+
+**Note**: Template tag attributes completely override default attributes - they don't merge.
+
+### Attribute Overriding
+
+Template tag attributes override default attributes:
+
+- Provided attributes completely replace defaults: `height="1em"` + `height="2em"` = `height="2em"`
+- This includes class attributes: `class="icon"` + `class="large"` = `class="large"`
+
+## Advanced Usage
+
+### Custom Renderers
+
+Create custom renderers by extending `BaseRenderer`:
+
+```python
+from easy_icons.base import BaseRenderer
+from django.utils.safestring import SafeString
+
+class CustomRenderer(BaseRenderer):
+    def render(self, name: str, **kwargs) -> SafeString:
+        resolved_name = self.get_icon(name)
+        attrs = self.build_attrs(**kwargs)
+        html = f'<custom-icon {attrs}>{resolved_name}</custom-icon>'
+        return self.safe_return(html)
+```
+
+### Disable Default Attributes
+
+Use `use_defaults=False` to ignore default attributes:
+
+```html
+{% icon "home" use_defaults=False class="only-this-class" %}
+```
+
+```python
+icon("home", use_defaults=False, **{"class": "only-this-class"})
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Install dependencies
+poetry install
+
+# Run tests
+poetry run pytest
+
+# Run tests with coverage
+poetry run pytest --cov=easy_icons --cov-report=html
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Run the test suite
+6. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for details.
+
+## Changelog
+
+### 0.1.0
+
+- Initial release
+- SVG, Provider, and Sprites renderers
+- Template tag support
+- Configuration system
+- Comprehensive test suite
+

django_easy_icons-0.2.3/README.md

@@ -0,0 +1,272 @@
+# Django Easy Icons
+
+Easy, flexible icons for Django templates with support for multiple rendering backends.
+
+## Overview
+
+Django Easy Icons provides a simple, consistent way to include icons in your Django templates. It supports multiple icon sources including SVG files, font icon libraries (like Font Awesome), and SVG sprite sheets.
+
+## Features
+
+- **Multiple Renderers**: Support for SVG files, font icons, and sprite sheets
+- **Template Integration**: Simple `{% icon %}` template tag
+- **Flexible Configuration**: Configure multiple icon sets with different renderers
+- **Attribute Merging**: Easily add classes and attributes to icons
+- **Caching**: Built-in renderer caching for performance
+
+## Installation
+
+```bash
+pip install django-easy-icons
+```
+
+Add `easy_icons` to your `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ... other apps
+    'easy_icons',
+]
+```
+
+## Quick Start
+
+### 1. Configure Icon Renderers
+
+Add configuration to your Django settings:
+
+```python
+EASY_ICONS = {
+    "default": {
+        "renderer": "easy_icons.renderers.SvgRenderer",
+        "config": {
+            "svg_dir": "icons",  # Template directory for SVG files
+            "default_attrs": {
+                "height": "1em",
+                "fill": "currentColor"
+            }
+        },
+        "icons": {
+            "home": "home.svg",
+            "user": "user.svg",
+            "settings": "cog.svg"
+        }
+    }
+}
+```
+
+### 2. Use in Templates
+
+```html
+{% load easy_icons %}
+
+<!-- Basic usage -->
+{% icon "home" %}
+
+<!-- With additional attributes -->
+{% icon "user" class="nav-icon" height="2em" %}
+
+<!-- Using specific renderer -->
+{% icon "heart" renderer="fontawesome" %}
+```
+
+### 3. Use in Python Code
+
+```python
+from easy_icons import icon
+
+# Basic usage
+home_icon = icon("home")
+
+# With attributes
+user_icon = icon("user", **{"class": "large", "data-role": "button"})
+
+# Using specific renderer
+fa_icon = icon("heart", renderer="fontawesome")
+```
+
+## Renderers
+
+### SVG Renderer
+
+Renders icons from SVG template files:
+
+```python
+EASY_ICONS = {
+    "svg": {
+        "renderer": "easy_icons.renderers.SvgRenderer",
+        "config": {
+            "svg_dir": "icons",
+            "default_attrs": {"class": "svg-icon"}
+        },
+        "icons": {
+            "home": "house.svg",
+            "user": "person.svg"
+        }
+    }
+}
+```
+
+### Provider Renderer
+
+For font icon libraries like Font Awesome:
+
+```python
+EASY_ICONS = {
+    "fontawesome": {
+        "renderer": "easy_icons.renderers.ProviderRenderer",
+        "config": {
+            "tag": "i"
+        },
+        "icons": {
+            "home": "fas fa-home",
+            "user": "fas fa-user",
+            "heart": "fas fa-heart"
+        }
+    }
+}
+```
+
+### Sprites Renderer
+
+For SVG sprite sheets:
+
+```python
+EASY_ICONS = {
+    "sprites": {
+        "renderer": "easy_icons.renderers.SpritesRenderer",
+        "config": {
+            "sprite_url": "/static/icons.svg"
+        },
+        "icons": {
+            "logo": "brand-logo",
+            "menu": "hamburger-menu"
+        }
+    }
+}
+```
+
+## Configuration
+
+### Multiple Renderers
+
+You can configure multiple renderers and choose which one to use:
+
+```python
+EASY_ICONS = {
+    "default": {
+        "renderer": "easy_icons.renderers.SvgRenderer",
+        "config": {"svg_dir": "icons"},
+        "icons": {"home": "home.svg"}
+    },
+    "fontawesome": {
+        "renderer": "easy_icons.renderers.ProviderRenderer",
+        "config": {"tag": "i"},
+        "icons": {"heart": "fas fa-heart"}
+    },
+    "sprites": {
+        "renderer": "easy_icons.renderers.SpritesRenderer",
+        "config": {"sprite_url": "/static/icons.svg"},
+        "icons": {"logo": "brand"}
+    }
+}
+```
+
+Use in templates:
+
+```html
+{% icon "home" %}  <!-- Uses default renderer -->
+{% icon "heart" renderer="fontawesome" %}
+{% icon "logo" renderer="sprites" %}
+```
+
+### Default Attributes
+
+Configure default attributes that will be applied to all icons from a renderer:
+
+```python
+"config": {
+    "default_attrs": {
+        "class": "icon",
+        "aria-hidden": "true",
+        "height": "1em"
+    }
+}
+```
+
+**Note**: Template tag attributes completely override default attributes - they don't merge.
+
+### Attribute Overriding
+
+Template tag attributes override default attributes:
+
+- Provided attributes completely replace defaults: `height="1em"` + `height="2em"` = `height="2em"`
+- This includes class attributes: `class="icon"` + `class="large"` = `class="large"`
+
+## Advanced Usage
+
+### Custom Renderers
+
+Create custom renderers by extending `BaseRenderer`:
+
+```python
+from easy_icons.base import BaseRenderer
+from django.utils.safestring import SafeString
+
+class CustomRenderer(BaseRenderer):
+    def render(self, name: str, **kwargs) -> SafeString:
+        resolved_name = self.get_icon(name)
+        attrs = self.build_attrs(**kwargs)
+        html = f'<custom-icon {attrs}>{resolved_name}</custom-icon>'
+        return self.safe_return(html)
+```
+
+### Disable Default Attributes
+
+Use `use_defaults=False` to ignore default attributes:
+
+```html
+{% icon "home" use_defaults=False class="only-this-class" %}
+```
+
+```python
+icon("home", use_defaults=False, **{"class": "only-this-class"})
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Install dependencies
+poetry install
+
+# Run tests
+poetry run pytest
+
+# Run tests with coverage
+poetry run pytest --cov=easy_icons --cov-report=html
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Run the test suite
+6. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for details.
+
+## Changelog
+
+### 0.1.0
+
+- Initial release
+- SVG, Provider, and Sprites renderers
+- Template tag support
+- Configuration system
+- Comprehensive test suite

django_easy_icons-0.2.3/pyproject.toml

@@ -0,0 +1,103 @@
+[tool.poetry]
+name = "django-easy-icons"
+version = "v0.2.3"
+description = "Easy, flexible icons for Django"
+authors = ["Sam <samuel.scott.jennings@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+packages = [{include = "easy_icons", from = "src"}]
+homepage = "https://github.com/SamuelJennings/django-easy-icons"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+django = "*"
+
+
+[tool.poetry.group.dev.dependencies]
+fairdm-dev-tools = {git = "https://github.com/FAIR-DM/dev-tools"}
+
+[tool.poetry.group.docs.dependencies]
+fairdm-docs = {git = "https://github.com/FAIR-DM/fairdm-docs", extras = ["sphinx_book_theme"]}
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = [".", "tests"]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py", "tests.py", "*_tests.py"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "--verbose",
+    "--tb=short",
+    "--cov=easy_icons",
+    "--cov-report=html",
+    "-ra",
+]
+filterwarnings = [
+    "ignore",
+    "ignore::DeprecationWarning",
+    "ignore::PendingDeprecationWarning"
+]
+
+[tool.coverage.report]
+skip_empty = true
+show_missing = true
+
+[tool.coverage.run]
+branch = true
+source = ["easy_icons"]
+
+[tool.djlint]
+profile = "django"
+indent = 2
+preserve_leading_space = true
+preserve_blank_lines = true
+format_attribute_template_tags = true
+format_css = true
+format_js = true
+max_line_length = 120
+max_attribute_length = 70
+include = "H006,H013,H020,H021,H023,H025,H030,H031"
+ignore = "H017"
+extension = "html"
+
+[tool.black]
+line-length = 120
+target-version = ['py38']
+preview = true
+
+[tool.isort]
+profile = "black"
+
+[tool.mypy]
+files = ["src/easy_icons"]
+disallow_untyped_defs = "False"
+disallow_any_unimported = "False"
+ignore_missing_imports = "True"
+no_implicit_optional = "True"
+check_untyped_defs = "False"
+warn_return_any = "True"
+warn_unused_ignores = "True"
+show_error_codes = "True"
+exclude = ["docs/","migrations/","tests/settings.py"]
+mypy_path = "src/easy_icons/"
+plugins = ["mypy_django_plugin.main"]
+
+[tool.django-stubs]
+django_settings_module = "tests.settings"
+ignore_missing_model_attributes = "True"
+
+[tool.deptry]
+extend_exclude = [
+    "tasks.py",
+    "tests/",
+    "example/",
+    "docs/"
+]
+
+[tool.deptry.per_rule_ignores]
+DEP003 = ["easy_icons"]

django_easy_icons-0.2.3/src/easy_icons/__init__.py

@@ -0,0 +1,29 @@
+"""Django Easy Icons - Flexible icon rendering for Django templates.
+
+This package provides a simple, consistent way to include icons in Django templates
+with support for multiple rendering backends including SVG files, font icon libraries,
+and SVG sprite sheets.
+
+Basic usage:
+    from easy_icons import icon
+
+    # Render an icon with default renderer
+    home_icon = icon("home")
+
+    # Render with attributes
+    user_icon = icon("user", height="2em", **{"class": "nav-icon"})
+
+    # Use specific renderer
+    fa_icon = icon("heart", renderer="fontawesome")
+
+Template usage:
+    {% load easy_icons %}
+    {% icon "home" %}
+    {% icon "user" class="nav-icon" %}
+    {% icon "heart" renderer="fontawesome" %}
+"""
+
+from .utils import icon
+
+__version__ = "0.1.0"
+__all__ = ["icon"]

django_easy_icons-0.2.3/src/easy_icons/apps.py

@@ -0,0 +1,9 @@
+from django.apps import AppConfig
+
+
+class EasyIconsConfig(AppConfig):
+    """Configuration for the Easy Icons Django app."""
+
+    name = "easy_icons"
+    default_auto_field = "django.db.models.BigAutoField"
+    verbose_name = "Easy Icons"

django_easy_icons-0.2.3/src/easy_icons/base.py

@@ -0,0 +1,110 @@
+"""Base renderer class and common functionality for django-easy-icons.
+
+This module provides the abstract base class that all icon renderers must inherit from,
+along with common functionality for attribute handling and icon name resolution.
+
+The BaseRenderer class handles:
+- Icon name mapping and resolution
+- HTML attribute building and merging
+- Default attribute management
+- Common interface for all renderers
+
+Example:
+    class MyRenderer(BaseRenderer):
+        def render(self, name: str, **kwargs) -> SafeString:
+            resolved_name = self.get_icon(name)
+            attrs = self.build_attrs(**kwargs)
+            return self.safe_return(f'<my-icon {attrs}>{resolved_name}</my-icon>')
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from django.forms.utils import flatatt
+from django.utils.safestring import SafeString, mark_safe
+
+from .exceptions import IconNotFoundError
+
+
+class BaseRenderer(ABC):
+    """Base class for all icon renderers.
+
+    Renderers now declare their configuration explicitly via ``__init__``
+    keyword arguments. The settings loader star-expands user supplied
+    ``config`` dictionaries directly into that initializer. Common shared
+    data (like icon name mappings) is still passed via ``icons``.
+    """
+
+    def __init__(
+        self, *, icons: dict[str, str] | None = None, default_attrs: dict[str, Any] | None = None, **_: Any
+    ):  # pragma: no cover - slim wrapper
+        """Initialize the base renderer.
+
+        Parameters
+        ----------
+        icons: Optional[Dict[str, str]]
+            Mapping of logical icon names to renderer-specific identifiers.
+        default_attrs: Optional[Dict[str, Any]]
+            Default HTML attributes applied (and mergeable) across all renders.
+        **_ : Any
+            Ignored extra keyword arguments (consumed by concrete subclasses).
+        """
+        self.icons = icons or {}
+        # Provide a unified place for managing default attributes so concrete
+        # renderers don't need to duplicate ``self.default_attrs = default_attrs or {}``.
+        self.default_attrs = (default_attrs or {}).copy()
+
+    def get_icon(self, name: str) -> str:
+        """Resolve icon name through renderer-specific icon mappings."""
+        try:
+            return self.icons[name]
+        except KeyError:
+            raise IconNotFoundError(f"Icon '{name}' not listed in available icons for {self.__class__.__name__}")
+
+    def build_attrs(self, use_defaults: bool = True, **kwargs: Any) -> str:
+        """Build HTML attributes string from configuration and provided kwargs.
+
+        Args:
+            use_defaults: Whether to merge with default attributes
+            **kwargs: Additional attributes to include
+
+        Returns:
+            HTML attributes string
+        """
+        if not use_defaults:
+            return flatatt(kwargs)
+
+        # creates a copy of default_attrs then override with kwargs
+        attrs = self.default_attrs.copy()
+        attrs.update(kwargs)
+
+        return flatatt(attrs)
+
+    @abstractmethod
+    def render(self, name: str, **kwargs: Any) -> SafeString:
+        """Render an icon with the given name and attributes.
+
+        Args:
+            name: The icon name to render
+            **kwargs: Additional attributes for the icon
+
+        Returns:
+            Safe HTML string containing the rendered icon
+        """
+        pass
+
+    def __call__(self, name: str, **kwargs: Any) -> SafeString:
+        """Make renderer instances callable.
+
+        Args:
+            name: The icon name to render
+            **kwargs: Additional attributes for the icon
+
+        Returns:
+            Safe HTML string containing the rendered icon
+        """
+        return self.render(name, **kwargs)
+
+    def safe_return(self, content: str) -> SafeString:
+        """Return HTML content marked as safe (internal helper)."""
+        return mark_safe(content)  # noqa: S308

django_easy_icons-0.2.3/src/easy_icons/exceptions.py

@@ -0,0 +1,34 @@
+"""Custom exceptions for django-easy-icons.
+
+This module defines the custom exception classes used throughout the django-easy-icons
+package to provide clear error messages for common failure scenarios.
+
+Exceptions:
+    IconNotFoundError: Raised when an icon name cannot be resolved
+    InvalidSvgError: Raised when SVG content is malformed or invalid
+
+These exceptions inherit from the standard Python Exception class and can be caught
+either specifically or as general exceptions.
+
+Example:
+    try:
+        icon("missing-icon")
+    except IconNotFoundError:
+        # Handle missing icon case
+        pass
+    except InvalidSvgError:
+        # Handle malformed SVG case
+        pass
+"""
+
+
+class IconNotFoundError(Exception):
+    """Raised when an icon name cannot be resolved or underlying asset is missing."""
+
+    pass
+
+
+class InvalidSvgError(Exception):
+    """Raised when SVG content is malformed or missing required elements."""
+
+    pass

django_easy_icons-0.2.3/src/easy_icons/renderers.py

@@ -0,0 +1,114 @@
+"""Concrete renderer implementations for django-easy-icons.
+
+All input validation responsibility is delegated to a single place:
+``BaseRenderer.get_icon``. Renderers themselves assume any name
+they receive has passed that minimal check and focus purely on output
+generation.
+
+The public API for consumers is ``easy_icons.utils.icon``; this module
+only exposes the concrete classes.
+"""
+
+from typing import Any
+
+from django.template.loader import render_to_string
+from django.utils.safestring import SafeString
+
+from .base import BaseRenderer
+from .exceptions import InvalidSvgError
+
+
+class SvgRenderer(BaseRenderer):
+    """Renderer for SVG icons sourced from template files.
+
+    Parameters
+    ----------
+    svg_dir: str = "icons"
+        Directory (template prefix) where SVG template fragments live.
+    default_attrs: dict | None
+        Default attributes to inject/merge into rendered SVG root element.
+    icons: dict[str,str] | None
+        Name mapping provided via settings.
+    """
+
+    def __init__(self, *, svg_dir: str = "icons", **kwargs: Any):
+        super().__init__(**kwargs)
+        self.svg_dir = svg_dir
+
+    def render(self, name: str, **kwargs: Any) -> SafeString:  # noqa: D401
+        resolved_name = self.get_icon(name)
+        template_name = f"{self.svg_dir}/{resolved_name}"
+        svg_str = render_to_string(template_name)
+        return self._inject_svg_attrs(svg_str, **kwargs)
+
+    def _inject_svg_attrs(self, svg_str: str, **kwargs: Any) -> SafeString:
+        """Inject attributes into the SVG element.
+
+        Args:
+            svg_str: The SVG content as a string
+            **kwargs: Additional attributes to inject into the SVG tag
+
+        Returns:
+            Safe HTML string with attributes injected
+        """
+        attrs = self.build_attrs(**kwargs)
+
+        if not attrs:
+            return self.safe_return(svg_str)
+
+        # Split on '<svg' to isolate the svg tag
+        before, sep, after = svg_str.partition("<svg")
+
+        if not sep:  # No '<svg' found
+            raise InvalidSvgError("No <svg> tag found in SVG content")
+
+        result = f"{before}<svg {attrs} {after.strip()}"
+        return self.safe_return(result)
+
+
+class ProviderRenderer(BaseRenderer):
+    """Renderer for provider / font icon classes using full class strings."""
+
+    template = '<{tag} class="{css_class}" {attrs}></{tag}>'
+
+    def __init__(self, *, tag: str = "i", **kwargs: Any):
+        super().__init__(**kwargs)
+        self.tag = tag
+
+    def render(self, name: str, **kwargs: Any) -> SafeString:  # noqa: D401
+        tag = self.tag
+        resolved_icon = f"{self.get_icon(name)} {kwargs.pop('class', '')} "
+        attrs = self.build_attrs(**kwargs)
+        element = self.template.format(tag=tag, css_class=resolved_icon.strip(), attrs=attrs).strip()
+        return self.safe_return(element)
+
+
+class SpritesRenderer(BaseRenderer):
+    """Renderer for SVG sprite symbols via <use>.
+
+    Parameters
+    ----------
+    sprite_url: str (required)
+        Base URL/path to the sprite sheet. Required; raises ValueError if missing.
+    default_attrs: dict | None
+        Default attributes for the outer <svg> element.
+    """
+
+    template = """<svg {attrs}>
+                    <use href="{sprite_url}#{resolved_name}"></use>
+                  </svg>"""
+
+    def __init__(self, *, sprite_url: str | None = None, **kwargs: Any):
+        if not sprite_url:
+            raise ValueError("SpritesRenderer requires 'sprite_url' keyword argument")
+        super().__init__(**kwargs)
+        self.sprite_url = sprite_url
+
+    def render(self, name: str, **kwargs: Any) -> SafeString:  # noqa: D401
+        resolved_name = self.get_icon(name)
+        sprite_url = self.sprite_url
+        attrs = self.build_attrs(**kwargs)
+
+        element = self.template.format(sprite_url=sprite_url, resolved_name=resolved_name, attrs=attrs).strip()
+
+        return self.safe_return(element)

django_easy_icons-0.2.3/src/easy_icons/templatetags/easy_icons.py

@@ -0,0 +1,53 @@
+"""Template tags for django-easy-icons.
+
+This module provides Django template tags for rendering icons in templates.
+The main template tag is {% icon %} which integrates with the django-easy-icons
+rendering system.
+
+Usage in templates:
+    {% load easy_icons %}
+
+    <!-- Basic usage -->
+    {% icon "home" %}
+
+    <!-- With attributes -->
+    {% icon "user" class="nav-icon" height="2em" %}
+
+    <!-- Using specific renderer -->
+    {% icon "heart" renderer="fontawesome" %}
+
+    <!-- With template variables -->
+    {% icon icon_name class=css_class %}
+
+The template tag supports all the same functionality as the Python icon() function,
+including multiple renderers, attribute merging, and Django's automatic HTML escaping.
+"""
+
+from django import template
+from django.utils.safestring import SafeString
+
+from .. import utils
+
+register = template.Library()
+
+
+@register.simple_tag
+def icon(name: str, renderer: str = "default", **kwargs) -> SafeString:
+    """Template tag to render an icon.
+
+    Usage:
+        {% icon "home" %}
+        {% icon "home" renderer="fontawesome" %}
+        {% icon "home" renderer="sprites" %}
+        {% icon "home" class="large" height="2em" %}
+        {% icon "heart" renderer="fontawesome" class="gold" %}
+
+    Args:
+        name: The icon name to render
+        renderer: Name of the renderer to use (defaults to 'default')
+        **kwargs: Additional attributes for the icon
+
+    Returns:
+        Safe HTML string containing the rendered icon
+    """
+    return utils.icon(name, renderer=renderer, **kwargs)

django_easy_icons-0.2.3/src/easy_icons/utils.py

@@ -0,0 +1,122 @@
+"""Main interface functions for django-easy-icons.
+
+This module provides the primary public API for the django-easy-icons package,
+including renderer management, caching, and the main icon() function used by
+both Python code and template tags.
+
+Functions:
+    get_renderer(name): Get a configured renderer instance by name
+    clear_cache(): Clear the renderer instance cache
+    icon(name, renderer, **kwargs): Render an icon using the specified renderer
+
+The icon() function is the main entry point for rendering icons and supports:
+- Multiple configured renderers
+- Attribute merging and customization
+- Caching for performance
+- Integration with Django's SafeString for secure HTML output
+
+Example:
+    # Basic usage
+    home_icon = icon("home")
+
+    # With custom attributes
+    user_icon = icon("user", **{"class": "large", "data-role": "button"})
+
+    # Using named renderer
+    fa_icon = icon("heart", renderer="fontawesome")
+"""
+
+from typing import Any, cast
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.utils.module_loading import import_string
+from django.utils.safestring import SafeString
+
+# Simple module-level cache for renderer instances
+_renderer_cache: dict[str, Any] = {}
+
+
+def get_renderer(name: str = "default") -> Any:
+    """Get a configured renderer instance.
+
+    Args:
+        name: Name of the renderer to get (defaults to 'default')
+
+    Returns:
+        Configured renderer instance
+
+    Raises:
+        ImproperlyConfigured: If renderer is not configured or cannot be imported
+    """
+    # Check cache first
+    if name in _renderer_cache:
+        return _renderer_cache[name]
+
+    # Get configuration from settings or use empty dict
+    config = getattr(settings, "EASY_ICONS", {})
+
+    # Validate basic configuration structure
+    if not isinstance(config, dict):
+        raise ImproperlyConfigured("EASY_ICONS setting must be a dictionary")
+
+    # Ensure requested renderer exists
+    if name not in config:
+        raise ImproperlyConfigured(f"Renderer '{name}' is not configured in EASY_ICONS")
+
+    renderer_config = config[name]
+
+    # Validate renderer configuration structure
+    if not isinstance(renderer_config, dict):
+        raise ImproperlyConfigured(f"EASY_ICONS['{name}'] must be a dictionary")
+
+    if "renderer" not in renderer_config:
+        raise ImproperlyConfigured(f"EASY_ICONS['{name}'] must specify a 'renderer' class path")
+
+    # Import and instantiate the renderer class
+    renderer_class_path = renderer_config["renderer"]
+
+    try:
+        renderer_class = import_string(renderer_class_path)
+    except ImportError as e:
+        raise ImproperlyConfigured(f"Cannot import renderer class '{renderer_class_path}': {e}")
+
+    # Extract configuration options
+    renderer_kwargs = renderer_config.get("config", {}) or {}
+    renderer_icons = renderer_config.get("icons", {}) or {}
+
+    # Create instance
+    try:
+        renderer_instance = renderer_class(
+            icons=renderer_icons,
+            **renderer_kwargs,
+        )
+    except Exception as e:
+        raise ImproperlyConfigured(f"Cannot instantiate renderer '{name}' with class '{renderer_class_path}': {e}")
+
+    # Cache the instance
+    _renderer_cache[name] = renderer_instance
+    return renderer_instance
+
+
+def clear_cache() -> None:
+    """Clear renderer cache.
+
+    Useful for testing and development when settings might change.
+    """
+    _renderer_cache.clear()
+
+
+def icon(name: str, renderer: str = "default", **kwargs: Any) -> SafeString:
+    """Render an icon using the specified or default renderer.
+
+    Args:
+        name: The icon name to render
+        renderer: Name of the renderer to use (defaults to 'default')
+        **kwargs: Additional attributes for the icon
+
+    Returns:
+        Safe HTML string containing the rendered icon
+    """
+    renderer_instance = get_renderer(renderer)
+    return cast(SafeString, renderer_instance(name, **kwargs))