Resolve #240 -- Add support for Django's tasks framework (>6.0)

Django's task framework provides native unified framework to
interact with any 3rd party task runner, like Celery, Dramatiq or
RQ. This step will allow us to greatly redurece the complexity of
this package once Django 5.2 LTS reaches EoL.

Starting with Django 6.0 we are default to the new task framework
while providing fallblack options with pending deprecation warnings.

Author: codingjoe

.github/workflows/ci.yml

@@ -72,11 +72,12 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.10"
+          - "3.12"
         django-version:
           # LTS gets tested on all OS
           - "4.2"
           - "5.1"
+          - "6.0"
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
@@ -95,6 +96,8 @@ jobs:
     name: PyTest
     strategy:
       matrix:
+        django-version:
+          - "5.2" # LTS
         extras:
           - "celery"
           - "dramatiq"
@@ -112,6 +115,7 @@ jobs:
         if: matrix.extras == 'dramatiq' || matrix.extras == 'django-rq'
         run: sudo apt install -y redis-server
       - run: python -m pip install .[test,${{ matrix.extras }}]
+      - run: python -m pip install django~=${{ matrix.django-version }}.0
       - run: python -m pytest
       - uses: codecov/codecov-action@v5
         with:

README.md

@@ -9,7 +9,7 @@ Responsive cross-browser image library using modern codes like AVIF & WebP.
 - serve files with or without a CDN
 - placeholders for local development
 - migration support
