django-qstash 0.0.10__py3-none-any.whl → 0.0.12__py3-none-any.whl

django_qstash/__init__.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
-__version__ = "0.0.10"
+__version__ = "0.0.12"
 
 from django_qstash.app import shared_task
+from django_qstash.app import stashed_task
 
-__all__ = ["shared_task"]
+__all__ = ["stashed_task", "shared_task"]

django_qstash/app/__init__.py

@@ -3,5 +3,6 @@ from __future__ import annotations
 from .base import AsyncResult
 from .base import QStashTask
 from .decorators import shared_task
+from .decorators import stashed_task
 
-__all__ = ["AsyncResult", "QStashTask", "shared_task"]
+__all__ = ["AsyncResult", "QStashTask", "stashed_task", "shared_task"]

django_qstash/app/decorators.py

@@ -6,24 +6,43 @@ from typing import Callable
 from django_qstash.app.base import QStashTask
 
 
-def shared_task(
+def stashed_task(
     func: Callable | None = None,
     name: str | None = None,
     deduplicated: bool = False,
     **options: dict[str, Any],
 ) -> QStashTask:
     """
-    Decorator that mimics Celery's shared_task
+    Decorator that mimics Celery's shared_task that maintains
+    Celery compatibility.
 
     Can be used as:
+
+        from django_qstash import shared_task
+
         @shared_task
         def my_task():
             pass
 
-        @shared_task(name="custom_name", deduplicated=True)
+        @stashed_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)
+
+
+def shared_task(func: Callable | None = None, **options: dict[str, Any]) -> QStashTask:
+    """
+    Decorator that is a drop-in replacement for Celery's shared_task.
+
+    Can be used as:
+
+        from django_qstash import shared_task
+
+        @shared_task
+        def my_task():
+            pass
+    """
+    return stashed_task(func, **options)

django_qstash/callbacks.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from django.core.exceptions import ImproperlyConfigured
+
 from django_qstash.settings import DJANGO_QSTASH_DOMAIN
 from django_qstash.settings import DJANGO_QSTASH_WEBHOOK_PATH
 
@@ -8,6 +10,10 @@ def get_callback_url() -> str:
     """
     Get the callback URL based on the settings.
     """
+    if DJANGO_QSTASH_DOMAIN is None:
+        raise ImproperlyConfigured("DJANGO_QSTASH_DOMAIN is not set")
+    if DJANGO_QSTASH_WEBHOOK_PATH is None:
+        raise ImproperlyConfigured("DJANGO_QSTASH_WEBHOOK_PATH is not set")
     callback_domain = DJANGO_QSTASH_DOMAIN.rstrip("/")
     if not callback_domain.startswith(("http://", "https://")):
         callback_domain = f"https://{callback_domain}"

django_qstash/cron.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import re
+
+minute_re = re.compile(
+    r"^\*$|^[0-5]?\d$|^[0-5]?\d-[0-5]?\d$|^[0-5]?\d(,[0-5]?\d)+$|^\*/([1-9]|[1-5][0-9])$"
+)
+
+hour_re = re.compile(
+    r"^\*$|^([01]?\d|2[0-3])$|^([01]?\d|2[0-3])-([01]?\d|2[0-3])$|^([01]?\d|2[0-3])(,([01]?\d|2[0-3]))+$|^\*/([1-9]|1[0-9]|2[0-3])$"
+)
+
+day_of_month_re = re.compile(
+    r"^\*$|^([1-2]?\d|3[01])$|^([1-2]?\d|3[01])-([1-2]?\d|3[01])$|^([1-2]?\d|3[01])(,([1-2]?\d|3[01]))+$|^\*/([1-9]|[12]\d|3[01])$"
+)
+
+month_re = re.compile(
+    r"^\*$|^([1-9]|1[0-2])$|^([1-9]|1[0-2])-([1-9]|1[0-2])$|^([1-9]|1[0-2])(,([1-9]|1[0-2]))+$|^\*/([1-9]|1[0-2])$"
+)
+
+day_of_week_re = re.compile(r"^\*$|^[0-6]$|^[0-6]-[0-6]$|^[0-6](,[0-6])+$|^\*/[1-6]$")

django_qstash/db/models.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from django.db import models
+
+
+class TaskStatus(models.TextChoices):
+    PENDING = "PENDING", "Pending"
+    SUCCESS = "SUCCESS", "Success"
+    EXECUTION_ERROR = "EXECUTION_ERROR", "Execution Error"
+    INTERNAL_ERROR = "INTERNAL_ERROR", "Internal Error"
+    OTHER_ERROR = "OTHER_ERROR", "Other Error"
+    UNKNOWN = "UNKNOWN", "Unknown"

django_qstash/handlers.py

@@ -9,6 +9,8 @@ from django.conf import settings
 from django.http import HttpRequest
 from qstash import Receiver
 
+from django_qstash.db.models import TaskStatus
+
 from . import utils
 from .exceptions import PayloadError
 from .exceptions import SignatureError
@@ -90,7 +92,9 @@ class QStashWebhook:
 
     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
+        payload = None
+        task_id = request.headers.get("Upstash-Message-Id")
+
         try:
             body = request.body.decode()
             self.verify_signature(
@@ -101,14 +105,14 @@ class QStashWebhook:
 
             payload = self.parse_payload(body)
             result = self.execute_task(payload)
-
             store_task_result(
-                task_id=request.headers.get("Upstash-Message-Id"),
+                task_id=task_id,
                 task_name=payload.task_name,
-                status="SUCCESS",
+                status=TaskStatus.SUCCESS,
                 result=result,
                 args=payload.args,
                 kwargs=payload.kwargs,
+                function_path=payload.function_path,
             )
 
             return {
@@ -125,16 +129,37 @@ class QStashWebhook:
                 "error": str(e),
                 "task_name": getattr(payload, "task_name", None),
             }, 400
+
         except TaskError as e:
             logger.exception("Task execution error: %s", str(e))
+            store_task_result(
+                task_id=task_id,
+                task_name=payload.task_name,
+                status=TaskStatus.EXECUTION_ERROR,
+                traceback=str(e),
+                args=payload.args,
+                kwargs=payload.kwargs,
+                function_path=payload.function_path,
+            )
             return {
                 "status": "error",
                 "error_type": e.__class__.__name__,
                 "error": str(e),
-                "task_name": payload.task_name if payload else None,
-            }, 500
+                "task_name": payload.task_name,
+            }, 422
+
         except Exception as e:
             logger.exception("Unexpected error in webhook handler: %s", str(e))
+            if payload:  # Store unexpected errors only if payload was parsed
+                store_task_result(
+                    task_id=task_id,
+                    task_name=payload.task_name,
+                    status=TaskStatus.INTERNAL_ERROR,
+                    traceback=str(e),
+                    args=payload.args,
+                    kwargs=payload.kwargs,
+                    function_path=payload.function_path,
+                )
             return {
                 "status": "error",
                 "error_type": "InternalServerError",

django_qstash/results/admin.py

@@ -17,5 +17,8 @@ class TaskResultAdmin(admin.ModelAdmin):
         "kwargs",
         "task_id",
         "date_created",
+        "function_path",
     ]
-    list_display = ["task_name", "status", "date_done"]
+    search_fields = ["task_name", "task_id", "function_path"]
+    list_display = ["task_name", "function_path", "status", "date_done"]
+    list_filter = ["status", "date_done"]

django_qstash/results/migrations/0002_taskresult_function_path_alter_taskresult_status_and_more.py

@@ -0,0 +1,46 @@
+# Generated by Django 5.1.4 on 2025-01-06 05:39
+
+from __future__ import annotations
+
+from django.db import migrations
+from django.db import models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("django_qstash_results", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="taskresult",
+            name="function_path",
+            field=models.TextField(blank=True, null=True),
+        ),
+        migrations.AlterField(
+            model_name="taskresult",
+            name="status",
+            field=models.CharField(
+                choices=[
+                    ("PENDING", "Pending"),
+                    ("SUCCESS", "Success"),
+                    ("EXECUTION_ERROR", "Execution Error"),
+                    ("INTERNAL_ERROR", "Internal Error"),
+                    ("OTHER_ERROR", "Other Error"),
+                    ("UNKNOWN", "Unknown"),
+                ],
+                default="PENDING",
+                max_length=50,
+            ),
+        ),
+        migrations.AlterField(
+            model_name="taskresult",
+            name="task_id",
+            field=models.CharField(db_index=True, max_length=255),
+        ),
+        migrations.AlterField(
+            model_name="taskresult",
+            name="traceback",
+            field=models.TextField(blank=True, null=True),
+        ),
+    ]

django_qstash/results/models.py

@@ -5,26 +5,25 @@ import uuid
 from django.db import models
 from django.utils import timezone
 
+from django_qstash.db.models import TaskStatus
+
 
 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_id = models.CharField(max_length=255, 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",
+        choices=TaskStatus.choices,
+        default=TaskStatus.PENDING,
     )
     date_created = models.DateTimeField(default=timezone.now)
     date_done = models.DateTimeField(null=True)
     result = models.JSONField(null=True)
-    traceback = models.TextField(null=True)
+    traceback = models.TextField(blank=True, null=True)
+    function_path = models.TextField(blank=True, null=True)
     args = models.JSONField(null=True)
     kwargs = models.JSONField(null=True)
 

django_qstash/results/services.py

@@ -1,17 +1,42 @@
 from __future__ import annotations
 
+import json
 import logging
+from typing import Any
 
 from django.apps import apps
 from django.utils import timezone
 
+from django_qstash.db.models import TaskStatus
+
 logger = logging.getLogger(__name__)
 
 
+def function_result_to_json(result: Any) -> str:
+    """Convert a function result to a JSON string"""
+    try:
+        data = {"result": result}
+        return json.dumps(data)
+    except Exception as e:
+        logger.exception("Failed to convert function result to JSON: %s", str(e))
+        return None
+
+
 def store_task_result(
-    task_id, task_name, status, result=None, traceback=None, args=None, kwargs=None
+    task_id,
+    task_name,
+    status,
+    result=None,
+    traceback=None,
+    args=None,
+    kwargs=None,
+    error=None,
+    function_path=None,
 ):
     """Helper function to store task results if the results app is installed"""
+    if status not in TaskStatus.values:
+        status = TaskStatus.UNKNOWN
+
     try:
         TaskResult = apps.get_model("django_qstash_results", "TaskResult")
         task_result = TaskResult.objects.create(
@@ -19,10 +44,11 @@ def store_task_result(
             task_name=task_name,
             status=status,
             date_done=timezone.now(),
-            result=result,
+            result=function_result_to_json(result),
             traceback=traceback,
             args=args,
             kwargs=kwargs,
+            function_path=function_path,
         )
         return task_result
     except LookupError:

django_qstash/results/tasks.py

@@ -7,16 +7,17 @@ from django.apps import apps
 from django.conf import settings
 from django.utils import timezone
 
-from django_qstash import shared_task
+from django_qstash import stashed_task
+from django_qstash.db.models import TaskStatus
 
 DJANGO_QSTASH_RESULT_TTL = getattr(settings, "DJANGO_QSTASH_RESULT_TTL", 604800)
 
 logger = logging.getLogger(__name__)
 
 
-@shared_task(name="Cleanup Task Results")
+@stashed_task(name="Cleanup Task Results")
 def clear_stale_results_task(
-    since=None, stdout=None, user_confirm=False, *args, **options
+    since=None, stdout=None, user_confirm=False, exclude_errors=True, *args, **options
 ):
     delta_seconds = since or DJANGO_QSTASH_RESULT_TTL
     cutoff_date = timezone.now() - timedelta(seconds=delta_seconds)
@@ -30,6 +31,14 @@ def clear_stale_results_task(
         logger.exception(msg)
         raise e
     qs_to_delete = TaskResult.objects.filter(date_done__lt=cutoff_date)
+    if exclude_errors:
+        qs_to_delete = qs_to_delete.exclude(
+            status__in=[
+                TaskStatus.EXECUTION_ERROR,
+                TaskStatus.INTERNAL_ERROR,
+                TaskStatus.OTHER_ERROR,
+            ]
+        )
 
     if user_confirm:
         user_input = input("Are you sure? (Y/n): ")
@@ -65,3 +74,12 @@ def clear_stale_results_task(
             stdout.write(msg)
         logger.exception(msg)
         raise e
+
+
+@stashed_task(name="Clear Task Error Results")
+def clear_task_errors_task(
+    since=None, stdout=None, user_confirm=False, *args, **options
+):
+    clear_stale_results_task(
+        since=since, stdout=stdout, user_confirm=user_confirm, exclude_errors=False
+    )

django_qstash/schedules/exceptions.py

@@ -7,3 +7,9 @@ class InvalidDurationStringValidationError(ValidationError):
     """Invalid duration string."""
 
     pass
+
+
+class InvalidCronStringValidationError(ValidationError):
+    """Invalid cron string."""
+
+    pass

django_qstash/schedules/forms.py

@@ -22,3 +22,10 @@ class TaskScheduleForm(forms.ModelForm):
             "retries",
             "timeout",
         ]
+
+    def clean(self):
+        cleaned_data = super().clean()
+        # If task_name is not provided, use the task value
+        if not cleaned_data.get("task_name") and cleaned_data.get("task"):
+            cleaned_data["task_name"] = cleaned_data["task"]
+        return cleaned_data

django_qstash/schedules/models.py

@@ -8,6 +8,7 @@ from django.db import models
 from django.utils import timezone
 
 from django_qstash.discovery.models import TaskField
+from django_qstash.schedules.validators import validate_cron_expression
 from django_qstash.schedules.validators import validate_duration_string
 
 DJANGO_QSTASH_DOMAIN = getattr(settings, "DJANGO_QSTASH_DOMAIN", None)
@@ -56,6 +57,7 @@ class TaskSchedule(models.Model):
     cron = models.CharField(
         max_length=255,
         default="*/5 * * * *",
+        validators=[validate_cron_expression],
         verbose_name="Cron Expression",
         help_text="Cron expression for scheduling the task",
     )

django_qstash/schedules/validators.py

@@ -2,6 +2,10 @@ from __future__ import annotations
 
 import re
 
+from django.utils.safestring import mark_safe
+
+from django_qstash import cron
+from django_qstash.schedules.exceptions import InvalidCronStringValidationError
 from django_qstash.schedules.exceptions import InvalidDurationStringValidationError
 
 
@@ -27,3 +31,39 @@ def validate_duration_string(value):
         raise InvalidDurationStringValidationError(
             "Duration too long. Maximum allowed: 7 days (equivalent to: 604800s, 10080m, 168h, 7d)"
         )
+
+
+def validate_cron_expression(value: str) -> None:
+    """Validates a standard cron expression with 5 fields (minute, hour, day of month, month, day of week)."""
+    parts = value.split()
+    if len(parts) != 5:
+        raise InvalidCronStringValidationError(
+            'Invalid cron format. Must contain 5 fields: "minute hour day_of_month month day_of_week"'
+        )
+
+    field_descriptions = {
+        "minute": "0-59",
+        "hour": "0-23",
+        "day_of_month": "1-31",
+        "month": "1-12",
+        "day_of_week": "0-6 (0=Sunday, 6=Saturday)",
+    }
+    field_label = {
+        "minute": "minute",
+        "hour": "hour",
+        "day_of_month": "day of the month",
+        "month": "month",
+        "day_of_week": "day of the week",
+    }
+    patterns = {
+        "minute": cron.minute_re,
+        "hour": cron.hour_re,
+        "day_of_month": cron.day_of_month_re,
+        "month": cron.month_re,
+        "day_of_week": cron.day_of_week_re,
+    }
+
+    for sub_value, (field, pattern) in zip(parts, patterns.items()):
+        if not re.match(pattern, sub_value):
+            invalid_msg = f"""<b>{sub_value}</b> is not a valid {field_label[field]}. <br/>Must be in range {field_descriptions[field]}. <br/><a target="_blank" href="https://crontab.guru/">crontab.guru</a> is also helpful."""
+            raise InvalidCronStringValidationError(mark_safe(invalid_msg))

{django_qstash-0.0.10.dist-info → django_qstash-0.0.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-qstash
-Version: 0.0.10
+Version: 0.0.12
 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
@@ -33,16 +33,32 @@ Requires-Dist: requests>=2.30
 
 _django-qstash_ is a drop-in replacement for Celery's `shared_task`.
 
-To do this, we use:
+
+## How it works
+
+In `tasks.py` in your apps:
+
+```python
+from django_qstash import shared_task
+
+
+@shared_task
+def my_task():
+    pass
+```
+> To use Celery too, you can use `@stashed_task` instead of `@shared_task` more below.
+
+To do this we need:
 
 - [Upstash QStash](https://upstash.com/docs/qstash/overall/getstarted)
-- A single public _webhook_ to call `@shared_task` functions automatically
+- A single public _webhook_ to call `@stashed_task` functions automatically
 
 This allows us to:
 
+- Nearly identical usage to Celery's `@shared_task` with far less configuration and overhead
 - Focus just on Django
-- Drop Celery
-- Truly scale Django to zero
+- Drop Celery completely, scale it down, or use it as normal. django-qstash can work hand-in-hand with Celery
+- Unlock true serverless and scale-to-zero for Django
 - 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.
@@ -51,6 +67,7 @@ This allows us to:
 ## Table of Contents
 
 - [django-qstash](#django-qstash)
+  - [How it works](#how-it-works)
   - [Table of Contents](#table-of-contents)
   - [Installation](#installation)
     - [Using Pip](#using-pip)
@@ -62,18 +79,22 @@ This allows us to:
   - [Usage](#usage)
     - [Define a Task](#define-a-task)
     - [Regular Task Call](#regular-task-call)
-    - [Async Task](#async-task)
+    - [Background Task](#background-task)
       - [`.delay()`](#delay)
       - [`.apply_async()`](#apply_async)
       - [`.apply_async()` With Time Delay](#apply_async-with-time-delay)
-    - [JSON-ready Arguments](#json-ready-arguments)
+    - [Arguments Must be JSON-ready](#arguments-must-be-json-ready)
     - [Example Task](#example-task)
   - [Management Commands](#management-commands)
-  - [Development Usage](#development-usage)
+  - [Public Domain In Development](#public-domain-in-development)
   - [Django Settings Configuration](#django-settings-configuration)
+    - [`DJANGO_QSTASH_DOMAIN`](#django_qstash_domain)
+    - [`DJANGO_QSTASH_WEBHOOK_PATH`](#django_qstash_webhook_path)
+    - [`DJANGO_QSTASH_FORCE_HTTPS`](#django_qstash_force_https)
+    - [Example Django Settings](#example-django-settings)
   - [Schedule Tasks (Optional)](#schedule-tasks-optional)
     - [Installation](#installation-1)
-  - [Schedule a Task](#schedule-a-task)
+    - [Schedule a Task](#schedule-a-task)
   - [Store Task Results (Optional)](#store-task-results-optional)
     - [Clear Stale Results](#clear-stale-results)
   - [Definitions](#definitions)
@@ -98,9 +119,9 @@ INSTALLED_APPS = [
     ##...
 ]
 ```
-- `django_qstash` Includes the `@shared_task` decorator and webhook view
+- `django_qstash` Includes the `@shared_task` and `@stashed_task` decorators and webhook view
 - `django_qstash.results` (Optional): Store task results in Django DB
-- `django_qstash.schedules` (Optional): Use QStash Schedules to run your `django_qstash` tasks. Out of the box support for _django_qstash_ `@shared_task`. Schedule tasks using _cron_ (e.g. `0 0 * * *`) format which is required based on [QStash Schedules](https://upstash.com/docs/qstash/features/schedules). use [contrab.guru](https://crontab.guru/) for writing the cron format.
+- `django_qstash.schedules` (Optional): Use QStash Schedules to run your `django_qstash` tasks. Out of the box support for _django_qstash_ `@stashed_task`. Schedule tasks using _cron_ (e.g. `0 0 * * *`) format which is required based on [QStash Schedules](https://upstash.com/docs/qstash/features/schedules). use [contrab.guru](https://crontab.guru/) for writing the cron format.
 
 ### Configure Webhook URL
 
@@ -144,7 +165,7 @@ There is a sample project in [sample_project/](sample_project/) that shows how a
 
 ## Usage
 
-Django-QStash revolves around the `shared_task` decorator. The goal is to be a drop-in replacement for Celery's `shared_task` decorator.
+Django-QStash revolves around the `stashed_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
@@ -152,17 +173,30 @@ Here's how it works:
 
 ### Define a Task
 ```python
+# from celery import shared_task
 from django_qstash import shared_task
+from django_qstash import stashed_task
 
 
-@shared_task
+@stashed_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.")
+
+
+@shared_task
+def hello_world_redux(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.")
 ```
 
+- `hello_world` and `hello_world_redux` work the same with django-qstash.
+- If you use Celery's `@shared_task` instead, Celery would handle only `hello_world_redux` and django-qstash would handle only `hello_world`.
+
 ### Regular Task Call
 Nothing special here. Just call the function like any other to verify it works.
 
@@ -171,9 +205,11 @@ Nothing special here. Just call the function like any other to verify it works.
 hello_world("Tony Stark", age=40, activity="building in a cave with a box of scraps.")
 ```
 
-### Async Task
+### Background 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.
+Using `.delay()` or `.apply_async()` is how you trigger a background task. These background tasks are actually setting up a QStash message that will be delivered via webhook to your Django application. django-qstash handles the webhook and the message delivery assuming installed correctly.
+
+This functionality is modeled after Celery and it works as you'd expect.
 
 
 #### `.delay()`
@@ -206,10 +242,11 @@ hello_world.apply_async(
 )
 ```
 
-### JSON-ready Arguments
+### Arguments Must be JSON-ready
 
-Each argument needs to be _JSON_ serializable. The way you find out:
+Arguments to django-qstash managed functions must be _JSON_ serializable.
 
+The way you find out:
 ```python
 import json
 
@@ -220,15 +257,23 @@ data = {
 print(json.dumps(data))
 # no errors, you're good to go.
 ```
+If you have `errors` you'll need to fix them. Here's a few common errors you might see:
+
+- Using a Django queryset directly as an argument
+- Using a Django model instance directly as an argument
+- Using a datetime object directly as an argument (e.g. `datetime.datetime` or `datetime.date`) instead of a timestamp or date string (e.g. `datetime.datetime.now().timestamp()` or `datetime.datetime.now.strftime("%Y-%m-%d")`)
 
 ### Example Task
 
 ```python
 # from celery import shared_task
-from django_qstash import shared_task
+# becomes
+# from django_qstash import shared_task
+# or
+from django_qstash import stashed_task
 
 
-@shared_task
+@stashed_task
 def math_add_task(a, b, save_to_file=False, *args, **kwargs):
     logger.info(f"Adding {a} and {b}")
     if save_to_file:
@@ -261,38 +306,83 @@ The `.delay()` method does not support a countdown parameter because it simply p
 
 ## Management Commands
 
-- `python manage.py available_tasks` to view all available tasks
+- `python manage.py available_tasks` to view all available tasks found by django-qstash. Unlike Celery, django-qstash does not assign tasks to a specific Celery app (e.g. `app = Celery()`).
 
 _Requires `django_qstash.schedules` installed._
 - `python manage.py task_schedules --list` see all schedules relate to the `DJANGO_QSTASH_DOMAIN`
 - `python manage.py task_schedules --sync` sync schedules based on the `DJANGO_QSTASH_DOMAIN` to store in the Django Admin.
 
-## Development Usage
+## Public Domain In Development
 
-django-qstash requires a public domain to work (e.g. `https://djangoqstash.com`). There are many ways to do this, we recommend:
+django-qstash _requires_ a publicly accessible domain to work (e.g. `https://djangoqstash.com`). There are many ways to do this, we recommend:
 
 - [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with a domain name you control.
 - [ngrok](https://ngrok.com/)
 
 Once you have a domain name, you can configure the `DJANGO_QSTASH_DOMAIN` setting in your Django settings.
 
-
 ## Django Settings Configuration
 
-In Django settings, you can configure the following:
+Various options are available to configure django-qstash.
 
-- `DJANGO_QSTASH_DOMAIN`: Must be a valid and publicly accessible domain. For example `https://djangoqstash.com`. Review [Development usage](#development-usage) for setting up a domain name during development.
+### `DJANGO_QSTASH_DOMAIN`
+- Required: Yes
+- Default:`None`
+- Description: Must be a valid and publicly accessible domain. For example `https://djangoqstash.com`. Review [Development usage](#development-usage) for setting up a domain name during development.
 
-- `DJANGO_QSTASH_WEBHOOK_PATH` (default:`/qstash/webhook/`): The path where QStash will send webhooks to your Django application.
+### `DJANGO_QSTASH_WEBHOOK_PATH`
+- Required: Yes
+- Default:`/qstash/webhook/`
+- Description: 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_FORCE_HTTPS`
+- Required: No
+- Default: `True`
+- Description: 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).
+###`DJANGO_QSTASH_RESULT_TTL`
+- Required: No
+- Default:`604800`
+- Description: A number of seconds after which task result data can be safely deleted. Defaults to 604800 seconds (7 days or 7 * 24 * 60 * 60).
+
+
+### Example Django Settings
+
+For a complete example, review [sample_project/settings.py](sample_project/settings.py) where [python-decouple](https://github.com/henriquebastos/python-decouple) is used to set the environment variables via the `.env` file or system environment variables (for production use).
+
+Using `os.environ`:
+```python
+import os
+
+###########################
+# django settings
+###########################
+DJANGO_DEBUG = str(os.environ.get("DJANGO_DEBUG")) == "1"
+DJANGO_SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY")
+ALLOWED_HOSTS = [os.environ.get("ALLOWED_HOST")]
+CSRF_TRUSTED_ORIGINS = [os.environ.get("CSRF_TRUSTED_ORIGIN")]
+###########################
+# qstash-py settings
+###########################
+QSTASH_TOKEN = os.environ.get("QSTASH_TOKEN")
+QSTASH_CURRENT_SIGNING_KEY = os.environ.get("QSTASH_CURRENT_SIGNING_KEY")
+QSTASH_NEXT_SIGNING_KEY = os.environ.get("QSTASH_NEXT_SIGNING_KEY")
+
+###########################
+# django_qstash settings
+###########################
+DJANGO_QSTASH_DOMAIN = os.environ.get("DJANGO_QSTASH_DOMAIN")
+DJANGO_QSTASH_WEBHOOK_PATH = os.environ.get("DJANGO_QSTASH_WEBHOOK_PATH")
+DJANGO_QSTASH_FORCE_HTTPS = True
+DJANGO_QSTASH_RESULT_TTL = 604800
+```
 
 
 ## Schedule Tasks (Optional)
 
-The `django_qstash.schedules` app schedules tasks using Upstash [QStash Schedules](https://upstash.com/docs/qstash/features/schedules) and the django-qstash `@shared_task` decorator.
+Run background tasks on a CRON schedule.
+
+The `django_qstash.schedules` app schedules tasks using Upstash [QStash Schedules](https://upstash.com/docs/qstash/features/schedules) via `@shared_task` or `@stashed_task` decorators along with the `TaskSchedule` model.
 
 ### Installation
 
@@ -312,8 +402,7 @@ Run migrations:
 python manage.py migrate django_qstash_schedules
 ```
 
-
-## Schedule a Task
+### Schedule a Task
 
 Tasks must exist before you can schedule them. Review [Define a Task](#define-a-task) for more information.
 
@@ -321,9 +410,6 @@ Here's how you can schedule a task:
 - Django Admin (`/admin/django_qstash_schedules/taskschedule/add/`)
 - Django shell (`python manage.py shell`)
 
-
-
-
 ```python
 from django_qstash.schedules.models import TaskSchedule
 from django_qstash.discovery.utils import discover_tasks
@@ -352,10 +438,11 @@ TaskSchedule.objects.create(
 - `cron` is the cron schedule to run the task. Use [contrab.guru](https://crontab.guru/) for writing the cron format.
 
 
-
 ## Store 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.
+Retain the results of background tasks in the database with clear-out functionality.
+
+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 the django-qstash webhook view handler (`qstash_webhook_view`).
 
 To install it, just add `django_qstash.results` to your `INSTALLED_APPS` setting.
 
@@ -373,6 +460,12 @@ Run migrations:
 python manage.py migrate django_qstash_results
 ```
 
+Key configuration:
+
+- [DJANGO_QSTASH_WEBHOOK_PATH](#django-settings-configuration)
+- [DJANGO_QSTASH_DOMAIN](#django-settings-configuration)
+- [DJANGO_QSTASH_RESULT_TTL](#django-settings-configuration)
+
 ### Clear Stale Results
 
 We recommend purging the `TaskResult` model after a certain amount of time.

{django_qstash-0.0.10.dist-info → django_qstash-0.0.12.dist-info}/RECORD

@@ -1,14 +1,17 @@
-django_qstash/__init__.py,sha256=LX7-S0Qx-tBkMzcbIy-Fv4WyLP_wY0GnNsO2YG1bJoA,129
-django_qstash/callbacks.py,sha256=VG5tGdNzAmUEh7NlpghrxhWvnpRNXZucWmWwxaemw0M,530
+django_qstash/__init__.py,sha256=ENXrTf63lzkaRO580z6PPjYDS7bgC2bNaK24S-uqnbo,188
+django_qstash/callbacks.py,sha256=IQ-D8sPlSRuREZ1zwkRyd2GtxfmrJJh2x4jLd39rZCE,813
 django_qstash/client.py,sha256=cgHf-g6lDAltY_Vt6GUVJNY2JSz1czBOHL-WVkkLs2M,149
+django_qstash/cron.py,sha256=13OzTMGXFgjNEXjs2Et20WGZYtW9lKlu79BjbRySnVc,716
 django_qstash/exceptions.py,sha256=pH6kKRJFIVFkDHUJQ9yRWmtGdBBSXpNAwMSFuNzMgPw,392
-django_qstash/handlers.py,sha256=mmm8TJOqV3j1rQXooNOa128gtmALXFNCAaDZ5xwIcuw,4950
+django_qstash/handlers.py,sha256=TtYZ-Sr858ajISBpDuHIT7-qaVsoVfTE6vVFJ9-kpPE,5820
 django_qstash/settings.py,sha256=YvpXMo1AdIWvbotISWJmhg0vrW3A3UQ4BieNzMfRC7Y,524
 django_qstash/utils.py,sha256=wrTU30cobO2di18BNEFtKD4ih2euf7eQNpg6p6TkQ1Y,1185
 django_qstash/views.py,sha256=H32f_jGnlwOTO0YG9znNo2b-GRYZ8TM-Wt0T62SGdXM,639
-django_qstash/app/__init__.py,sha256=353w1JyvIinkr3aHjyT7I01utFM56lrgIjSSfqtJkA4,187
+django_qstash/app/__init__.py,sha256=kmoCVoESInzCZ_oGUiPVY4GsFQwBC07cqFJCyn9Loyk,240
 django_qstash/app/base.py,sha256=gM7GIJh_omZcxbmsrwAEadA-N6EuUJbPzh0CflOIVRg,3864
-django_qstash/app/decorators.py,sha256=Gn0TAxUHfS4fKUdKdArvHeWlxrRvj9_NOVnC1a6pGTQ,732
+django_qstash/app/decorators.py,sha256=Zkr0dLhW5-7yGmj7JunLGcgzOwsONRyz3YkrD957DqY,1170
+django_qstash/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_qstash/db/models.py,sha256=UTmjw76h49HT4hPKaCwnOkHph70GOJ6mMDZt8aKmHH8,372
 django_qstash/discovery/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 django_qstash/discovery/fields.py,sha256=h-31sysbIU05KGKGBAu7uQo9bZnZg3kgjN_ZhPPMTGU,1260
 django_qstash/discovery/models.py,sha256=9ml9lTKEqEKx2uqYvejZw_BjdnowgFOPE7rYNt_8E9A,685
@@ -20,27 +23,28 @@ django_qstash/management/commands/available_tasks.py,sha256=l-do7Mry83NxbCdyMLcL
 django_qstash/management/commands/clear_stale_results.py,sha256=mxXXqIy6pnvsN8JVE0xe3mypqtkaZbpqdBjpox-MDik,1402
 django_qstash/management/commands/task_schedules.py,sha256=b9lJ1vjQKHyGzWAo9csGwE_oaKfgcSC8bPFLt9Ry6WE,4278
 django_qstash/results/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-django_qstash/results/admin.py,sha256=q9fn3lfn0gviMfiimYij0wBCYww7FxyrOfGPr1NvntA,434
+django_qstash/results/admin.py,sha256=Vr1O6E7vucSnkZ1PwHQ7RYkwOxiX4WHPAKaA7L8Cn-4,580
 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/tasks.py,sha256=NETuiREwCKfajWKCnnB5iAsHoSsvBIThf805_wpzjbw,2166
+django_qstash/results/models.py,sha256=AV7-nVEMq-Xt2QVY6D7NQc4_3E7v-6NA2xngTU8DfXA,1062
+django_qstash/results/services.py,sha256=vax0nsH9VO8nWTbS1Ki762-w-15ADeWSN6Sohpx7Dlg,1590
+django_qstash/results/tasks.py,sha256=kd49OOZyOg6OG3RSyywtZPtpGaPlycY2OXl1BXaoxVM,2746
 django_qstash/results/migrations/0001_initial.py,sha256=A90SKgWmBf4SIJYG1Jh6-b_81Ia1zIzGj3Bfl1O4-kg,1902
+django_qstash/results/migrations/0002_taskresult_function_path_alter_taskresult_status_and_more.py,sha256=FevtPlzkKHjRD1tcnXskigY5jr2X3gYv7KE2TcdEAxU,1374
 django_qstash/results/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 django_qstash/schedules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 django_qstash/schedules/admin.py,sha256=ToFkdGfN3smNctTduLQpwxZ5yW20jW4HKRr7x1UilIk,1673
 django_qstash/schedules/apps.py,sha256=zTyTH6xTZPKsEC2MlJcQBDp2ZiRWdMfq2j2jGbpBLH0,360
-django_qstash/schedules/exceptions.py,sha256=fvXArrK24ZBGITijuJ_I5xixURmFrJpQ6Dbi2bLNqCQ,195
+django_qstash/schedules/exceptions.py,sha256=lrX8kKF5H93FIQNaeZR9mlJBEEmtta6T69CevoYk_xA,295
 django_qstash/schedules/formatters.py,sha256=KMt1457z4Mp0Mob2IxgTBHmye_mRfcLn7Rdf7ThvbEg,1157
-django_qstash/schedules/forms.py,sha256=S5Wy2mZha2-th4oAQLjkC9JytfXFNJcL1j18u6rslxI,524
-django_qstash/schedules/models.py,sha256=WS4b5ssh07ekiTe5_y4phLKGl7uTXHJBiF4W47vkGec,4357
+django_qstash/schedules/forms.py,sha256=A0TW5xM73Kp7gzieprqaf7leQlqMB7NZFsNn3r_7Jp4,808
+django_qstash/schedules/models.py,sha256=ZcwuIZAn9jC8ZQDfqKTYGjo1C-0WfKf4Mddp_EfoBU4,4476
 django_qstash/schedules/services.py,sha256=U3c2cZgdKGWgpmhRD0j0wT_T43w7K4pXm552M2sTr_4,2186
 django_qstash/schedules/signals.py,sha256=g1aRAbZx-stnvD589mZagR6I27E56064fUyWsxKitR4,696
-django_qstash/schedules/validators.py,sha256=i8IEjnRVk-iysmqvT_kbPYpxTKCQWoX9P1JHcL3zkhI,925
+django_qstash/schedules/validators.py,sha256=w1dLgf_rAujurcktGPgu1aXejT5BhH5ianKSr7cEYKU,2467
 django_qstash/schedules/migrations/0001_initial.py,sha256=66cA8xnJV3h7QgzCaOiv-Nu3Xl9IdZQPgQKhxyW3bs4,4516
 django_qstash/schedules/migrations/0002_taskschedule_updated_at.py,sha256=6hZO0a9P2ZpOROkk7O5UXBhahghU0QfxZl4E-c3HKGw,459
 django_qstash/schedules/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-django_qstash-0.0.10.dist-info/METADATA,sha256=MBBDbS-vk7yxaIa4XKKj4GHAO2xWVNIzg3s63PKoggk,15412
-django_qstash-0.0.10.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-django_qstash-0.0.10.dist-info/top_level.txt,sha256=AlV3WSK1A0ZvKuCLsINtIJhJW8zo7SEB-D3_RAjZ0hI,14
-django_qstash-0.0.10.dist-info/RECORD,,
+django_qstash-0.0.12.dist-info/METADATA,sha256=NIxqfsPXtnoculriqbmMK9d_4PkFwvX-D2ey4U43hY0,19422
+django_qstash-0.0.12.dist-info/WHEEL,sha256=A3WOREP4zgxI0fKrHUG8DC8013e3dK3n7a6HDbcEIwE,91
+django_qstash-0.0.12.dist-info/top_level.txt,sha256=AlV3WSK1A0ZvKuCLsINtIJhJW8zo7SEB-D3_RAjZ0hI,14
+django_qstash-0.0.12.dist-info/RECORD,,

{django_qstash-0.0.10.dist-info → django_qstash-0.0.12.dist-info}/WHEEL

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