django-image-toolkit 0.1.0__tar.gz

django_image_toolkit-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.python-version

django_image_toolkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Skoroboatei Gomes
+
+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_image_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.5
+Name: django-image-toolkit
+Version: 0.1.0
+Summary: An image toolkit for media driven apps in django. Custom image fields with format conversion, cropping and validation. Hashed based filename storage. Cleanup and widgets
+Project-URL: Homepage, https://github.com/edu292/django-image-tookit
+Project-URL: Issues, https://github.com/edu292/django-image-toolkit/issues
+Author-email: Eduardo Skoroboatei Gomes <eduskoroboatei@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Django
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.14
+Requires-Dist: django>=6.0.4
+Requires-Dist: pillow>=12.2.0

django_image_toolkit-0.1.0/image_toolkit/admin.py

@@ -0,0 +1,32 @@
+from django.contrib import admin
+
+
+class ImageGridAdminMixin(admin.ModelAdmin):
+    change_list_template = 'image_toolkit/admin/image_grid.html'
+    image_field = 'file'
+    name_field = 'name'
+    edit_page = True
+
+    def get_list_editable(self, request):
+        editable = list(super().get_list_editable(request))
+        if self.name_field and self.name_field not in editable:
+            editable.append(self.name_field)
+        return tuple(editable)
+
+    def changelist_view(self, request, extra_context=None):
+        response = super().changelist_view(request, extra_context=extra_context)
+
+        if hasattr(response, 'context_data') and 'cl' in response.context_data:
+            cl = response.context_data['cl']
+            for obj in cl.result_list:
+                file_attr = getattr(obj, self.image_field, None)
+                obj._image = file_attr
+                obj._name = getattr(obj, self.name_field, '')
+                obj._name_field = self.name_field
+                obj._abs_url = request.build_absolute_uri(file_attr.url) if file_attr else ''
+
+        return response
+
+    class Media:
+        css = {'all': ('image_toolkit/css/admin_image_grid.css',)}
+        js = ('image_toolkit/js/admin_image_grid.js',)

django_image_toolkit-0.1.0/image_toolkit/apps.py

@@ -0,0 +1,22 @@
+from django.apps import AppConfig
+from django.db.models import FileField
+
+
+class ImageToolkitConfig(AppConfig):
+    name = 'image_toolkit'
+
+    def ready(self) -> None:
+        from django.apps import apps
+
+        for model in apps.get_models():
+            has_file_field = any(isinstance(field, FileField) for field in model._meta.fields)
+            if has_file_field:
+                self.connect_signal(model)
+
+    def connect_signal(self, model):
+        from django.db.models.signals import post_delete, pre_save
+
+        from .handlers import delete_old_file, delete_on_model_delete
+
+        post_delete.connect(delete_on_model_delete, sender=model, dispatch_uid=f'{model._meta.label}_cleanup_delete')
+        pre_save.connect(delete_old_file, sender=model, dispatch_uid=f'{model._meta.label}_cleanup_change')

django_image_toolkit-0.1.0/image_toolkit/fields.py

