django-simple-icons 16.26.0__tar.gz

django_simple_icons-16.26.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 M4p4
+
+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_simple_icons-16.26.0/MANIFEST.in

@@ -0,0 +1 @@
+include src/django_simple_icons/simple-icons.zip

django_simple_icons-16.26.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: django-simple-icons
+Version: 16.26.0
+Summary: Use Simple Icons brand icons in your Django and Jinja templates.
+Author-email: M4p4 <homejr@protonmail.com>
+License-Expression: MIT
+Project-URL: Changelog, https://github.com/M4p4/django-simple-icons/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/M4p4/django-simple-icons
+Keywords: django,icons,jinja,simple-icons,svg
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: jinja
+Requires-Dist: jinja2>=2.8; extra == "jinja"
+Dynamic: license-file
+
+# django-simple-icons
+
+[![PyPI version](https://img.shields.io/pypi/v/django-simple-icons.svg)](https://pypi.org/project/django-simple-icons/)
+[![Python versions](https://img.shields.io/pypi/pyversions/django-simple-icons.svg)](https://pypi.org/project/django-simple-icons/)
+[![CI](https://github.com/M4p4/django-simple-icons/actions/workflows/main.yml/badge.svg)](https://github.com/M4p4/django-simple-icons/actions/workflows/main.yml)
+
+Use [Simple Icons](https://simpleicons.org/), 3,449 SVG brand icons, in your Django and
+Jinja templates. The icons ship inside the package, so there is no CDN to call and no
+static files to collect. Each icon renders as inline SVG that follows the surrounding
+text color.
+
+## Installation
+
+Install with the extra matching your template engine:
+
+```console
+python -m pip install 'django-simple-icons[django]'
+python -m pip install 'django-simple-icons[jinja]'
+```
+
+The package itself has no runtime dependencies and needs Python 3.12 or later.
+
+## Django
+
+Add the app to `INSTALLED_APPS` so the template tag library can be loaded:
+
+```python
+INSTALLED_APPS = [
+    ...,
+    "django_simple_icons",
+]
+```
+
+Then load the library and render an icon by its slug:
+
+```html
+{% load simple_icons %}
+
+{% simple_icon "django" %}
+```
+
+That produces a 24x24 inline SVG which inherits the current text color and is hidden
+from screen readers:
+
+```html
+<svg viewBox="0 0 24 24" width="24" height="24" fill="currentColor" aria-hidden="true"><path d="M11.146 0h3.924…"/></svg>
+```
+
+### Sizing
+
+`size` sets both `width` and `height` and defaults to 24:
+
+```html
+{% simple_icon "django" size=48 %}
+```
+
+Pass `size=None` to omit both attributes, which is what you want when CSS classes
+control the size:
+
+```html
+{% simple_icon "django" size=None class="h-6 w-6" %}
+```
+
+### Color
+
+Icons use `fill="currentColor"` by default, so they follow the surrounding text. Pass
+`color="brand"` to use the brand's official color, or any CSS color to set it directly:
+
+```html
+{% simple_icon "django" color="brand" %}
+{% simple_icon "django" color="#ff6600" %}
+```
+
+### Extra attributes
+
+Any other keyword argument becomes an attribute on the `<svg>` element, with
+underscores converted to dashes:
+
+```html
+{% simple_icon "django" class="h-6 w-6 text-green-700" data_controller="icon" %}
+```
+
+```html
+<svg viewBox="0 0 24 24" width="24" height="24" fill="currentColor" aria-hidden="true" class="h-6 w-6 text-green-700" data-controller="icon"><path d="M11.146 0h3.924…"/></svg>
+```
+
+Values are escaped, so `data_test="a < 2"` renders as `data-test="a &lt; 2"`.
+
+### Accessibility
+
+Icons are decorative by default, so the upstream `<title>` is removed and
+`aria-hidden="true"` is set. An icon next to a text label needs nothing more.
+
+For a standalone icon that carries meaning, pass `title=True` to keep the brand name as
+the accessible name, or pass a string to replace it:
+
+```html
+{% simple_icon "django" title=True %}
+{% simple_icon "django" title="Django framework" %}
+```
+
+Either form keeps `role="img"` and drops `aria-hidden`:
+
+```html
+<svg role="img" viewBox="0 0 24 24" width="24" height="24" fill="currentColor"><title>Django framework</title><path d="M11.146 0h3.924…"/></svg>
+```
+
+## Jinja
+
+Register the function as a global on your environment:
+
+```python
+from django_simple_icons.jinja import simple_icon
+
+environment.globals["simple_icon"] = simple_icon
+```
+
+Call it with the same arguments as the Django tag:
+
+```jinja
+{{ simple_icon("django") }}
+{{ simple_icon("django", size=48, color="brand") }}
+{{ simple_icon("django", title="Django framework") }}
+```
+
+The result is a `markupsafe.Markup`, so it renders unescaped under autoescaping.
+
+Because `class` is a reserved word in Python, spell it `class_` when calling the
+function directly. The trailing underscore is stripped:
+
+```jinja
+{{ simple_icon("django", class_="h-6 w-6") }}
+```
+
+## Arguments
+
+| Argument  | Default          | Description                                                |
+| --------- | ---------------- | ---------------------------------------------------------- |
+| `name`    | required         | The icon slug, such as `"django"`                           |
+| `size`    | `24`             | Sets `width` and `height`; `None` omits both                |
+| `color`   | `"currentColor"` | Any CSS color, or `"brand"` for the brand's official color  |
+| `title`   | `False`          | `True` keeps the brand name, a string replaces it           |
+| `**attrs` | none             | Extra attributes; underscores become dashes                 |
+
+## Brand colors
+
+`get_brand_color` returns a brand's official color, which is useful outside a template:
+
+```pycon
+>>> from django_simple_icons import get_brand_color
+>>> get_brand_color("django")
+'#092E20'
+```
+
+## Finding icon slugs
+
+Slugs match the names on [simpleicons.org](https://simpleicons.org/), where you can
+search the full set. An unknown slug raises `IconDoesNotExist` with suggestions:
+
+```pycon
+>>> from django_simple_icons import get_brand_color
+>>> get_brand_color("djngo")
+Traceback (most recent call last):
+  ...
+django_simple_icons.IconDoesNotExist: Icon 'djngo' does not exist. Did you mean: django, deno, fandango? Browse the available icons at https://simpleicons.org/
+```
+
+## Supported versions
+
+- Python 3.12, 3.13 and 3.14
+- Django 5.2, 6.0 and 6.1 are tested. Django is declared as `>=4.2` because the code
+  uses nothing newer, but only the tested versions are supported.
+- Jinja2 2.8 and later
+
+## Versioning
+
+The package version mirrors the bundled Simple Icons release, so version 16.26.0
+contains Simple Icons 16.26.0. A fix to this package that ships no new icons appends a
+fourth segment, such as 16.26.0.1.
+
+## License
+
+The code in this package is MIT licensed. The icons come from Simple Icons and are
+[CC0-1.0](https://github.com/simple-icons/simple-icons/blob/master/LICENSE.md).
+
+Brand icons and names are trademarks of their respective owners. Using an icon does not
+imply endorsement, and some brands restrict how their marks may be used. Read the
+[Simple Icons legal disclaimer](https://github.com/simple-icons/simple-icons/blob/master/DISCLAIMER.md)
+before shipping an icon.

django_simple_icons-16.26.0/README.md

@@ -0,0 +1,189 @@
+# django-simple-icons
+
+[![PyPI version](https://img.shields.io/pypi/v/django-simple-icons.svg)](https://pypi.org/project/django-simple-icons/)
+[![Python versions](https://img.shields.io/pypi/pyversions/django-simple-icons.svg)](https://pypi.org/project/django-simple-icons/)
+[![CI](https://github.com/M4p4/django-simple-icons/actions/workflows/main.yml/badge.svg)](https://github.com/M4p4/django-simple-icons/actions/workflows/main.yml)
+
+Use [Simple Icons](https://simpleicons.org/), 3,449 SVG brand icons, in your Django and
+Jinja templates. The icons ship inside the package, so there is no CDN to call and no
+static files to collect. Each icon renders as inline SVG that follows the surrounding
+text color.
+
+## Installation
+
+Install with the extra matching your template engine:
+
+```console
+python -m pip install 'django-simple-icons[django]'
+python -m pip install 'django-simple-icons[jinja]'
+```
+
+The package itself has no runtime dependencies and needs Python 3.12 or later.
+
+## Django
+
+Add the app to `INSTALLED_APPS` so the template tag library can be loaded:
+
+```python
+INSTALLED_APPS = [
+    ...,
+    "django_simple_icons",
+]
+```
+
+Then load the library and render an icon by its slug:
+
+```html
+{% load simple_icons %}
+
+{% simple_icon "django" %}
+```
+
+That produces a 24x24 inline SVG which inherits the current text color and is hidden
+from screen readers:
+
+```html
+<svg viewBox="0 0 24 24" width="24" height="24" fill="currentColor" aria-hidden="true"><path d="M11.146 0h3.924…"/></svg>
+```
+
+### Sizing
+
+`size` sets both `width` and `height` and defaults to 24:
+
+```html
+{% simple_icon "django" size=48 %}
+```
+
+Pass `size=None` to omit both attributes, which is what you want when CSS classes
+control the size:
+
+```html
+{% simple_icon "django" size=None class="h-6 w-6" %}
+```
+
+### Color
+
+Icons use `fill="currentColor"` by default, so they follow the surrounding text. Pass
+`color="brand"` to use the brand's official color, or any CSS color to set it directly:
+
+```html
+{% simple_icon "django" color="brand" %}
+{% simple_icon "django" color="#ff6600" %}
+```
+
+### Extra attributes
+
+Any other keyword argument becomes an attribute on the `<svg>` element, with
+underscores converted to dashes:
+
+```html
+{% simple_icon "django" class="h-6 w-6 text-green-700" data_controller="icon" %}
+```
+
+```html
+<svg viewBox="0 0 24 24" width="24" height="24" fill="currentColor" aria-hidden="true" class="h-6 w-6 text-green-700" data-controller="icon"><path d="M11.146 0h3.924…"/></svg>
+```
+
+Values are escaped, so `data_test="a < 2"` renders as `data-test="a &lt; 2"`.
+
+### Accessibility
+
+Icons are decorative by default, so the upstream `<title>` is removed and
+`aria-hidden="true"` is set. An icon next to a text label needs nothing more.
+
+For a standalone icon that carries meaning, pass `title=True` to keep the brand name as
+the accessible name, or pass a string to replace it:
+
+```html
+{% simple_icon "django" title=True %}
+{% simple_icon "django" title="Django framework" %}
+```
+
+Either form keeps `role="img"` and drops `aria-hidden`:
+
+```html
+<svg role="img" viewBox="0 0 24 24" width="24" height="24" fill="currentColor"><title>Django framework</title><path d="M11.146 0h3.924…"/></svg>
+```
+
+## Jinja
+
+Register the function as a global on your environment:
+
+```python
+from django_simple_icons.jinja import simple_icon
+
+environment.globals["simple_icon"] = simple_icon
+```
+
+Call it with the same arguments as the Django tag:
+
+```jinja
+{{ simple_icon("django") }}
+{{ simple_icon("django", size=48, color="brand") }}
+{{ simple_icon("django", title="Django framework") }}
+```
+
+The result is a `markupsafe.Markup`, so it renders unescaped under autoescaping.
+
+Because `class` is a reserved word in Python, spell it `class_` when calling the
+function directly. The trailing underscore is stripped:
+
+```jinja
+{{ simple_icon("django", class_="h-6 w-6") }}
+```
+
+## Arguments
+
+| Argument  | Default          | Description                                                |
+| --------- | ---------------- | ---------------------------------------------------------- |
+| `name`    | required         | The icon slug, such as `"django"`                           |
+| `size`    | `24`             | Sets `width` and `height`; `None` omits both                |
+| `color`   | `"currentColor"` | Any CSS color, or `"brand"` for the brand's official color  |
+| `title`   | `False`          | `True` keeps the brand name, a string replaces it           |
+| `**attrs` | none             | Extra attributes; underscores become dashes                 |
+
+## Brand colors
+
+`get_brand_color` returns a brand's official color, which is useful outside a template:
+
+```pycon
+>>> from django_simple_icons import get_brand_color
+>>> get_brand_color("django")
+'#092E20'
+```
+
+## Finding icon slugs
+
+Slugs match the names on [simpleicons.org](https://simpleicons.org/), where you can
+search the full set. An unknown slug raises `IconDoesNotExist` with suggestions:
+
+```pycon
+>>> from django_simple_icons import get_brand_color
+>>> get_brand_color("djngo")
+Traceback (most recent call last):
+  ...
+django_simple_icons.IconDoesNotExist: Icon 'djngo' does not exist. Did you mean: django, deno, fandango? Browse the available icons at https://simpleicons.org/
+```
+
+## Supported versions
+
+- Python 3.12, 3.13 and 3.14
+- Django 5.2, 6.0 and 6.1 are tested. Django is declared as `>=4.2` because the code
+  uses nothing newer, but only the tested versions are supported.
+- Jinja2 2.8 and later
+
+## Versioning
+
+The package version mirrors the bundled Simple Icons release, so version 16.26.0
+contains Simple Icons 16.26.0. A fix to this package that ships no new icons appends a
+fourth segment, such as 16.26.0.1.
+
+## License
+
+The code in this package is MIT licensed. The icons come from Simple Icons and are
+[CC0-1.0](https://github.com/simple-icons/simple-icons/blob/master/LICENSE.md).
+
+Brand icons and names are trademarks of their respective owners. Using an icon does not
+imply endorsement, and some brands restrict how their marks may be used. Read the
+[Simple Icons legal disclaimer](https://github.com/simple-icons/simple-icons/blob/master/DISCLAIMER.md)
+before shipping an icon.

django_simple_icons-16.26.0/pyproject.toml

@@ -0,0 +1,136 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [ "setuptools>=77" ]
+
+[project]
+name = "django-simple-icons"
+version = "16.26.0"
+description = "Use Simple Icons brand icons in your Django and Jinja templates."
+readme = "README.md"
+keywords = [ "django", "icons", "jinja", "simple-icons", "svg" ]
+license = "MIT"
+license-files = [ "LICENSE" ]
+authors = [
+  { name = "M4p4", email = "homejr@protonmail.com" },
+]
+requires-python = ">=3.12"
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Framework :: Django",
+  "Framework :: Django :: 4.2",
+  "Framework :: Django :: 5.2",
+  "Framework :: Django :: 6.0",
+  "Framework :: Django :: 6.1",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+optional-dependencies.django = [ "django>=4.2" ]
+optional-dependencies.jinja = [ "jinja2>=2.8" ]
+urls.Changelog = "https://github.com/M4p4/django-simple-icons/blob/main/CHANGELOG.md"
+urls.Repository = "https://github.com/M4p4/django-simple-icons"
+
+[dependency-groups]
+test = [
+  "coverage[toml]",
+  "jinja2",
+  "pytest",
+  "pytest-randomly",
+]
+django52 = [ "django>=5.2,<5.3" ]
+django60 = [ "django>=6,<6.1" ]
+# Django 6.1 is still in beta; the specifier opts uv into prereleases and will
+# resolve to the final release once it lands.
+django61 = [ "django>=6.1b1,<6.2" ]
+
+[tool.setuptools]
+packages.find.where = [ "src" ]
+package-data.django_simple_icons = [ "py.typed", "simple-icons.zip" ]
+
+[tool.uv]
+# uv only auto-installs the `dev` group, so name the groups a bare `uv run`
+# needs. The full version matrix is exercised by tox, not by the default env.
+default-groups = [ "test", "django60" ]
+conflicts = [
+  [
+    { group = "django52" },
+    { group = "django60" },
+    { group = "django61" },
+  ],
+]
+
+[tool.ruff]
+lint.select = [
+  # flake8-bugbear
+  "B",
+  # flake8-comprehensions
+  "C4",
+  # pycodestyle
+  "E",
+  # Pyflakes errors
+  "F",
+  # isort
+  "I",
+  # flake8-simplify
+  "SIM",
+  # flake8-tidy-imports
+  "TID",
+  # pyupgrade
+  "UP",
+  # Pyflakes warnings
+  "W",
+]
+lint.ignore = [
+  # flake8-bugbear opinionated rules
+  "B9",
+  # line-too-long
+  "E501",
+  # suppressible-exception
+  "SIM105",
+  # if-else-block-instead-of-if-exp
+  "SIM108",
+]
+lint.extend-safe-fixes = [
+  # non-pep585-annotation
+  "UP006",
+]
+lint.isort.required-imports = [ "from __future__ import annotations" ]
+
+[tool.pyproject-fmt]
+max_supported_python = "3.14"
+
+[tool.mypy]
+mypy_path = "src/"
+namespace_packages = false
+warn_unreachable = true
+enable_error_code = [
+  "ignore-without-code",
+  "redundant-expr",
+  "truthy-bool",
+]
+strict = true
+overrides = [ { module = "tests.*", allow_untyped_defs = true, allow_untyped_calls = true } ]
+
+[tool.pytest]
+ini_options.testpaths = [ "tests" ]
+ini_options.addopts = "-ra --strict-config --strict-markers"
+
+[tool.coverage]
+run.branch = true
+run.data_file = ".coverage/cov"
+run.parallel = true
+run.source = [
+  "django_simple_icons",
+  "tests",
+]
+paths.source = [
+  "src",
+  ".tox/**/site-packages",
+]
+report.show_missing = true
+report.skip_covered = true
+report.skip_empty = true

django_simple_icons-16.26.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

django_simple_icons-16.26.0/src/django_simple_icons/__init__.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from contextlib import contextmanager
+from copy import deepcopy
+from difflib import get_close_matches
+from functools import lru_cache
+from importlib.resources import files
+from typing import Any
+from xml.etree import ElementTree
+from zipfile import ZipFile
+
+__all__ = ["IconDoesNotExist", "get_brand_color"]
+
+_ICONS_URL = "https://simpleicons.org/"
+
+
+class IconDoesNotExist(Exception):
+    pass
+
+
+@contextmanager
+def _zip_file() -> Iterator[ZipFile]:
+    resource = files("django_simple_icons").joinpath("simple-icons.zip")
+    with resource.open("rb") as file, ZipFile(file) as archive:
+        yield archive
+
+
+@lru_cache(maxsize=1)
+def _load_metadata() -> dict[str, dict[str, str]]:
+    with _zip_file() as archive:
+        data: dict[str, dict[str, str]] = json.loads(archive.read("data.json"))
+    return data
+
+
+def _unknown_icon(name: str) -> IconDoesNotExist:
+    matches = get_close_matches(name, _load_metadata(), n=3)
+    suggestion = f" Did you mean: {', '.join(matches)}?" if matches else ""
+    return IconDoesNotExist(
+        f"Icon {name!r} does not exist.{suggestion}"
+        f" Browse the available icons at {_ICONS_URL}"
+    )
+
+
+@lru_cache(maxsize=128)
+def _load_icon(name: str) -> ElementTree.Element:
+    with _zip_file() as archive:
+        try:
+            svg_bytes = archive.read(f"icons/{name}.svg")
+        except KeyError:
+            raise _unknown_icon(name) from None
+
+    svg = ElementTree.fromstring(svg_bytes.decode())
+    # Parsing resolves the xmlns declaration into '{ns}tag' names; undo that so
+    # the icon serializes as plain inline SVG.
+    for element in svg.iter():
+        _, _, element.tag = element.tag.rpartition("}")
+    return svg
+
+
+def get_brand_color(name: str) -> str:
+    """Return the official brand color of ``name`` as ``"#RRGGBB"``."""
+    try:
+        hex_ = _load_metadata()[name]["hex"]
+    except KeyError:
+        raise _unknown_icon(name) from None
+    return f"#{hex_}"
+
+
+def _plain_str(value: Any) -> Any:
+    """Demote a ``str`` subclass to ``str``, leaving anything else untouched.
+
+    ``markupsafe.Markup`` overrides ``replace()`` to escape its arguments, so
+    ElementTree's serializer would turn its own ``<`` into ``<``.
+    Non-strings pass through so ElementTree still rejects what it cannot
+    serialize instead of silently emitting ``"None"``.
+    """
+    return str(value) if isinstance(value, str) else value
+
+
+def _render_icon(
+    name: str,
+    *,
+    size: int | None,
+    color: str,
+    title: str | bool,
+    attrs: dict[str, Any],
+) -> str:
+    color = _plain_str(color)
+    title = _plain_str(title)
+
+    svg = deepcopy(_load_icon(name))
+
+    if size is not None:
+        svg.set("width", str(size))
+        svg.set("height", str(size))
+
+    if color == "brand":
+        svg.set("fill", get_brand_color(name))
+    else:
+        svg.set("fill", color)
+
+    title_element = svg.find("title")
+    assert title_element is not None  # every Simple Icon ships a <title>
+    if title is False:
+        # Decorative by default: no accessible name, hidden from screen readers.
+        svg.remove(title_element)
+        svg.attrib.pop("role", None)
+        svg.set("aria-hidden", "true")
+    elif title is not True:
+        title_element.text = title
+
+    for key, value in attrs.items():
+        # removesuffix: `class` and `for` are reserved words, so the Python and
+        # Jinja surfaces have to spell them `class_` / `for_`.
+        svg.set(key.removesuffix("_").replace("_", "-"), str(_plain_str(value)))
+
+    # Tags carry no namespace after _load_icon(), so no xmlns is serialized —
+    # inline SVG inherits it from the surrounding HTML document anyway.
+    return ElementTree.tostring(svg, encoding="unicode")