Django Q2

Warnings

• breaking Python 3.8 support was dropped in `django-q2` v1.8.0. Ensure your Python environment is 3.9 or higher when upgrading.
  Fix: Upgrade your Python version to 3.9 or newer before upgrading `django-q2` to version 1.8.0 or later.
• breaking Django 3.2 and 4.1 support was dropped in `django-q2` v1.7.0. Subsequent versions require Django 4.2 or newer, with v1.9.0 adding support for Django 6.0.
  Fix: Upgrade your Django project to version 4.2 or later before upgrading `django-q2` to version 1.7.0 or later.
• gotcha If using Redis as your broker, `django-q2` v1.9.0 introduced a fix for compatibility with `redis-py > 5`. Ensure you are on `django-q2` v1.9.0 or higher if using recent `redis-py` versions to avoid potential issues.
  Fix: Upgrade `django-q2` to v1.9.0 or newer if you are using `redis-py` version 5 or greater.
• gotcha The `SECRET_KEY` in your Django settings is crucial as Django Q2 uses it to sign task packages. Without a properly set `SECRET_KEY`, tasks might fail to unpack or execute securely.
  Fix: Ensure `SECRET_KEY` is set in your Django settings, especially in production environments.
• gotcha A bug existed in versions prior to 1.7.0 where setting `max_attempts` to 1 would still result in the task being retried once. This could lead to unexpected duplicate executions.
  Fix: Upgrade to `django-q2` v1.7.0 or newer to correctly handle `max_attempts=1`.
• deprecated The original `django-q` project is no longer maintained. Users are strongly advised to migrate to `django-q2` for continued support and updates. Migration typically involves uninstalling `django-q` and installing `django-q2`.
  Fix: Uninstall `django-q` and `pip install django-q2`. Then run `python manage.py migrate`.

Install

• pip install django-q2 Install latest version
• pip install django-q2[redis] Install with Redis broker support

Imports

• async_task

  from django_q.tasks import async_task

  Primary function to enqueue a task for asynchronous execution.
• schedule

  from django_q.tasks import schedule

  Used to create scheduled, cron, or repeated tasks.
• Schedule

  from django_q.models import Schedule

  Django model for managing scheduled tasks programmatically.

Quickstart

To get started, add 'django_q' to your `INSTALLED_APPS` and configure `Q_CLUSTER` in your `settings.py`. Ensure you run `python manage.py migrate` to create necessary database tables. Define your task functions and enqueue them using `async_task`. Finally, start the Q2 cluster with `python manage.py qcluster` to process tasks in the background. The example above demonstrates a basic setup and how to enqueue a task, assuming a Django project structure.

import os
import django
from django.conf import settings

# Minimal Django setup if running outside a full Django environment
if not settings.configured:
    settings.configure(
        INSTALLED_APPS=[
            'django_q',
            # Add other apps if needed
        ],
        DATABASES={
            'default': {
                'ENGINE': 'django.db.backends.sqlite3',
                'NAME': ':memory:',
            }
        },
        Q_CLUSTER={
            'name': 'myproject',
            'workers': 4,
            'timeout': 90,
            'compress': True,
            'save_limit': 250,
            'queue_limit': 500,
            'cpu_affinity': 1,
            'label': 'Django Q2',
            'redis': os.environ.get('REDIS_URL', 'redis://localhost:6379/0'),
        },
        SECRET_KEY=os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-for-development'),
        TIME_ZONE='UTC',
        USE_TZ=True,
    )
django.setup()

# Your task function (e.g., in a tasks.py file)
def my_long_running_task(iterations):
    result = 0
    for i in range(iterations):
        result += i
    return result

# Enqueue the task
from django_q.tasks import async_task
task_id = async_task('my_app.tasks.my_long_running_task', 1000000)
print(f"Task enqueued with ID: {task_id}")

# To run the cluster in a separate terminal:
# python manage.py qcluster