django-qstash 0.0.10__tar.gz → 0.0.12__tar.gz

{django_qstash-0.0.10 → django_qstash-0.0.12}/PKG-INFO

@@ -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 → django_qstash-0.0.12}/README.md

@@ -4,16 +4,32 @@
 
 _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.
@@ -22,6 +38,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)
@@ -33,18 +50,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)
@@ -69,9 +90,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
 
@@ -115,7 +136,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
@@ -123,17 +144,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.
 
@@ -142,9 +176,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()`
@@ -177,10 +213,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
 
@@ -191,15 +228,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:
@@ -232,38 +277,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
 
@@ -283,8 +373,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.
 
@@ -292,9 +381,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
@@ -323,10 +409,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.
 
@@ -344,6 +431,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 → django_qstash-0.0.12}/pyproject.toml

@@ -6,7 +6,7 @@ requires = [
 
 [project]
 name = "django-qstash"
-version = "0.0.10"
+version = "0.0.12"
 description = "A drop-in replacement for Celery's shared_task with Upstash QStash."
 readme = "README.md"
 license = { file = "LICENSE" }

django_qstash-0.0.12/src/django_qstash/__init__.py

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

{django_qstash-0.0.10 → django_qstash-0.0.12}/src/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"]