django-qstash 0.0.1__py3-none-any.whl

django_qstash/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.0"
+
+from .tasks import shared_task
+
+__all__ = ["shared_task"]

django_qstash/tasks.py

@@ -0,0 +1,151 @@
+import functools
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from qstash import QStash
+
+QSTASH_TOKEN = getattr(settings, "QSTASH_TOKEN", None)
+DJANGO_QSTASH_DOMAIN = getattr(settings, "DJANGO_QSTASH_DOMAIN", None)
+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")
+
+# Initialize QStash client once
+qstash_client = QStash(QSTASH_TOKEN)
+
+
+class QStashTask:
+    def __init__(
+        self,
+        func: Optional[Callable] = None,
+        name: Optional[str] = None,
+        delay_seconds: Optional[int] = None,
+        deduplicated: bool = False,
+        **options: Dict[str, Any],
+    ):
+        self.func = func
+        self.name = name or (func.__name__ if func else None)
+        self.delay_seconds = delay_seconds
+        self.deduplicated = deduplicated
+        self.options = options
+        self.callback_domain = DJANGO_QSTASH_DOMAIN.rstrip("/")
+        self.webhook_path = DJANGO_QSTASH_WEBHOOK_PATH.strip("/")
+
+        if func is not None:
+            functools.update_wrapper(self, func)
+
+    def __get__(self, obj, objtype):
+        """Support for instance methods"""
+        return functools.partial(self.__call__, obj)
+
+    def __call__(self, *args, **kwargs):
+        """
+        Execute the task, either directly or via QStash based on context
+        """
+        # Handle the case when the decorator is used without parameters
+        if self.func is None:
+            return self.__class__(
+                args[0],
+                name=self.name,
+                delay_seconds=self.delay_seconds,
+                deduplicated=self.deduplicated,
+                **self.options,
+            )
+
+        # If called directly (not through delay/apply_async), execute the function
+        if not getattr(self, "_is_delayed", False):
+            return self.func(*args, **kwargs)
+
+        # Reset the delayed flag
+        self._is_delayed = False
+
+        # Prepare the payload
+        payload = {
+            "function": self.func.__name__,
+            "module": self.func.__module__,
+            "args": args,  # Send args as-is
+            "kwargs": kwargs,
+            "task_name": self.name,
+            "options": self.options,
+        }
+
+        # Ensure callback URL is properly formatted
+        callback_domain = self.callback_domain
+        if not callback_domain.startswith(("http://", "https://")):
+            callback_domain = f"https://{callback_domain}"
+
+        url = f"{callback_domain}/{self.webhook_path}/"
+        # Send to QStash using the official SDK
+        response = qstash_client.message.publish_json(
+            url=url,
+            body=payload,
+            delay=f"{self.delay_seconds}s" if self.delay_seconds else None,
+            retries=self.options.get("max_retries", 3),
+            content_based_deduplication=self.deduplicated,
+        )
+        # Return an AsyncResult-like object for Celery compatibility
+        return AsyncResult(response.message_id)
+
+    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":
+        """Celery-compatible apply_async() method"""
+        self._is_delayed = True
+        if countdown is not None:
+            self.delay_seconds = countdown
+        self.options.update(options)
+
+        # Fix: Ensure we're passing the arguments correctly
+        args = args or ()
+        kwargs = kwargs or {}
+        return self(*args, **kwargs)
+
+
+class AsyncResult:
+    """Minimal Celery AsyncResult-compatible class"""
+
+    def __init__(self, task_id: str):
+        self.task_id = task_id
+
+    def get(self, timeout: Optional[int] = None) -> Any:
+        """Simulate Celery's get() method"""
+        raise NotImplementedError("QStash doesn't support result retrieval")
+
+    @property
+    def id(self) -> str:
+        return self.task_id
+
+
+def shared_task(
+    func: Optional[Callable] = None,
+    name: Optional[str] = None,
+    deduplicated: bool = False,
+    **options: Dict[str, Any],
+) -> QStashTask:
+    """
+    Decorator that mimics Celery's shared_task
+
+    Can be used as:
+        @shared_task
+        def my_task():
+            pass
+
+        @shared_task(name="custom_name", deduplicated=True)
+        def my_task():
+            pass
+    """
+    if func is not None:
+        return QStashTask(func, name=name, deduplicated=deduplicated, **options)
+    return lambda f: QStashTask(f, name=name, deduplicated=deduplicated, **options)

django_qstash/utils.py

@@ -0,0 +1,37 @@
+import importlib
+import logging
+from typing import Any, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+def import_string(import_path: str) -> Any:
+    """
+    Import a module path and return the attribute/class designated by the last name.
+
+    Example:
+        import_string('myapp.tasks.mytask') -> mytask function
+    """
+    try:
+        module_path, class_name = import_path.rsplit(".", 1)
+        module = importlib.import_module(module_path)
+        return getattr(module, class_name)
+    except (ImportError, AttributeError) as e:
+        raise ImportError(f"Could not import '{import_path}': {e}")
+
+
+def validate_task_payload(payload: dict) -> Tuple[bool, str]:
+    """Validate the task payload has all required fields"""
+    required_fields = {"function", "module", "args", "kwargs"}
+    missing_fields = required_fields - set(payload.keys())
+
+    if missing_fields:
+        return False, f"Missing required fields: {', '.join(missing_fields)}"
+
+    if not isinstance(payload["args"], (list, tuple)):
+        return False, "Args must be a list or tuple"
+
+    if not isinstance(payload["kwargs"], dict):
+        return False, "Kwargs must be a dictionary"
+
+    return True, ""

django_qstash/views.py

@@ -0,0 +1,124 @@
+import json
+import logging
+
+from django.conf import settings
+from django.http import (
+    HttpRequest,
+    HttpResponse,
+    HttpResponseBadRequest,
+    HttpResponseForbidden,
+)
+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,
+)
+
+
+@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",
+        )

django_qstash-0.0.1.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.1
+Name: django-qstash
+Version: 0.0.1
+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.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+django_qstash/__init__.py,sha256=HvBJshBllZs_V6B2p1DtRYkcU1CiDglPlk43V8MYleI,81
+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.1.dist-info/METADATA,sha256=QZayHLC5YDuYHMFtMbmBdx8ZTllFhnXk8F2xAxGWcpI,3079
+django_qstash-0.0.1.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+django_qstash-0.0.1.dist-info/top_level.txt,sha256=AlV3WSK1A0ZvKuCLsINtIJhJW8zo7SEB-D3_RAjZ0hI,14
+django_qstash-0.0.1.dist-info/RECORD,,

django_qstash-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.6.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_qstash-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+django_qstash