README.md

django-q-registry

A Django app to register periodic Django Q tasks.

Requirements

• Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13
• Django 4.2, 5.0
• Django Q2 1.4.3+
  • This package has only been tested with the Django ORM broker.

Installation

1. Install the package from PyPI:

   python -m pip install django-q-registry

2. Add the app to your Django project's INSTALLED_APPS:

   INSTALLED_APPS = [
       ...,
       "django_q_registry",
       ...,
   ]

Getting Started

Registering Periodic Tasks

There are three supported ways to register periodic tasks:

1. In a tasks.py file in a Django app, using the @register_task decorator:

   # tasks.py
   from django.core.mail import send_mail
   from django_q.models import Schedule
   from django_q_registry import register_task
   
   
   @register_task(
       name="Send periodic test email",
       schedule_type=Schedule.CRON,
       # https://crontab.guru/#*/5_*_*_*_*
       cron="*/5 * * * *",
   )
   def send_test_email():
       send_mail(
           subject="Test email",
           message="This is a test email.",
           from_email="[email protected]",
           recipient_list=["[email protected]"],
       )

2. In a tasks.py file in a Django app, using the registry.register function directly:

   # tasks.py
   from django.core.mail import send_mail
   from django_q.models import Schedule
   from django_q_registry.registry import registry
   
   
   registry.register(
       send_mail,
       name="Send periodic test email",
       kwargs={
           "subject": "Test email",
           "message": "This is a test email.",
           "from_email": "[email protected]",
           "recipient_list": ["[email protected]"],
       },
       schedule_type=Schedule.CRON,
       # https://crontab.guru/#*/5_*_*_*_*
       cron="*/5 * * * *",
   )

3. In a Django project's settings.py file, using the Q_REGISTRY["TASKS"] setting:

   # settings.py
   from django_q.models import Schedule
   
   
   Q_REGISTRY = {
       "TASKS": [
           {
               "name": "Send periodic test email",
               "func": "django.core.mail.send_mail",
               "kwargs": {
                   "subject": "Test email",
                   "message": "This is a test email.",
                   "from_email": "[email protected]",
                   "recipient_list": ["[email protected]"],
               },
               "schedule_type": Schedule.CRON,
               # https://crontab.guru/#*/5_*_*_*_*
               "cron": "*/5 * * * *",
           },
       ],
   }

Setting up Periodic Tasks in Production

At some point in your project's deployment process, run the setup_periodic_tasks management command:

python manage.py migrate
python manage.py setup_periodic_tasks

This command automatically registers periodic tasks from tasks.py files in Django apps, and from the Q_REGISTRY["TASKS"] setting. It also cleans up any periodic tasks that are no longer registered.

Documentation

Please refer to the documentation for more information.

License

django-q-registry is licensed under the MIT license. See the LICENSE file for more information.