@@ -0,0 +1,212 @@
+import io
+import math
+from pathlib import Path
+from typing import Any
+
+from django import forms
+from django.core.exceptions import ValidationError
+from django.core.files.base import ContentFile
+from django.core.files.uploadedfile import SimpleUploadedFile
+from django.db.models import ImageField
+from django.utils.translation import gettext_lazy as _
+from PIL import Image
+
+from .widgets import ResizableImageWidget
+
+
+def is_float(str: Any):
+    try:
+        float(str)
+    except TypeError:
+        return False
+
+    return True
+
+
+class WebPImageField(ImageField):
+    def __init__(self, quality: int = 80, *args: Any, **kwargs: Any) -> None:
+        if not is_float(quality):
+            raise TypeError(f'Expect quality to be a valid float. Given {quality}')
+        super().__init__(*args, **kwargs)
+        self.quality = quality
+
+    def deconstruct(self) -> Any:
+        name, path, args, kwargs = super().deconstruct()
+        kwargs['quality'] = self.quality
+
+        return name, path, args, kwargs
+
+    def process_image(self, img):
+        return img
+
+    def get_prep_value(self, value):
+        prepped_value = super().get_prep_value(value)
+
+        if prepped_value == '':
+            return None
+
+        return prepped_value
+
+    def pre_save(self, model_instance, add):
+        file = getattr(model_instance, self.attname)
+
+        if file and not file._committed:
+            img = Image.open(file)
+
+            if img.format != 'WEBP':
+                if img.mode in ('RGBA', 'P'):
+                    img = img.convert('RGBA')
+                elif img.mode != 'RGB':
+                    img = img.convert('RGB')
+
+                img = self.process_image(img)
+
+                output = io.BytesIO()
+                img.save(output, format='WEBP', quality=self.quality)
+                output.seek(0)
+
+                file.file = ContentFile(output.read())
+                file.name = Path(file.name).with_suffix('.webp')
+
+        return super().pre_save(model_instance, add)
+
+
+class ImageDimensionMixin:
+    def __init__(
+        self,
+        width: int | None = None,
+        height: int | None = None,
+        aspect_ratio: str | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        if aspect_ratio and (width or height):
+            raise TypeError('Provide EITHER width and height OR aspect_ratio, not both.')
+
+        invalid_aspect_ratio_error = TypeError(
+            f'Aspect ratio must be "width/height" (e.g., "1/1" or "16/9"). Current: {aspect_ratio}'
+        )
+        if aspect_ratio:
+            parts = aspect_ratio.split('/', 1)
+            if len(parts) != 2 or any(not is_float(p) for p in parts):
+                raise invalid_aspect_ratio_error
+
+        self.width = width
+        self.height = height
+        self.aspect_ratio = aspect_ratio
+
+        super().__init__(*args, **kwargs)
+
+    def deconstruct(self) -> Any:
+        name, path, args, kwargs = super().deconstruct()
+
+        if self.width:
+            kwargs['width'] = self.width
+        if self.height:
+            kwargs['height'] = self.height
+        if self.aspect_ratio:
+            kwargs['aspect_ratio'] = self.aspect_ratio
+
+        return name, path, args, kwargs
+
+
+class WebPValidatedImageField(ImageDimensionMixin, WebPImageField):
+    def formfield(self, **kwargs):
+        defaults = {'validators': [self.validate_dimensions]}
+        defaults.update(kwargs)
+        return super().formfield(**defaults)
+
+    def validate_dimensions(self, image):
+        if not image:
+            return
+
+        img = Image.open(image)
+        image_width, image_height = img.size
+
+        if self.width and image_width != self.width:
+            raise ValidationError(_(f'Width must be {self.width}px (given: {image_width}px).'))
+        if self.height and image_height != self.height:
+            raise ValidationError(_(f'Height must be {self.height}px (given: {image_height}px).'))
+
+        if self.aspect_ratio:
+            target_width_aspect, target_height_aspect = (float(ratio) for ratio in self.aspect_ratio.split('/'))
+            target_ratio = target_width_aspect / target_height_aspect
+            image_ratio = image_width / image_height
+            if not math.isclose(target_ratio, image_ratio):
+                divisor = math.gcd(image_width, image_height)
+                image_width_aspect = image_width / divisor
+                image_height_aspect = image_height / divisor
+                raise ValidationError(
+                    _(
+                        f'The image must be in the {target_width_aspect}/{target_height_aspect} aspect ratio (given: {image_width_aspect}/{image_height_aspect})'
+                    )
+                )
+
+
+class WebPAutoCropField(ImageDimensionMixin, WebPImageField):
+    def process_image(self, img: Image.Image) -> Image.Image:
+        if self.aspect_ratio:
+            target_w_aspect, target_h_aspect = (float(aspect) for aspect in self.aspect_ratio.split('/'))
+            target_ratio = target_w_aspect / target_h_aspect
+        elif self.width and self.height:
+            target_ratio = self.width / self.height
+
+        original_w, original_h = img.size
+        current_ratio = original_w / original_h
+
+        if not math.isclose(current_ratio, target_ratio):
+            if current_ratio > target_ratio:
+                new_w = int(original_h * target_ratio)
+                offset = (original_w - new_w) // 2
+                img = img.crop((offset, 0, offset + new_w, original_h))
+            else:
+                new_h = int(original_w / target_ratio)
+                offset = (original_h - new_h) // 2
+                img = img.crop((0, offset, original_w, offset + new_h))
+
+        if self.width and self.height and img.width > self.width:
+            img = img.resize((self.width, self.height), Image.Resampling.LANCZOS)
+
+        return img
+
+
+class DynamicImageFormField(forms.MultiValueField):
+    widget = ResizableImageWidget
+
+    def __init__(self, **kwargs):
+        fields = (
+            forms.ImageField(required=kwargs.get('required', True)),
+            forms.IntegerField(required=False, min_value=1),
+            forms.IntegerField(required=False, min_value=1),
+            forms.IntegerField(required=False, min_value=1, max_value=100),
+        )
+        super().__init__(fields, require_all_fields=False, **kwargs)
+
+    def compress(self, data_list):
+        if not data_list or not data_list[0]:
+            return None
+
+        img_file, max_width, max_height, quality = data_list
+        quality = quality or 80
+
+        if not hasattr(img_file, 'read'):
+            return img_file
+
+        img = Image.open(img_file)
+
+        if img.mode in ('RGBA', 'P'):
+            img = img.convert('RGBA')
+        elif img.mode != 'RGB':
+            img = img.convert('RGB')
+
+        if max_width or max_height:
+            target_w = max_width or img.width
+            target_h = max_height or img.height
+            img.thumbnail((target_w, target_h), Image.Resampling.LANCZOS)
+
+        output = io.BytesIO()
+        img.save(output, format='WEBP', quality=quality)
+        output.seek(0)
+
+        new_name = Path(img_file.name).with_suffix('.webp').name
+        return SimpleUploadedFile(new_name, output.read(), content_type='image/webp')

django_image_toolkit-0.1.0/image_toolkit/handlers.py

@@ -0,0 +1,27 @@
+from django.db import transaction
+from django.db.models import FileField
+
+
+def delete_on_model_delete(sender, instance, **kwargs):
+    for field in instance._meta.fields:
+        if isinstance(field, FileField):
+            file = getattr(instance, field.name)
+            if file and file.storage.exists(file.name):
+                transaction.on_commit(lambda f=file: f.delete(save=False))
+
+def delete_old_file(sender, instance, **kwargs):
+    if not instance.pk:
+        return
+
+    try:
+        old_instance = sender.objects.get(pk=instance.pk)
+    except sender.DoesNotExist:
+        return
+
+    for field in instance._meta.fields:
+        if isinstance(field, FileField):
+            old_file = getattr(old_instance, field.name)
+            new_file = getattr(instance, field.name)
+
+            if old_file and old_file != new_file and old_file.storage.exists(old_file.name):
+                transaction.on_commit(lambda f=old_file: f.delete(save=False))

django_image_toolkit-0.1.0/image_toolkit/static/admin_image_grid.css

@@ -0,0 +1,177 @@
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+  gap: 16px;
+  padding: 16px 0;
+}
+
+.image-card {
+  display: flex;
+  flex-direction: column;
+  border: 1px solid var(--hairline-color, #e0e0e0);
+  border-radius: 4px;
+  background-color: var(--body-bg, #ffffff);
+  overflow: hidden;
+}
+
+.image-card__figure {
+  position: relative;
+  margin: 0;
+  aspect-ratio: 1;
+  background-color: var(--darkened-bg, #f8f8f8);
+}
+
+.image-card__link {
+  display: block;
+  width: 100%;
+  height: 100%;
+  text-decoration: none;
+}
+
+.image-card__img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+}
+
+.image-card__control {
+  position: absolute;
+  top: 8px;
+  z-index: 1;
+}
+
+.image-card__control--top-left {
+  left: 8px;
+}
+
+.image-card__control--top-right {
+  right: 8px;
+}
+
+.image-card__checkbox {
+  width: 16px;
+  height: 16px;
+  margin: 0;
+  cursor: pointer;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.3);
+}
+
+.image-card__badge {
+  position: absolute;
+  bottom: 8px;
+  padding: 2px 6px;
+  background-color: rgba(0, 0, 0, 0.65);
+  color: #ffffff;
+  font-size: 11px;
+  border-radius: 2px;
+  pointer-events: none;
+}
+
+.image-card__badge--bottom-left {
+  left: 8px;
+}
+
+.image-card__badge--bottom-right {
+  right: 8px;
+}
+
+.image-card__footer {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 8px 12px;
+  border-top: 1px solid var(--hairline-color, #e0e0e0);
+}
+
+.image-card__name-group {
+  flex: 1;
+  min-width: 0;
+  margin-right: 8px;
+}
+
+.image-card__name-display {
+  display: flex;
+  align-items: flex-start;
+}
+
+.image-card__title {
+  font-size: 13px;
+  color: var(--body-fg, #333333);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.image-card__name-edit {
+  display: none;
+}
+
+.image-card__name-group--editing .image-card__name-display {
+  display: none;
+}
+
+.image-card__name-group--editing .image-card__name-edit {
+  display: block;
+}
+
+.image-card__input {
+  width: 100%;
+  box-sizing: border-box;
+  padding: 4px;
+  border: 1px solid var(--border-color, #ccc);
+  border-radius: 3px;
+  font-size: 13px;
+  background-color: var(--body-bg, #ffffff);
+  color: var(--body-fg, #333333);
+}
+
+.image-card__input:focus {
+  border-color: var(--primary, #79aec8);
+  outline: none;
+}
+
+.image-card__action {
+  background: transparent;
+  border: none;
+  padding: 4px;
+  cursor: pointer;
+  color: var(--body-quiet-color, #666666);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 3px;
+  text-decoration: none;
+}
+
+.image-card__action:hover,
+.image-card__action:focus {
+  color: var(--primary, #79aec8);
+  background-color: var(--darkened-bg, #f8f8f8);
+}
+
+.image-card__action--edit {
+  margin-left: 4px;
+  margin-top: -2px;
+  padding: 2px;
+}
+
+.image-card__action--overlay {
+  background-color: rgba(255, 255, 255, 0.9);
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.2);
+}
+
+.image-card__action--overlay:hover,
+.image-card__action--overlay:focus {
+  background-color: var(--body-bg, #ffffff);
+}
+
+.image-card__action--danger {
+  color: var(--delete-button-bg, #ba2121);
+}
+
+.image-card__action--danger:hover,
+.image-card__action--danger:focus {
+  color: var(--error-fg, #ffffff);
+  background-color: var(--delete-button-bg, #ba2121);
+}

django_image_toolkit-0.1.0/image_toolkit/static/admin_image_grid.js

@@ -0,0 +1,39 @@
+document.addEventListener("click", (e) => {
+  const editBtn = e.target.closest(".image-card__action--edit");
+  if (editBtn) {
+    const group = editBtn.closest(".image-card__name-group");
+    group.classList.add("image-card__name-group--editing");
+    const input = group.querySelector(".image-card__input");
+    input.focus();
+    const val = input.value;
+    input.value = "";
+    input.value = val;
+    return;
+  }
+
+  const copyBtn = e.target.closest(".image-card__action--copy");
+  if (copyBtn && copyBtn.dataset.url) {
+    navigator.clipboard.writeText(copyBtn.dataset.url);
+  }
+});
+
+function saveEdit(e) {
+  const form = e.target.closest("form");
+  const saveButton = form.querySelector('input[name="_save"]');
+
+  form.requestSubmit(saveButton);
+}
+
+document.addEventListener("focusout", (e) => {
+  if (!e.target.matches(".image-card__input")) return;
+  const group = e.target.closest(".image-card__name-group");
+  group.classList.remove("image-card__name-group--editing");
+  saveEdit(e);
+});
+
+document.addEventListener("keydown", (e) => {
+  if (e.key === "Enter" && e.target.matches(".image-card__input")) {
+    e.preventDefault();
+    saveEdit(e);
+  }
+});

django_image_toolkit-0.1.0/image_toolkit/storages.py

@@ -0,0 +1,17 @@
+import hashlib
+from pathlib import Path
+
+from django.core.files import File
+from django.core.files.storage import FileSystemStorage
+
+
+class HashedFileSystemStorage(FileSystemStorage):
+    def _save(self, name, content: File):
+        original_filepath = Path(name)
+        hasher = hashlib.blake2b(digest_size=16)
+        for chunck in content.chunks():
+            hasher.update(chunck)
+
+        hash = hasher.hexdigest()
+        hashed_filepath = original_filepath.parent / Path(hash + original_filepath.suffix)
+        return super()._save(hashed_filepath, content)

django_image_toolkit-0.1.0/image_toolkit/templates/image_toolkit/admin/image_grid.html

@@ -0,0 +1,98 @@
+{% extends "admin/change_list.html" %}
+{% load i18n static %}
+{% block result_list %}
+    {% if cl.result_list %}
+        <div class="card-grid">
+            {% for result in cl.result_list %}
+                <div class="image-card">
+                    <figure class="image-card__figure">
+                        {% if result._image %}
+                            <input type="checkbox"
+                                   name="_selected_action"
+                                   value="{{ result.pk }}"
+                                   class="action-select image-card__control image-card__control--top-left image-card__checkbox"
+                                   aria-label="{% translate 'Select item' %}" />
+                            <a href="{% url 'admin:'|add:cl.opts.app_label|add:'_'|add:cl.opts.model_name|add:'_delete' result.pk %}"
+                               class="image-card__action image-card__action--overlay image-card__action--danger image-card__control image-card__control--top-right"
+                               title="{% translate 'Delete' %}">
+                                <svg width="16"
+                                     height="16"
+                                     viewBox="0 0 24 24"
+                                     fill="none"
+                                     stroke="currentColor"
+                                     stroke-width="2"
+                                     stroke-linecap="round"
+                                     stroke-linejoin="round">
+                                    <polyline points="3 6 5 6 21 6"></polyline>
+                                    <path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6m3 0V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"></path>
+                                </svg>
+                            </a>
+                            {% if cl.model_admin.edit_page %}
+                                <a href="{% url 'admin:'|add:cl.opts.app_label|add:'_'|add:cl.opts.model_name|add:'_change' result.pk %}"
+                                   class="image-card__link">
+                                    <img class="image-card__img"
+                                         src="{{ result._image.url }}"
+                                         alt="{{ result._name }}" />
+                                </a>
+                            {% else %}
+                                <img class="image-card__img"
+                                     src="{{ result._image.url }}"
+                                     alt="{{ result._name }}" />
+                            {% endif %}
+                            <span class="image-card__badge image-card__badge--bottom-left">{{ result._image.size|filesizeformat }}</span>
+                            <span class="image-card__badge image-card__badge--bottom-right">{{ result._image.width }}x{{ result._image.height }}</span>
+                        {% endif %}
+                    </figure>
+                    <footer class="image-card__footer">
+                        <div class="image-card__name-group">
+                            <div class="image-card__name-display">
+                                <span class="image-card__title" title="{{ result._name }}">{{ result._name }}</span>
+                                <button type="button"
+                                        class="image-card__action image-card__action--edit"
+                                        title="{% translate 'Edit name' %}">
+                                    <svg width="12"
+                                         height="12"
+                                         viewBox="0 0 24 24"
+                                         fill="none"
+                                         stroke="currentColor"
+                                         stroke-width="2"
+                                         stroke-linecap="round"
+                                         stroke-linejoin="round">
+                                        <path d="M17 3a2.828 2.828 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5L17 3z"></path>
+                                    </svg>
+                                </button>
+                            </div>
+                            <div class="image-card__name-edit">
+                                <input type="hidden"
+                                       name="form-{{ forloop.counter0 }}-id"
+                                       value="{{ result.pk }}" />
+                                <input type="text"
+                                       name="form-{{ forloop.counter0 }}-{{ result._name_field }}"
+                                       value="{{ result._name }}"
+                                       class="image-card__input"
+                                       required
+                                       aria-label="{% translate 'Edit name' %}" />
+                            </div>
+                        </div>
+                        <button type="button"
+                                class="image-card__action image-card__action--copy"
+                                aria-label="{% translate 'Copy URL' %}"
+                                data-url="{{ result._abs_url }}">
+                            <svg width="16"
+                                 height="16"
+                                 viewBox="0 0 24 24"
+                                 fill="none"
+                                 stroke="currentColor"
+                                 stroke-width="2"
+                                 stroke-linecap="round"
+                                 stroke-linejoin="round">
+                                <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+                                <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+                            </svg>
+                        </button>
+                    </footer>
+                </div>
+            {% endfor %}
+        </div>
+    {% endif %}
+{% endblock %}