-- async image processing for [Celery], [Dramatiq] or [Django RQ][django-rq]
+- async image processing for via [Django Tasks][django-tasks]
 - [DRF] support
 
 [![PyPi Version](https://img.shields.io/pypi/v/django-pictures.svg)](https://pypi.python.org/pypi/django-pictures/)
@@ -100,13 +100,32 @@ PICTURES = {
     "PIXEL_DENSITIES": [1, 2],
     "USE_PLACEHOLDERS": True,
     "QUEUE_NAME": "pictures",
+    "BACKEND": "default",
     "PROCESSOR": "pictures.tasks.process_picture",
 }
 ```
 
 If you have either Dramatiq or Celery installed, we will default to async
 image processing. You will need workers to listen to the `pictures` queue.
 
+> [!IMPORTANT]
+> Starting with Django version 6.0, this package leverage Django's built-in
+> task framework for async image processing by default. You will need to add
+> add the `pictures` queue to your `TASKS` setting:
+
+```python
+# settings.py
+TASKS = {
+    "default": {
+        # ...
+        "QUEUES": [
+            # ...
+            "pictures",  # add the new pictures queue here
+        ]
+    },
+}
+```
+
 ### Placeholders
 
 This library comes with dynamically created placeholders to simplify local
@@ -218,6 +237,38 @@ densities.
 
 ### Async image processing
 
+> [!IMPORTANT]
+> Starting with Django version 6.0, this package leverage Django's built-in
+> task framework for async image processing by default. You can explicitly
+> override this behavior via the `PICTURES["PROCESSOR"]` setting.
+
+Images are processed on a separate queue by default, you will add the `pictures`
+queue to your task backend configuration. You can override the queue name,
+via the `PICTURES["QUEUE_NAME"]` setting.
+
+If you want to run image processing on a separate backend, you can set the
+`PICTURES["BACKEND"]` setting to something other than `default`.
+
+You may also override the processor to explicitly use Celery, Dramatiq or
+Django RQ until they provide proper integration with Django Tasks.
+
+> [!WARNING]
+> The custom Celery, Dramatiq and Django RQ integration is deprecated
+> and will be removed in the next major release (version 2.0).
+
+```python
+# settings.py
+PICTURES = {
+    "PROCESSOR": "pictures.tasks.celery",  # use Celery
+    # or
+    "PROCESSOR": "pictures.tasks.dramatiq",  # use Dramatiq
+    # or
+    "PROCESSOR": "pictures.tasks.django_rq",  # use Django RQ
+}
+```
+
+#### Pre Django 6.0
+
 If you have either Dramatiq or Celery installed, we will default to async
 image processing. You will need workers to listen to the `pictures` queue.
 You can override the queue name, via the `PICTURES["QUEUE_NAME"]` setting.
@@ -377,8 +428,6 @@ class MyPicture(Picture):
 [caniemail-srcset]: https://www.caniemail.com/features/html-srcset/
 [caniemail-webp]: https://www.caniemail.com/features/image-webp/
 [caniuse-picture]: https://caniuse.com/picture
-[celery]: https://docs.celeryproject.org/en/stable/
-[django-rq]: https://github.com/rq/django-rq
-[dramatiq]: https://dramatiq.io/
+[django-tasks]: https://docs.djangoproject.com/en/stable/topics/tasks/
 [drf]: https://www.django-rest-framework.org/
 [migration]: tests/testapp/migrations/0002_alter_profile_picture.py

pictures/conf.py

@@ -21,6 +21,7 @@ def get_settings():
             "PIXEL_DENSITIES": [1, 2],
             "USE_PLACEHOLDERS": settings.DEBUG,
             "QUEUE_NAME": "pictures",
+            "BACKEND": "default",
             "PICTURE_CLASS": "pictures.models.PillowPicture",
             "PROCESSOR": "pictures.tasks.process_picture",
             **getattr(settings, "PICTURES", {}),

pictures/tasks.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
+import warnings
 from typing import Protocol
 
+import django
 from django.db import transaction
 from PIL import Image
 
@@ -46,12 +48,12 @@ def _process_picture(
 
 
 try:
-    import dramatiq
+    from dramatiq import actor
 except ImportError:
     pass
 else:
 
-    @dramatiq.actor(queue_name=conf.get_settings().QUEUE_NAME)
+    @actor(queue_name=conf.get_settings().QUEUE_NAME)
     def process_picture_with_dramatiq(
         storage: tuple[str, list, dict],
         file_name: str,
@@ -60,12 +62,19 @@ def process_picture_with_dramatiq(
     ) -> None:
         _process_picture(storage, file_name, new, old)
 
-    def process_picture(  # noqa: F811
+    def dramatiq_process_picture(  # noqa: F811
         storage: tuple[str, list, dict],
         file_name: str,
         new: list[tuple[str, list, dict]] | None = None,
         old: list[tuple[str, list, dict]] | None = None,
     ) -> None:
+        if django.VERSION >= (6, 0):
+            warnings.warn(
+                "The `dramatiq_process_picture`-processor deprecated in favor of Django's tasks framework."
+                " Deletion is scheduled with Django 5.2 version support.",
+                PendingDeprecationWarning,
+                stacklevel=2,
+            )
         transaction.on_commit(
             lambda: process_picture_with_dramatiq.send(
                 storage=storage,
@@ -75,6 +84,8 @@ def process_picture(  # noqa: F811
             )
         )
 
+    process_picture = dramatiq_process_picture  # type: ignore[assignment]
+
 
 try:
     from celery import shared_task
@@ -94,12 +105,19 @@ def process_picture_with_celery(
     ) -> None:
         _process_picture(storage, file_name, new, old)
 
-    def process_picture(  # noqa: F811
+    def celery_process_picture(  # noqa: F811
         storage: tuple[str, list, dict],
         file_name: str,
         new: list[tuple[str, list, dict]] | None = None,
         old: list[tuple[str, list, dict]] | None = None,
     ) -> None:
+        if django.VERSION >= (6, 0):
+            warnings.warn(
+                "The `celery_process_picture`-processor deprecated in favor of Django's tasks framework."
+                " Deletion is scheduled with Django 5.2 version support.",
+                PendingDeprecationWarning,
+                stacklevel=2,
+            )
         transaction.on_commit(
             lambda: process_picture_with_celery.apply_async(
                 kwargs=dict(
@@ -112,6 +130,8 @@ def process_picture(  # noqa: F811
             )
         )
 
+    process_picture = celery_process_picture  # type: ignore[assignment]
+
 
 try:
     from django_rq import job
@@ -128,12 +148,19 @@ def process_picture_with_django_rq(
     ) -> None:
         _process_picture(storage, file_name, new, old)
 
-    def process_picture(  # noqa: F811
+    def rq_process_picture(  # noqa: F811
         storage: tuple[str, list, dict],
         file_name: str,
         new: list[tuple[str, list, dict]] | None = None,
         old: list[tuple[str, list, dict]] | None = None,
     ) -> None:
+        if django.VERSION >= (6, 0):
+            warnings.warn(
+                "The `rq_process_picture`-processor deprecated in favor of Django's tasks framework."
+                " Deletion is scheduled with Django 5.2 version support.",
+                PendingDeprecationWarning,
+                stacklevel=2,
+            )
         transaction.on_commit(
             lambda: process_picture_with_django_rq.delay(
                 storage=storage,
@@ -142,3 +169,46 @@ def process_picture(  # noqa: F811
                 old=old,
             )
         )
+
+    process_picture = rq_process_picture  # type: ignore[assignment]
+
+
+try:
+    from django.tasks import exceptions, task
+except ImportError:
+    pass
+else:
+    try:
+
+        @task(
+            backend=conf.get_settings().BACKEND,
+            queue_name=conf.get_settings().QUEUE_NAME,
+        )
+        def process_picture_with_django_tasks(
+            storage: tuple[str, list, dict],
+            file_name: str,
+            new: list[tuple[str, list, dict]] | None = None,
+            old: list[tuple[str, list, dict]] | None = None,
+        ) -> None:
+            _process_picture(storage, file_name, new, old)
+
+        def process_picture(  # noqa: F811
+            storage: tuple[str, list, dict],
+            file_name: str,
+            new: list[tuple[str, list, dict]] | None = None,
+            old: list[tuple[str, list, dict]] | None = None,
+        ) -> None:
+            transaction.on_commit(
+                lambda: process_picture_with_django_tasks.enqueue(
+                    storage=storage,
+                    file_name=file_name,
+                    new=new,
+                    old=old,
+                )
+            )
+
+    except exceptions.InvalidTask as e:
+        raise exceptions.ImproperlyConfigured(
+            "Pictures are processed on a separate queue by default,"
+            " please `TASKS` settings in accordance with Django-Pictures documentation."
+        ) from e

pyproject.toml

@@ -30,8 +30,8 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Framework :: Django",
   "Framework :: Django :: 4.2",
-  "Framework :: Django :: 5.1",
   "Framework :: Django :: 5.2",
+  "Framework :: Django :: 6.0",
 ]
 requires-python = ">=3.10"
 dependencies = ["django>=4.2.0", "pillow>=11.3.0"]

tests/test_tasks.py

@@ -1,6 +1,8 @@
+import importlib
 from unittest.mock import Mock
 
 import pytest
+from django.core.exceptions import ImproperlyConfigured
 
 from pictures import tasks
 from tests.testapp.models import SimpleModel
@@ -24,3 +26,21 @@ def test_process_picture__file_cannot_be_reopened(image_upload_file):
 
 def test_noop():
     tasks.noop()  # does nothing
+
+
+def test_django_tasks_misconfiguration(settings):
+    pytest.importorskip(
+        "django", minversion="6.0", reason="Django tasks introduced in 6.0"
+    )
+    settings.TASKS = {
+        "default": {
+            "BACKEND": "django.tasks.backends.immediate.ImmediateBackend",
+            "QUEUES": ["default"],
+        }
+    }
+    with pytest.raises(ImproperlyConfigured) as e:
+        importlib.reload(tasks)
+    assert str(e.value) == (
+        "Pictures are processed on a separate queue by default,"
+        " please `TASKS` settings in accordance with Django-Pictures documentation."
+    )

tests/testapp/settings.py

@@ -140,6 +140,16 @@
 }
 
 
+# Django tasks (6.0+)
+
+TASKS = {
+    "default": {
+        "BACKEND": "django.tasks.backends.immediate.ImmediateBackend",
+        "QUEUES": ["default", "pictures"],
+    }
+}
+
+
 # Dramatiq
 try:
     import dramatiq  # NoQA