django-qstash 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

django_qstash/__init__.py

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

django_qstash/exceptions.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+
+class WebhookError(Exception):
+    """Base exception for webhook handling errors."""
+
+    pass
+
+
+class SignatureError(WebhookError):
+    """Invalid or missing signature."""
+
+    pass
+
+
+class PayloadError(WebhookError):
+    """Invalid payload structure or content."""
+
+    pass
+
+
+class TaskError(WebhookError):
+    """Error in task execution."""
+
+    pass

django_qstash/handlers.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from django.conf import settings
+from django.http import HttpRequest
+from qstash import Receiver
+
+from . import utils
+from .exceptions import PayloadError
+from .exceptions import SignatureError
+from .exceptions import TaskError
+from .results.services import store_task_result
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TaskPayload:
+    function: str
+    module: str
+    args: list
+    kwargs: dict
+    task_name: str
+    function_path: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> TaskPayload:
+        """Create TaskPayload from dictionary."""
+        is_valid, error = utils.validate_task_payload(data)
+        if not is_valid:
+            raise PayloadError(error)
+
+        function_path = f"{data['module']}.{data['function']}"
+        return cls(
+            function=data["function"],
+            module=data["module"],
+            args=data["args"],
+            kwargs=data["kwargs"],
+            task_name=data.get("task_name", function_path),
+            function_path=function_path,
+        )
+
+
+class QStashWebhook:
+    def __init__(self):
+        self.receiver = Receiver(
+            current_signing_key=settings.QSTASH_CURRENT_SIGNING_KEY,
+            next_signing_key=settings.QSTASH_NEXT_SIGNING_KEY,
+        )
+        self.force_https = getattr(settings, "DJANGO_QSTASH_FORCE_HTTPS", True)
+
+    def verify_signature(self, body: str, signature: str, url: str) -> None:
+        """Verify QStash signature."""
+        if not signature:
+            raise SignatureError("Missing Upstash-Signature header")
+
+        if self.force_https and not url.startswith("https://"):
+            url = url.replace("http://", "https://")
+
+        try:
+            self.receiver.verify(body=body, signature=signature, url=url)
+        except Exception as e:
+            raise SignatureError(f"Invalid signature: {e}")
+
+    def parse_payload(self, body: str) -> TaskPayload:
+        """Parse and validate webhook payload."""
+        try:
+            data = json.loads(body)
+            return TaskPayload.from_dict(data)
+        except json.JSONDecodeError as e:
+            raise PayloadError(f"Invalid JSON payload: {e}")
+
+    def execute_task(self, payload: TaskPayload) -> Any:
+        """Import and execute the task function."""
+        try:
+            task_func = utils.import_string(payload.function_path)
+        except ImportError as e:
+            raise TaskError(f"Could not import task function: {e}")
+
+        try:
+            if callable(task_func) and hasattr(task_func, "actual_func"):
+                return task_func.actual_func(*payload.args, **payload.kwargs)
+            return task_func(*payload.args, **payload.kwargs)
+        except Exception as e:
+            raise TaskError(f"Task execution failed: {e}")
+
+    def handle_request(self, request: HttpRequest) -> tuple[dict, int]:
+        """Process webhook request and return response data and status code."""
+        payload = None  # Initialize payload as None
+        try:
+            body = request.body.decode()
+            self.verify_signature(
+                body=body,
+                signature=request.headers.get("Upstash-Signature"),
+                url=request.build_absolute_uri(),
+            )
+
+            payload = self.parse_payload(body)
+            result = self.execute_task(payload)
+
+            store_task_result(
+                task_id=request.headers.get("Upstash-Message-Id"),
+                task_name=payload.task_name,
+                status="SUCCESS",
+                result=result,
+                args=payload.args,
+                kwargs=payload.kwargs,
+            )
+
+            return {
+                "status": "success",
+                "task_name": payload.task_name,
+                "result": result if result is not None else "null",
+            }, 200
+
+        except (SignatureError, PayloadError) as e:
+            logger.exception("Authentication error: %s", str(e))
+            return {
+                "status": "error",
+                "error_type": e.__class__.__name__,
+                "error": str(e),
+                "task_name": getattr(payload, "task_name", None),
+            }, 400
+        except TaskError as e:
+            logger.exception("Task execution error: %s", str(e))
+            return {
+                "status": "error",
+                "error_type": e.__class__.__name__,
+                "error": str(e),
+                "task_name": payload.task_name if payload else None,
+            }, 500
+        except Exception as e:
+            logger.exception("Unexpected error in webhook handler: %s", str(e))
+            return {
+                "status": "error",
+                "error_type": "InternalServerError",
+                "error": "An unexpected error occurred",
+                "task_name": getattr(payload, "task_name", None),
+            }, 500

