django-qstash 0.0.5__tar.gz → 0.0.7__tar.gz

{django_qstash-0.0.5 → django_qstash-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-qstash
-Version: 0.0.5
+Version: 0.0.7
 Summary: A drop-in replacement for Celery's shared_task with Upstash QStash.
 Author-email: Justin Mitchel <justin@codingforentrepreneurs.com>
 Project-URL: Changelog, https://github.com/jmitchel3/django-qstash

{django_qstash-0.0.5 → django_qstash-0.0.7}/pyproject.toml

@@ -6,7 +6,7 @@ requires = [
 
 [project]
 name = "django-qstash"
-version = "0.0.5"
+version = "0.0.7"
 description = "A drop-in replacement for Celery's shared_task with Upstash QStash."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -74,6 +74,8 @@ source = [
 ]
 omit = [
   "*/migrations/*",
+  "*/admin.py",
+  "tests/*",
 ]
 
 [tool.coverage.paths]

{django_qstash-0.0.5 → django_qstash-0.0.7}/src/django_qstash/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = "0.0.5"
+__version__ = "0.0.7"
 
 from .tasks import shared_task
 

django_qstash-0.0.7/src/django_qstash/callbacks.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from django_qstash.settings import DJANGO_QSTASH_DOMAIN
+from django_qstash.settings import DJANGO_QSTASH_WEBHOOK_PATH
+
+
+def get_callback_url() -> str:
+    """
+    Get the callback URL based on the settings.
+    """
+    callback_domain = DJANGO_QSTASH_DOMAIN.rstrip("/")
+    if not callback_domain.startswith(("http://", "https://")):
+        callback_domain = f"https://{callback_domain}"
+    webhook_path = DJANGO_QSTASH_WEBHOOK_PATH.strip("/")
+    return f"{callback_domain}/{webhook_path}/"

django_qstash-0.0.7/src/django_qstash/client.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from qstash import QStash
+
+from django_qstash.settings import QSTASH_TOKEN
+
+qstash_client = QStash(QSTASH_TOKEN)

django_qstash-0.0.7/src/django_qstash/discovery/fields.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from django import forms
+
+from django_qstash.discovery.utils import discover_tasks
+from django_qstash.discovery.validators import task_exists_validator
+
+
+class TaskChoiceField(forms.ChoiceField):
+    """
+    A form field that provides choices from discovered QStash tasks
+    """
+
+    def __init__(self, *args, **kwargs):
+        # Remove max_length if it's present since ChoiceField doesn't use it
+        kwargs.pop("max_length", None)
+
+        # Get tasks before calling parent to set choices
+        tasks = discover_tasks()
+
+        # Convert tasks to choices using (task_name, task_name) format
+        task_choices = [(task_value, task_label) for task_value, task_label in tasks]
+
+        kwargs["choices"] = task_choices
+        kwargs["validators"] = [task_exists_validator] + kwargs.get("validators", [])
+        super().__init__(*args, **kwargs)
+
+    def get_task(self):
+        """
+        Returns the actual task dot notation path for the selected value
+        """
+        if self.data:
+            tasks = discover_tasks()
+
+            for task_value, task_label in tasks:
+                if task_label == self.data:
+                    return task_value
+        return None

django_qstash-0.0.7/src/django_qstash/discovery/models.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from django.db import models
+
+from django_qstash.discovery.fields import TaskChoiceField
+
+
+class TaskField(models.CharField):
+    """
+    A model field for storing QStash task references
+    """
+
+    def __init__(self, *args, **kwargs):
+        # Set a reasonable max_length for task names if not provided
+        if "max_length" not in kwargs:
+            kwargs["max_length"] = 255
+        super().__init__(*args, **kwargs)
+
+    def formfield(self, **kwargs):
+        # Use our custom form field
+        defaults = {
+            "form_class": TaskChoiceField,
+        }
+        defaults.update(kwargs)
+        return super().formfield(**defaults)

django_qstash-0.0.7/src/django_qstash/discovery/utils.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import logging
+import os
+import warnings
+from functools import lru_cache
+from importlib import import_module
+
+from django.apps import apps
+from django.conf import settings
+from django.core.signals import request_started
+from django.utils.module_loading import module_has_submodule
+
+logger = logging.getLogger(__name__)
+
+DJANGO_QSTASH_DISCOVER_INCLUDE_SETTINGS_DIR = getattr(
+    settings, "DJANGO_QSTASH_DISCOVER_INCLUDE_SETTINGS_DIR", True
+)
+
+
+@lru_cache(maxsize=None)
+def discover_tasks() -> list[tuple[str, str]]:
+    """
+    Automatically discover tasks in Django apps and return them as a list of tuples.
+    Each tuple contains (dot_notation_path, task_name).
+    If no custom task name is specified, both values will be the dot notation path.
+
+    Returns:
+        List of tuples: [(dot_notation_path, task_name), ...]
+        Example: [
+            ('example_app.tasks.my_task', 'example_app.tasks.my_task'),
+            ('other_app.tasks.custom_task', 'special_name')
+        ]
+    """
+    from django_qstash.tasks import QStashTask
+
+    discovered_tasks = []
+    packages = []
+
+    # Add Django apps that contain tasks.py
+    for app_config in apps.get_app_configs():
+        if module_has_submodule(app_config.module, "tasks"):
+            packages.append(app_config.name)
+
+    # Add the directory containing settings.py if it has a tasks.py module
+    if DJANGO_QSTASH_DISCOVER_INCLUDE_SETTINGS_DIR:
+        settings_module = os.environ.get("DJANGO_SETTINGS_MODULE", "")
+        if settings_module:
+            settings_package = settings_module.rsplit(".", 1)[0]
+            try:
+                settings_module_obj = import_module(settings_package)
+                if module_has_submodule(settings_module_obj, "tasks"):
+                    packages.append(settings_package)
+            except ImportError:
+                warnings.warn(
+                    f"Could not import settings package {settings_package} for task discovery",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+
+    # Rest of the discovery logic
+    for package in packages:
+        try:
+            tasks_module = import_module(f"{package}.tasks")
+            # Find all attributes that are QstashTask instances
+            for attr_name in dir(tasks_module):
+                attr = getattr(tasks_module, attr_name)
+
+                if isinstance(attr, QStashTask):
+                    value = f"{package}.tasks.{attr_name}"
+                    if attr.name == attr_name:
+                        label = value
+                    else:
+                        label = f"{attr.name} ({value})"
+                    discovered_tasks.append((value, label))
+        except Exception as e:
+            warnings.warn(
+                f"Failed to import tasks from {package}: {str(e)}",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+    return discovered_tasks
+
+
+def clear_discover_tasks_cache(sender, **kwargs):
+    logger.info("Clearing Django QStash discovered tasks cache")
+    discover_tasks.cache_clear()
+
+
+request_started.connect(
+    clear_discover_tasks_cache,
+    dispatch_uid="clear_django_qstash_discovered_tasks_cache",
+)

django_qstash-0.0.7/src/django_qstash/discovery/validators.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from django.core.exceptions import ValidationError
+
+from django_qstash.discovery.utils import discover_tasks
+
+
+def task_exists_validator(task_name):
+    """
+    Validates that a task name exists in the discovered tasks
+
+    Args:
+        task_name: The name of the task to validate
+
+    Raises:
+        ValidationError: If the task cannot be found
+    """
+    tasks = discover_tasks()
+    available_tasks = [task[0] for task in tasks]
+
+    if task_name not in available_tasks:
+        raise ValidationError(
+            f"Task '{task_name}' not found. Available tasks: {', '.join(available_tasks)}"
+        )

django_qstash-0.0.7/src/django_qstash/management/commands/task_schedules.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import json
+import logging
+
+from django.apps import apps
+from django.core.management.base import BaseCommand
+from django.db import models
+
+from django_qstash.callbacks import get_callback_url
+from django_qstash.client import qstash_client
+
+logger = logging.getLogger(__name__)
+
+
+class Command(BaseCommand):
+    """Management command to list and sync QStash schedules."""
+
+    help = "List and sync schedules from QStash"
+
+    def add_arguments(self, parser) -> None:
+        parser.add_argument(
+            "--list",
+            action="store_true",
+            help="List schedules from QStash",
+        )
+        parser.add_argument(
+            "--sync",
+            action="store_true",
+            help="Sync schedules from QStash to local database",
+        )
+        parser.add_argument(
+            "--no-input",
+            action="store_true",
+            help="Do not ask for confirmation",
+        )
+
+    def get_task_schedule_model(self) -> models.Model | None:
+        """Get the TaskSchedule model if available."""
+        try:
+            return apps.get_model("django_qstash_schedules", "TaskSchedule")
+        except LookupError:
+            self.stdout.write(
+                self.style.ERROR(
+                    "Django QStash Schedules not installed.\n"
+                    "Add `django_qstash.schedules` to INSTALLED_APPS and run migrations."
+                )
+            )
+
+    def sync_schedules(self, schedules: list) -> None:
+        """Sync remote schedules to local database."""
+        TaskSchedule = self.get_task_schedule_model()
+
+        for schedule in schedules:
+            try:
+                body = json.loads(schedule.body)
+                task_name = body.get("task_name", "Unnamed Task")
+                function = f"{body['module']}.{body['function']}"
+
+                obj, created = TaskSchedule.objects.update_or_create(
+                    schedule_id=schedule.schedule_id,
+                    defaults={
+                        "name": task_name,
+                        "task": function,
+                        "cron": schedule.cron,
+                        "args": body.get("args", []),
+                        "kwargs": body.get("kwargs", {}),
+                    },
+                )
+                status = "Created" if created else "Updated"
+                logger.info(
+                    "%s schedule: %s (%s)", status, task_name, schedule.schedule_id
+                )
+            except Exception:
+                logger.exception("Failed to sync schedule %s", schedule.schedule_id)
+
+    def handle(self, *args, **options) -> None:
+        auto_confirm = options.get("no_input")
+        if not (options.get("sync") or options.get("list")):
+            self.stdout.write(
+                self.style.ERROR("Please specify either --list or --sync option")
+            )
+            return
+
+        try:
+            destination = get_callback_url()
+            schedules = qstash_client.schedule.list()
+
+            self.stdout.write(
+                self.style.SUCCESS(
+                    f"Found {len(schedules)} remote schedules based on destination: {destination}"
+                )
+            )
+
+            for schedule in schedules:
+                body = json.loads(schedule.body)
+                task_name = body.get("task_name", "Unnamed Task")
+                function = f"{body['module']}.{body['function']}"
+
+                self.stdout.write(
+                    f"\nSchedule ID: {schedule.schedule_id}"
+                    f"\n  Task: {task_name} ({function})"
+                    f"\n  Cron: {schedule.cron}"
+                    f"\n  Destination: {schedule.destination}"
+                    f"\n  Retries: {schedule.retries}"
+                    f"\n  Status: {'Paused' if schedule.paused else 'Active'}"
+                )
+
+            if options.get("sync"):
+                user_input = input("Do you want to sync remote schedules? (y/n): ")
+                if user_input.lower() == "y" or auto_confirm:
+                    self.sync_schedules(schedules)
+                else:
+                    self.stdout.write(self.style.ERROR("Sync cancelled"))
+        except Exception as e:
+            self.stdout.write(self.style.ERROR(f"An error occurred: {str(e)}"))

django_qstash-0.0.7/src/django_qstash/schedules/admin.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from django.contrib import admin
+
+from django_qstash.schedules import services
+from django_qstash.schedules.forms import TaskScheduleForm
+from django_qstash.schedules.models import TaskSchedule
+
+
+@admin.register(TaskSchedule)
+class TaskScheduleAdmin(admin.ModelAdmin):
+    list_display = ["schedule_id", "task_name"]
+    readonly_fields = [
+        "schedule_id",
+        "task_name",
+        "get_qstash_schedule_details",
+        "paused_at",
+        "resumed_at",
+        "active_at",
+    ]
+    form = TaskScheduleForm
+
+    fieldsets = [
+        (
+            "Name",
+            {
+                "fields": ["name", "schedule_id", "is_active"],
+            },
+        ),
+        (
+            "Task Selection",
+            {
+                "fields": ["task", "task_name"],
+            },
+        ),
+        (
+            "Arguments",
+            {
+                "fields": ["args", "kwargs"],
+            },
+        ),
+        (
+            "Schedule",
+            {
+                "fields": ["cron", "retries", "timeout"],
+            },
+        ),
+        (
+            "QStash Metadata",
+            {
+                "fields": [
+                    "paused_at",
+                    "resumed_at",
+                    "active_at",
+                    "get_qstash_schedule_details",
+                ],
+                "classes": ["collapse"],
+            },
+        ),
+    ]
+
+    @admin.display(description="Raw")
+    def get_qstash_schedule_details(self, obj: TaskSchedule) -> dict:
+        if not obj.schedule_id:
+            return "No schedule ID yet"
+        return services.get_task_schedule_from_qstash(obj, as_dict=True)

django_qstash-0.0.7/src/django_qstash/schedules/apps.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class SchedulesConfig(AppConfig):
+    name = "django_qstash.schedules"
+    label = "django_qstash_schedules"
+    verbose_name = "django_qstash_schedules"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        import django_qstash.schedules.signals  # noqa

django_qstash-0.0.7/src/django_qstash/schedules/exceptions.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from django.core.exceptions import ValidationError
+
+
+class InvalidDurationStringValidationError(ValidationError):
+    """Invalid duration string."""
+
+    pass

django_qstash-0.0.7/src/django_qstash/schedules/formatters.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from django_qstash.callbacks import get_callback_url
+from django_qstash.schedules.models import TaskSchedule
+
+
+def prepare_qstash_payload(instance: TaskSchedule) -> dict[str, Any]:
+    """Prepare the task payload for QStash"""
+    return {
+        "function": instance.task_name.split(".")[-1],  # Get function name
+        "module": ".".join(instance.task_name.split(".")[:-1]),  # Get module path
+        "args": instance.args,
+        "kwargs": instance.kwargs,
+        "task_name": instance.name,
+        "options": {
+            "max_retries": instance.retries,
+            "timeout": instance.timeout,
+        },
+    }
+
+
+def format_task_schedule_for_qstash(instance: TaskSchedule) -> dict[str, Any]:
+    payload = prepare_qstash_payload(instance)
+    callback_url = get_callback_url()
+    data = {
+        "destination": callback_url,
+        "body": json.dumps(payload),
+        "cron": instance.cron,
+        "retries": instance.retries,
+        "timeout": instance.timeout,
+    }
+    if instance.schedule_id:
+        data["schedule_id"] = instance.schedule_id
+    return data

django_qstash-0.0.7/src/django_qstash/schedules/forms.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from django import forms
+
+from django_qstash.discovery.fields import TaskChoiceField
+from django_qstash.schedules.models import TaskSchedule
+
+
+class TaskScheduleForm(forms.ModelForm):
+    task = TaskChoiceField()
+
+    class Meta:
+        model = TaskSchedule
+        fields = [
+            "name",
+            "task",
+            "task_name",
+            "args",
+            "kwargs",
+            "schedule_id",
+            "cron",
+            "retries",
+            "timeout",
+        ]

django_qstash-0.0.7/src/django_qstash/schedules/migrations/0001_initial.py

@@ -0,0 +1,122 @@
+# Generated by Django 5.1.4 on 2025-01-02 06:28
+
+from __future__ import annotations
+
+import django.core.validators
+import django.utils.timezone
+from django.db import migrations
+from django.db import models
+
+import django_qstash.discovery.models
+import django_qstash.schedules.validators
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="TaskSchedule",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "schedule_id",
+                    models.CharField(
+                        blank=True,
+                        db_index=True,
+                        help_text="The schedule ID stored in QStash",
+                        max_length=255,
+                        null=True,
+                        unique=True,
+                        verbose_name="Schedule ID",
+                    ),
+                ),
+                (
+                    "name",
+                    models.CharField(
+                        help_text="Short Description For This Task Schedule",
+                        max_length=200,
+                        verbose_name="Name",
+                    ),
+                ),
+                ("task", django_qstash.discovery.models.TaskField(max_length=255)),
+                (
+                    "task_name",
+                    models.CharField(
+                        blank=True,
+                        help_text="Original Python location of task",
+                        max_length=255,
+                    ),
+                ),
+                (
+                    "args",
+                    models.JSONField(
+                        blank=True,
+                        default=list,
+                        help_text='JSON encoded positional arguments (Example: ["arg1", "arg2"])',
+                        verbose_name="Positional Arguments",
+                    ),
+                ),
+                (
+                    "kwargs",
+                    models.JSONField(
+                        blank=True,
+                        default=dict,
+                        help_text='JSON encoded keyword arguments (Example: {"argument": "value"})',
+                        verbose_name="Keyword Arguments",
+                    ),
+                ),
+                (
+                    "cron",
+                    models.CharField(
+                        default="*/5 * * * *",
+                        help_text="Cron expression for scheduling the task",
+                        max_length=255,
+                        verbose_name="Cron Expression",
+                    ),
+                ),
+                (
+                    "retries",
+                    models.IntegerField(
+                        default=3,
+                        help_text="Number of times to retry the task if it fails",
+                        validators=[django.core.validators.MaxValueValidator(5)],
+                        verbose_name="Retries",
+                    ),
+                ),
+                (
+                    "timeout",
+                    models.CharField(
+                        default="60s",
+                        help_text="Duration string for task timeout (e.g., '1s', '5m', '2h'). See Max HTTP Connection Timeout on QStash pricing page for allowed values for your Upstash account.",
+                        max_length=10,
+                        validators=[
+                            django_qstash.schedules.validators.validate_duration_string
+                        ],
+                        verbose_name="Timeout",
+                    ),
+                ),
+                ("is_active", models.BooleanField(default=True)),
+                (
+                    "active_at",
+                    models.DateTimeField(
+                        blank=True, default=django.utils.timezone.now, null=True
+                    ),
+                ),
+                ("is_paused", models.BooleanField(default=False)),
+                ("paused_at", models.DateTimeField(blank=True, null=True)),
+                ("is_resumed", models.BooleanField(default=False)),
+                ("resumed_at", models.DateTimeField(blank=True, null=True)),
+            ],
+        ),
+    ]

django_qstash-0.0.7/src/django_qstash/schedules/migrations/0002_taskschedule_updated_at.py

@@ -0,0 +1,20 @@
+# Generated by Django 5.1.4 on 2025-01-02 07:44
+
+from __future__ import annotations
+
+from django.db import migrations
+from django.db import models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("django_qstash_schedules", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="taskschedule",
+            name="updated_at",
+            field=models.DateTimeField(auto_now=True),
+        ),
+    ]