django_qstash/management/commands/clear_stale_results.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from datetime import timedelta
+
+from django.apps import apps
+from django.conf import settings
+from django.core.management.base import BaseCommand
+from django.utils import timezone
+
+DJANGO_QSTASH_RESULT_TTL = getattr(settings, "DJANGO_QSTASH_RESULT_TTL", 604800)
+
+
+class Command(BaseCommand):
+    help = f"""Clears stale task results older than\n
+    {DJANGO_QSTASH_RESULT_TTL} seconds (settings.DJANGO_QSTASH_RESULT_TTL)"""
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--no-input",
+            action="store_true",
+            help="Do not ask for confirmation",
+        )
+        parser.add_argument(
+            "--since",
+            type=int,
+            help="The number of seconds ago to clear results for",
+        )
+
+    def handle(self, *args, **options):
+        no_input = options["no_input"]
+        since = options.get("since") or DJANGO_QSTASH_RESULT_TTL
+        cutoff_date = timezone.now() - timedelta(seconds=since)
+        try:
+            TaskResult = apps.get_model("django_qstash_results", "TaskResult")
+        except LookupError:
+            self.stdout.write(
+                self.style.ERROR(
+                    "Django QStash Results not installed.\nAdd `django_qstash.results` to INSTALLED_APPS and run migrations."
+                )
+            )
+            return
+        to_delete = TaskResult.objects.filter(date_done__lt=cutoff_date)
+
+        if not to_delete.exists():
+            self.stdout.write("No stale Django QStash task results found")
+            return
+
+        # use input to confirm  deletion
+        self.stdout.write(
+            f"Deleting {to_delete.count()} task results older than {cutoff_date} ({DJANGO_QSTASH_RESULT_TTL} seconds)"
+        )
+        if not no_input:
+            if input("Are you sure? (y/n): ") != "y":
+                self.stdout.write("Skipping deletion")
+                return
+
+        deleted_count, _ = to_delete.delete()
+
+        self.stdout.write(
+            self.style.SUCCESS(f"Successfully deleted {deleted_count} stale results.")
+        )

django_qstash/results/admin.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from django.contrib import admin
+
+from .models import TaskResult
+
+
+@admin.register(TaskResult)
+class TaskResultAdmin(admin.ModelAdmin):
+    readonly_fields = [
+        "task_name",
+        "status",
+        "date_done",
+        "result",
+        "traceback",
+        "args",
+        "kwargs",
+        "task_id",
+        "date_created",
+    ]
+    list_display = ["task_name", "status", "date_done"]

django_qstash/results/apps.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class ResultsConfig(AppConfig):
+    name = "django_qstash.results"
+    label = "django_qstash_results"
+    verbose_name = "django_qstash_results"
+    default_auto_field = "django.db.models.BigAutoField"

django_qstash/results/migrations/0001_initial.py

@@ -0,0 +1,62 @@
+# Generated by Django 5.1.4 on 2024-12-30 23:31
+
+from __future__ import annotations
+
+import uuid
+
+import django.utils.timezone
+from django.db import migrations
+from django.db import models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="TaskResult",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid1,
+                        editable=False,
+                        primary_key=True,
+                        serialize=False,
+                        unique=True,
+                    ),
+                ),
+                (
+                    "task_id",
+                    models.CharField(db_index=True, max_length=255, unique=True),
+                ),
+                ("task_name", models.CharField(max_length=255)),
+                (
+                    "status",
+                    models.CharField(
+                        choices=[
+                            ("PENDING", "Pending"),
+                            ("SUCCESS", "Success"),
+                            ("FAILURE", "Failure"),
+                        ],
+                        default="PENDING",
+                        max_length=50,
+                    ),
+                ),
+                (
+                    "date_created",
+                    models.DateTimeField(default=django.utils.timezone.now),
+                ),
+                ("date_done", models.DateTimeField(null=True)),
+                ("result", models.JSONField(null=True)),
+                ("traceback", models.TextField(null=True)),
+                ("args", models.JSONField(null=True)),
+                ("kwargs", models.JSONField(null=True)),
+            ],
+            options={
+                "ordering": ["-date_done"],
+            },
+        ),
+    ]

django_qstash/results/models.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import uuid
+
+from django.db import models
+from django.utils import timezone
+
+
+class TaskResult(models.Model):
+    id = models.UUIDField(
+        primary_key=True, default=uuid.uuid1, editable=False, unique=True
+    )
+    task_id = models.CharField(max_length=255, unique=True, db_index=True)
+    task_name = models.CharField(max_length=255)
+    status = models.CharField(
+        max_length=50,
+        choices=[
+            ("PENDING", "Pending"),
+            ("SUCCESS", "Success"),
+            ("FAILURE", "Failure"),
+        ],
+        default="PENDING",
+    )
+    date_created = models.DateTimeField(default=timezone.now)
+    date_done = models.DateTimeField(null=True)
+    result = models.JSONField(null=True)
+    traceback = models.TextField(null=True)
+    args = models.JSONField(null=True)
+    kwargs = models.JSONField(null=True)
+
+    class Meta:
+        app_label = "django_qstash_results"
+        ordering = ["-date_done"]
+
+    def __str__(self):
+        return f"{self.task_name} ({self.task_id})"

django_qstash/results/services.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import logging
+
+from django.apps import apps
+from django.utils import timezone
+
+logger = logging.getLogger(__name__)
+
+
+def store_task_result(
+    task_id, task_name, status, result=None, traceback=None, args=None, kwargs=None
+):
+    """Helper function to store task results if the results app is installed"""
+    try:
+        TaskResult = apps.get_model("django_qstash_results", "TaskResult")
+        task_result = TaskResult.objects.create(
+            task_id=task_id,
+            task_name=task_name,
+            status=status,
+            date_done=timezone.now(),
+            result=result,
+            traceback=traceback,
+            args=args,
+            kwargs=kwargs,
+        )
+        return task_result
+    except LookupError:
+        # Model isn't installed, skip storage
+        logger.debug(
+            "Django QStash Results not installed. Add `django_qstash.results` to INSTALLED_APPS and run migrations."
+        )
+        return None

django_qstash/tasks.py

@@ -1,5 +1,9 @@
+from __future__ import annotations
+
 import functools
-from typing import Any, Callable, Dict, Optional, Tuple
+import warnings
+from typing import Any
+from typing import Callable
 
 from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
@@ -11,7 +15,11 @@ DJANGO_QSTASH_WEBHOOK_PATH = getattr(
     settings, "DJANGO_QSTASH_WEBHOOK_PATH", "/qstash/webhook/"
 )
 if not QSTASH_TOKEN or not DJANGO_QSTASH_DOMAIN:
-    raise ImproperlyConfigured("QSTASH_TOKEN and DJANGO_QSTASH_DOMAIN must be set")
+    warnings.warn(
+        "QSTASH_TOKEN and DJANGO_QSTASH_DOMAIN should be set for QStash functionality",
+        RuntimeWarning,
+        stacklevel=2,
+    )
 
 # Initialize QStash client once
 qstash_client = QStash(QSTASH_TOKEN)
@@ -20,11 +28,11 @@ qstash_client = QStash(QSTASH_TOKEN)
 class QStashTask:
     def __init__(
         self,
-        func: Optional[Callable] = None,
-        name: Optional[str] = None,
-        delay_seconds: Optional[int] = None,
+        func: Callable | None = None,
+        name: str | None = None,
+        delay_seconds: int | None = None,
         deduplicated: bool = False,
-        **options: Dict[str, Any],
+        **options: dict[str, Any],
     ):
         self.func = func
         self.name = name or (func.__name__ if func else None)
@@ -45,6 +53,10 @@ class QStashTask:
         """
         Execute the task, either directly or via QStash based on context
         """
+        if not QSTASH_TOKEN or not DJANGO_QSTASH_DOMAIN:
+            raise ImproperlyConfigured(
+                "QSTASH_TOKEN and DJANGO_QSTASH_DOMAIN must be set to use django-qstash"
+            )
         # Handle the case when the decorator is used without parameters
         if self.func is None:
             return self.__class__(
@@ -89,18 +101,18 @@ class QStashTask:
         # Return an AsyncResult-like object for Celery compatibility
         return AsyncResult(response.message_id)
 
-    def delay(self, *args, **kwargs) -> "AsyncResult":
+    def delay(self, *args, **kwargs) -> AsyncResult:
         """Celery-compatible delay() method"""
         self._is_delayed = True
         return self(*args, **kwargs)
 
     def apply_async(
         self,
-        args: Optional[Tuple] = None,
-        kwargs: Optional[Dict] = None,
-        countdown: Optional[int] = None,
-        **options: Dict[str, Any],
-    ) -> "AsyncResult":
+        args: tuple | None = None,
+        kwargs: dict | None = None,
+        countdown: int | None = None,
+        **options: dict[str, Any],
+    ) -> AsyncResult:
         """Celery-compatible apply_async() method"""
         self._is_delayed = True
         if countdown is not None:
@@ -119,7 +131,7 @@ class AsyncResult:
     def __init__(self, task_id: str):
         self.task_id = task_id
 
-    def get(self, timeout: Optional[int] = None) -> Any:
+    def get(self, timeout: int | None = None) -> Any:
         """Simulate Celery's get() method"""
         raise NotImplementedError("QStash doesn't support result retrieval")
 
@@ -129,10 +141,10 @@ class AsyncResult:
 
 
 def shared_task(
-    func: Optional[Callable] = None,
-    name: Optional[str] = None,
+    func: Callable | None = None,
+    name: str | None = None,
     deduplicated: bool = False,
-    **options: Dict[str, Any],
+    **options: dict[str, Any],
 ) -> QStashTask:
     """
     Decorator that mimics Celery's shared_task

django_qstash/views.py

@@ -1,124 +1,21 @@
+from __future__ import annotations
+
 import json
-import logging
 
-from django.conf import settings
-from django.http import (
-    HttpRequest,
-    HttpResponse,
-    HttpResponseBadRequest,
-    HttpResponseForbidden,
-)
+from django.http import HttpRequest
+from django.http import HttpResponse
 from django.views.decorators.csrf import csrf_exempt
 from django.views.decorators.http import require_http_methods
-from qstash import Receiver
-
-from . import utils
-
-DJANGO_QSTASH_FORCE_HTTPS = getattr(settings, "DJANGO_QSTASH_FORCE_HTTPS", True)
-
-logger = logging.getLogger(__name__)
 
-
-# Initialize the QStash receiver
-receiver = Receiver(
-    current_signing_key=settings.QSTASH_CURRENT_SIGNING_KEY,
-    next_signing_key=settings.QSTASH_NEXT_SIGNING_KEY,
-)
+from .handlers import QStashWebhook
 
 
 @csrf_exempt
 @require_http_methods(["POST"])
 def qstash_webhook_view(request: HttpRequest) -> HttpResponse:
-    """
-    Webhook handler for QStash callbacks.
-
-    Expects a POST request with:
-    - Upstash-Signature header for verification
-    - JSON body containing task information:
-        {
-            "function": "full.path.to.function",
-            "module": "module.path",
-            "args": [...],
-            "kwargs": {...},
-            "task_name": "optional_task_name",
-            "options": {...}
-        }
-    """
-    try:
-        # Get the signature from headers
-        signature = request.headers.get("Upstash-Signature")
-        if not signature:
-            return HttpResponseForbidden("Missing Upstash-Signature header")
-
-        # Verify the signature using the QStash SDK
-        url = request.build_absolute_uri()
-        if DJANGO_QSTASH_FORCE_HTTPS and not url.startswith("https://"):
-            url = url.replace("http://", "https://")
-        try:
-            receiver.verify(
-                body=request.body.decode(),
-                signature=signature,
-                url=url,
-            )
-        except Exception as e:
-            logger.error(f"Signature verification failed: {e}")
-            return HttpResponseForbidden("Invalid signature")
-
-        # Parse the payload
-        try:
-            payload = json.loads(request.body.decode())
-        except json.JSONDecodeError as e:
-            logger.error(f"Failed to parse JSON payload: {e}")
-            return HttpResponseBadRequest("Invalid JSON payload")
-
-        # Validate payload structure
-        is_valid, error_message = utils.validate_task_payload(payload)
-        if not is_valid:
-            logger.error(f"Invalid payload structure: {error_message}")
-            return HttpResponseBadRequest(error_message)
-
-        # Import the function
-        try:
-            function_path = f"{payload['module']}.{payload['function']}"
-            task_func = utils.import_string(function_path)
-        except ImportError as e:
-            logger.error(f"Failed to import task function: {e}")
-            return HttpResponseBadRequest(f"Could not import task function: {e}")
-
-        # Execute the task
-        try:
-            if hasattr(task_func, "__call__") and hasattr(task_func, "actual_func"):
-                # If it's a wrapped function, call the actual function directly
-                result = task_func.actual_func(*payload["args"], **payload["kwargs"])
-            else:
-                result = task_func(*payload["args"], **payload["kwargs"])
-
-            # Prepare the response
-            response_data = {
-                "status": "success",
-                "task_name": payload.get("task_name", function_path),
-                "result": result if result is not None else "null",
-            }
-
-            return HttpResponse(
-                json.dumps(response_data), content_type="application/json"
-            )
-
-        except Exception as e:
-            logger.exception(f"Task execution failed: {e}")
-            error_response = {
-                "status": "error",
-                "task_name": payload.get("task_name", function_path),
-                "error": str(e),
-            }
-            return HttpResponse(
-                json.dumps(error_response), status=500, content_type="application/json"
-            )
-
-    except Exception as e:
-        logger.exception(f"Unexpected error in webhook handler: {e}")
-        return HttpResponse(
-            json.dumps({"status": "error", "error": "Internal server error"}),
-            status=500,
-            content_type="application/json",
-        )
+    """Handle QStash webhook requests."""
+    webhook = QStashWebhook()
+    response_data, status_code = webhook.handle_request(request)
+    return HttpResponse(
+        json.dumps(response_data), status=status_code, content_type="application/json"
+    )

django_qstash-0.0.4.dist-info/METADATA

@@ -0,0 +1,343 @@
+Metadata-Version: 2.1
+Name: django-qstash
+Version: 0.0.4
+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
+Project-URL: Documentation, https://github.com/jmitchel3/django-qstash
+Project-URL: Funding, https://github.com/jmitchel3/django-qstash
+Project-URL: Repository, https://github.com/jmitchel3/django-qstash
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: django>=4.2
+Requires-Dist: qstash>=2
+Requires-Dist: requests>=2.30
+
+> :warning: **BETA Software**: Working on being production-ready soon.
+
+# django-qstash
+
+_django-qstash_ is a drop-in replacement for Celery's `shared_task`.
+
+To do this, we use:
+
+- [Upstash QStash](https://upstash.com/docs/qstash/overall/getstarted)
+- A single public _webhook_ to call `@shared_task` functions automatically
+
+This allows us to:
+
+- Focus just on Django
+- Drop Celery
+- Truly scale Django to zero
+- Run background tasks through webhooks
+- Cut costs
+- Trigger GitHub Actions Workflows or GitLab CI/CD pipelines for handling other kinds of background tasks based on our project's code.
+
+
+## Table of Contents
+
+- [django-qstash](#django-qstash)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+    - [Using Pip](#using-pip)
+    - [Update Settings (`settings.py`)](#update-settings-settingspy)
+    - [Configure Webhook URL](#configure-webhook-url)
+    - [Required Environment Variables](#required-environment-variables)
+  - [Sample Project](#sample-project)
+  - [Dependencies](#dependencies)
+  - [Usage](#usage)
+    - [Define a Task](#define-a-task)
+    - [Regular Task Call](#regular-task-call)
+    - [Async Task](#async-task)
+      - [`.delay()`](#delay)
+      - [`.apply_async()`](#apply_async)
+      - [`.apply_async()` With Time Delay](#apply_async-with-time-delay)
+    - [JSON-ready Arguments](#json-ready-arguments)
+    - [Example Task](#example-task)
+  - [Configuration](#configuration)
+  - [Storing Task Results (Optional)](#storing-task-results-optional)
+    - [Clear Stale Results](#clear-stale-results)
+  - [Definitions](#definitions)
+  - [Motivation](#motivation)
+
+
+## Installation
+
+### Using Pip
+```bash
+pip install django-qstash
+```
+
+### Update Settings (`settings.py`)
+
+```python
+INSTALLED_APPS = [
+    ##...
+    "django_qstash",
+    "django_qstash.results",
+    ##...
+]
+```
+- `django_qstash` Includes the `@shared_task` decorator and webhook view
+- `django_qstash.results` (Optional): Store task results in Django DB
+
+
+### Configure Webhook URL
+
+In your `ROOT_URLCONF` (e.g. `urls.py`), add the following:
+```python
+from django_qstash.views import qstash_webhook_view
+
+urlpatterns = [
+    # ...
+    path("qstash/webhook/", qstash_webhook_view),
+    # ...
+]
+```
+Be sure to use this path in your `DJANGO_QSTASH_WEBHOOK_PATH` environment variable.
+
+### Required Environment Variables
+
+Get your QStash token and signing keys from [Upstash](https://upstash.com/).
+
+```python
+QSTASH_TOKEN = "your_token"
+QSTASH_CURRENT_SIGNING_KEY = "your_current_signing_key"
+QSTASH_NEXT_SIGNING_KEY = "your_next_signing_key"
+
+# required for django-qstash
+DJANGO_QSTASH_DOMAIN = "https://example.com"
+DJANGO_QSTASH_WEBHOOK_PATH = "/qstash/webhook/"
+```
+> Review [.env.sample](.env.sample) to see all the environment variables you need to set.
+
+
+## Sample Project
+There is a sample project in [sample_project/](sample_project/) that shows how all this is implemented.
+
+## Dependencies
+
+- [Python 3.10+](https://www.python.org/)
+- [Django 5+](https://docs.djangoproject.com/)
+- [qstash-py](https://github.com/upstash/qstash-py)
+- [Upstash](https://upstash.com/) account
+
+## Usage
+
+Django-QStash revolves around the `shared_task` decorator. The goal is to be a drop-in replacement for Celery's `shared_task` decorator.
+
+Here's how it works:
+- Define a Task
+- Call a Task with `.delay()` or `.apply_async()`
+
+### Define a Task
+```python
+from django_qstash import shared_task
+
+
+@shared_task
+def hello_world(name: str, age: int = None, activity: str = None):
+    if age is None:
+        print(f"Hello {name}! I see you're {activity}.")
+        return
+    print(f"Hello {name}! I see you're {activity} at {age} years old.")
+```
+
+
+### Regular Task Call
+Nothing special here. Just call the function like any other to verify it works.
+
+```python
+# normal function call
+hello_world("Tony Stark", age=40, activity="building in a cave with a box of scraps.")
+```
+
+### Async Task
+
+Using `.delay()` or `.apply_async()` is how you call an async task. This is modeled after Celery and it works as you'd expect.
+
+
+#### `.delay()`
+```python
+hello_world.delay(
+    "Tony Stark", age=40, activity="building in a cave with a box of scraps."
+)
+```
+
+#### `.apply_async()`
+```python
+hello_world.apply_async(
+    args=("Tony Stark",),
+    kwargs={"activity": "building in a cave with a box of scraps."},
+)
+```
+
+#### `.apply_async()` With Time Delay
+
+Just use the `countdown` parameter to delay the task by N seconds. (always in seconds): `.apply_async(*args, **kwargs, countdown=N)`
+
+
+```python
+# async task delayed 35 seconds
+delay_35_seconds = 35
+hello_world.apply_async(
+    args=("Tony Stark",),
+    kwargs={"activity": "building in a cave with a box of scraps."},
+    countdown=delay_35_seconds,
+)
+```
+
+### JSON-ready Arguments
+
+Each argument needs to be _JSON_ serializable. The way you find out:
+
+```python
+import json
+
+data = {
+    "args": ("Tony Stark",),
+    "kwargs": {"activity": "building in a cave with a box of scraps."},
+}
+print(json.dumps(data))
+# no errors, you're good to go.
+```
+
+### Example Task
+
+```python
+# from celery import shared_task
+from django_qstash import shared_task
+
+
+@shared_task
+def math_add_task(a, b, save_to_file=False, *args, **kwargs):
+    logger.info(f"Adding {a} and {b}")
+    if save_to_file:
+        with open("math-add-result.txt", "w") as f:
+            f.write(f"{a} + {b} = {a + b}")
+    return a + b
+```
+
+
+Calling:
+```python
+math_add_task.apply_async(args=(12, 454), save_to_file=True)
+```
+is the same as
+```python
+math_add_task.delay(12, 454, save_to_file=True)
+```
+
+But if you need to delay the task, use `.apply_async()` with the `countdown` parameter.
+
+```python
+five_hours = 5 * 60 * 60
+math_add_task.apply_async(
+    args=(12, 454), kwargs={"save_to_file": True}, countdown=five_hours
+)
+```
+
+The `.delay()` method does not support a countdown parameter because it simply passes the arguments (*args, **kwargs) to the `apply_async()` method.
+
+
+## Configuration
+
+In Django settings, you can configure the following:
+
+`DJANGO_QSTASH_DOMAIN`: Must be a valid and publicly accessible domain. For example `https://djangoqstash.com`
+
+In development mode, we recommend using a tunnel like [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with a domain name you control. You can also consider [ngrok](https://ngrok.com/).
+
+`DJANGO_QSTASH_WEBHOOK_PATH` (default:`/qstash/webhook/`): The path where QStash will send webhooks to your Django application.
+
+`DJANGO_QSTASH_FORCE_HTTPS` (default:`True`): Whether to force HTTPS for the webhook.
+
+`DJANGO_QSTASH_RESULT_TTL` (default:`604800`): A number of seconds after which task result data can be safely deleted. Defaults to 604800 seconds (7 days or 7 * 24 * 60 * 60).
+
+
+## Storing Task Results (Optional)
+
+In `django_qstash.results.models` we have the `TaskResult` model class that can be used to track async task results. These entries are created via webhooks.
+
+To install it, just add `django_qstash.results` to your `INSTALLED_APPS` setting.
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_qstash.results",
+    # ...
+]
+```
+
+Run migrations:
+```bash
+python manage.py migrate
+```
+
+### Clear Stale Results
+
+We recommend purging the `TaskResult` model after a certain amount of time.
+```bash
+python manage.py clear_stale_results
+```
+Args:
+- `--since` is the number of seconds ago to clear results for. Defaults to 604800 seconds (7 days or the `DJANGO_QSTASH_RESULT_TTL` setting).
+- `--no-input` is a flag to skip the confirmation prompt to delete the results.
+
+
+
+## Definitions
+
+- **Background Task**: A function or task that is not part of the request/response cycle.
+  - Examples include as sending an email, running a report, or updating a database.
+  - Pro: Background tasks can drastically improve the end-user experience since they can move on with their day while the task runs in the background.
+  - Con: Processes that run background tasks (like Celery) typically have to run 24/7.
+- **Scale-to-Zero**: Depending on the amount of traffic, Django can be effectively turned off. If done right, when more traffic comes in, Django can be turned back on very quickly.
+- **Serverless**: A cloud computing model where code runs without server management, with scaling and billing tied to usage. Often used interchangeably with "scale-to-zero".
+
+
+## Motivation
+
+TLDR - Celery cannot be serverless. I want serverless "Celery" so I only pay for the apps that have attention and traffic. Upstash created QStash to help solve the problem of message queues in a serverless environment. django-qstash is the goldilocks that combines the functionality of Celery with the functionality of QStash all to unlock fully serverless Django.
+
+I run a lot of side projects with Django. Some as demos for tutorials based on my work at [@codingforentrepreneurs](https://cfe.sh/github) and some are new businesses that haven't found much traction yet.
+
+Most web apps can benefit from async background tasks such as sending emails, running reports, or updating databases.
+
+But how?
+
+Traditionally, I'd reach for Celery but that can get expensive really quick. Running a lot of Django projects can add up too -- "death by a thousand cuts" if you will. A server for Django, for celery worker, for celery beat scheduler, and so on. It adds up fast.
+
+I think serverless is the answer. Pay for what you use and scale to zero when you don't need it and scale up when you do -- all automated.
+
+Django can be serverless and is pretty easy to do thanks to Docker and the countless hosting options and services out there. Celery cannot be serverless, at least yet.
+
+Let's face it. Celery is a powerful tool to run async background tasks but it comes at a cost. It needs at least one server running 24/7. For best performance it needs 2 (one worker, one beat). It also needs Redis or RabbitMQ. Most background processes that are tied to web apps are not serverless; they have to "listen" for their next task.
+
+To make Django truly scale-to-zero and serverless, we need to drop Celery.
+
+Enter __django-qstash__.
+
+django-qstash is designed to be a near drop-in replacement for Celery's `shared_task` decorator.
+
+It works by leveraging Upstash QStash to deliver messages about your tasks (e.g. the function's arguments) via webhooks to your Django application.  In the QStash [docs](https://upstash.com/docs/qstash/overall/getstarted), it is described as:
+
+> QStash is a serverless messaging and scheduling solution. It fits easily into your existing workflow and allows you to build reliable systems without managing infrastructure.
+>
+> Instead of calling an endpoint directly, QStash acts as a middleman between you and an API to guarantee delivery, perform automatic retries on failure, and more.
+
+django-qstash has a webhook handler that converts a QStash message to run a specific `@shared_task` function (the one that called `.delay()` or `.apply_async()`). It's easy, it's cheap, it's effective, and best of all, it unlocks the scale-to-zero potential of Django as a serverless app.

django_qstash-0.0.4.dist-info/RECORD

@@ -0,0 +1,19 @@
+django_qstash/__init__.py,sha256=wkPLjMVFXjwiEliBROhlszOouSwzpvgVAXU0IfHtlAw,117
+django_qstash/exceptions.py,sha256=pH6kKRJFIVFkDHUJQ9yRWmtGdBBSXpNAwMSFuNzMgPw,392
+django_qstash/handlers.py,sha256=mmm8TJOqV3j1rQXooNOa128gtmALXFNCAaDZ5xwIcuw,4950
+django_qstash/tasks.py,sha256=tiBJz8BIOYRD6MN0k4_1ncKCjLlptP3BvTad9lz7YVo,5220
+django_qstash/utils.py,sha256=wrTU30cobO2di18BNEFtKD4ih2euf7eQNpg6p6TkQ1Y,1185
+django_qstash/views.py,sha256=H32f_jGnlwOTO0YG9znNo2b-GRYZ8TM-Wt0T62SGdXM,639
+django_qstash/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_qstash/management/commands/clear_stale_results.py,sha256=stHCnvC1ER_rZXKUK-YVUgazC2q04eGIHjo_BrPSDEI,2096
+django_qstash/results/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_qstash/results/admin.py,sha256=q9fn3lfn0gviMfiimYij0wBCYww7FxyrOfGPr1NvntA,434
+django_qstash/results/apps.py,sha256=4me4cg5yeoeSJTphkHYzGMJUfGucT47FNIUMYu5gmIo,275
+django_qstash/results/models.py,sha256=aEiAhGJOuLRtjibUw6xdQqUt3eYKLqY2as4I4QSrF5U,1047
+django_qstash/results/services.py,sha256=HvNp5D1tQ__nz4LVUTAGxuyLl_dnlBps4pJ6E9HD2kA,991
+django_qstash/results/migrations/0001_initial.py,sha256=A90SKgWmBf4SIJYG1Jh6-b_81Ia1zIzGj3Bfl1O4-kg,1902
+django_qstash/results/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_qstash-0.0.4.dist-info/METADATA,sha256=D8RJT4Ivi3TlKjhD8hGw_YcLJvBo6r4XK6Vp7_pJ8e8,12307
+django_qstash-0.0.4.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+django_qstash-0.0.4.dist-info/top_level.txt,sha256=AlV3WSK1A0ZvKuCLsINtIJhJW8zo7SEB-D3_RAjZ0hI,14
+django_qstash-0.0.4.dist-info/RECORD,,

django_qstash-0.0.2.dist-info/METADATA

@@ -1,95 +0,0 @@
-Metadata-Version: 2.1
-Name: django-qstash
-Version: 0.0.2
-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
-Project-URL: Documentation, https://github.com/jmitchel3/django-qstash
-Project-URL: Funding, https://github.com/jmitchel3/django-qstash
-Project-URL: Repository, https://github.com/jmitchel3/django-qstash
-Classifier: Development Status :: 4 - Beta
-Classifier: Framework :: Django :: 4.2
-Classifier: Framework :: Django :: 5.0
-Classifier: Framework :: Django :: 5.1
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Natural Language :: English
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: django>=4.2
-Requires-Dist: qstash>=2
-Requires-Dist: requests>=2.30
-
-# Django QStash `pip install django-qstash`
-
-A drop-in replacement for Celery's shared_task leveraging Upstash QStash for a truly serverless Django application to run background tasks asynchronously from the request/response cycle.
-
-## Installation
-
-```bash
-pip install django-qstash
-```
-
-Depends on:
-
-- [Python 3.10+](https://www.python.org/)
-- [Django 5+](https://docs.djangoproject.com/)
-- [qstash-py](https://github.com/upstash/qstash-py)
-
-## Usage
-
-```python
-# from celery import shared_task
-from django_qstash import shared_task
-
-@shared_task
-def math_add_task(a, b, save_to_file=False):
-    logger.info(f"Adding {a} and {b}")
-    if save_to_file:
-        with open("math-add-result.txt", "w") as f:
-            f.write(f"{a} + {b} = {a + b}")
-    return a + b
-```
-
-```python
-math_add_task.apply_async(args=(12, 454), save_to_file=True)
-
-# or
-
-math_add_task.delay(12, 454, save_to_file=True)
-```
-
-
-## Configuration
-
-### Environment variables
-
-
-```python
-QSTASH_TOKEN="your_token"
-QSTASH_CURRENT_SIGNING_KEY="your_current_signing_key"
-QSTASH_NEXT_SIGNING_KEY="your_next_signing_key"
-
-# required for django-qstash
-DJANGO_QSTASH_DOMAIN="https://example.com"
-DJANGO_QSTASH_WEBHOOK_PATH="/qstash/webhook/"
-```
-
-
-
-`DJANGO_QSTASH_DOMAIN`: Must be a valid and publicly accessible domain. For example `https://djangoqstash.net`
-
-In development mode, we recommend using a tunnel like [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with a domain name you control. You can also consider [ngrok](https://ngrok.com/). 
-
-
-`DJANGO_QSTASH_WEBHOOK_PATH`: The path where QStash will send webhooks to your Django application. Defaults to `/qstash/webhook/`
-
-
-`DJANGO_QSTASH_FORCE_HTTPS`: Whether to force HTTPS for the webhook. Defaults to `True`.

django_qstash-0.0.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-django_qstash/__init__.py,sha256=s9YTqnhDQdkNv4B-ncx_Ci8Lpkim8vmzfhpL9keFVjM,117
-django_qstash/tasks.py,sha256=X2gFILRvUF2GFuwyAUT43Zvw7OsdFci7870VhRNQ5-M,4929
-django_qstash/utils.py,sha256=wrTU30cobO2di18BNEFtKD4ih2euf7eQNpg6p6TkQ1Y,1185
-django_qstash/views.py,sha256=ucxKQdBoz9Db_1wpuE3U0BBC4nPqtFv05Kb0wggrpOg,4270
-django_qstash-0.0.2.dist-info/METADATA,sha256=ZyBvj8g4G_XyONeA-lqI6p7cEOFBupE-L6JDpJU0x_A,3079
-django_qstash-0.0.2.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-django_qstash-0.0.2.dist-info/top_level.txt,sha256=AlV3WSK1A0ZvKuCLsINtIJhJW8zo7SEB-D3_RAjZ0hI,14
-django_qstash-0.0.2.dist-info/RECORD,,