django-qstash 0.0.9__tar.gz → 0.0.11__tar.gz

{django_qstash-0.0.9 → django_qstash-0.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-qstash
-Version: 0.0.9
+Version: 0.0.11
 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)
@@ -68,8 +85,13 @@ This allows us to:
       - [`.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)
+  - [Management Commands](#management-commands)
+  - [Development Usage](#development-usage)
+  - [Django Settings Configuration](#django-settings-configuration)
+  - [Schedule Tasks (Optional)](#schedule-tasks-optional)
+    - [Installation](#installation-1)
+  - [Schedule a Task](#schedule-a-task)
+  - [Store Task Results (Optional)](#store-task-results-optional)
     - [Clear Stale Results](#clear-stale-results)
   - [Definitions](#definitions)
   - [Motivation](#motivation)
@@ -89,12 +111,13 @@ INSTALLED_APPS = [
     ##...
     "django_qstash",
     "django_qstash.results",
+    "django_qstash.schedules",
     ##...
 ]
 ```
-- `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_ `@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
 
@@ -138,7 +161,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 `stashed_task` decorator.
 
 Here's how it works:
 - Define a Task
@@ -146,10 +169,10 @@ Here's how it works:
 
 ### Define a Task
 ```python
-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}.")
@@ -157,7 +180,6 @@ def hello_world(name: str, age: int = None, activity: str = None):
     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.
 
@@ -220,10 +242,13 @@ print(json.dumps(data))
 
 ```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:
@@ -254,22 +279,101 @@ math_add_task.apply_async(
 The `.delay()` method does not support a countdown parameter because it simply passes the arguments (*args, **kwargs) to the `apply_async()` method.
 
 
-## Configuration
+## Management Commands
+
+- `python manage.py available_tasks` to view all available tasks
+
+_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
+
+django-qstash requires a public 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:
 
-`DJANGO_QSTASH_DOMAIN`: Must be a valid and publicly accessible domain. For example `https://djangoqstash.com`
+- `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_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.
 
-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_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_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.
+## Schedule Tasks (Optional)
 
-`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).
+The `django_qstash.schedules` app schedules tasks using Upstash [QStash Schedules](https://upstash.com/docs/qstash/features/schedules) and the django-qstash `@stashed_task` decorator.
 
+### Installation
 
-## Storing Task Results (Optional)
+Update your `INSTALLED_APPS` setting to include `django_qstash.schedules`.
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_qstash",  # required
+    "django_qstash.schedules",
+    # ...
+]
+```
+
+Run migrations:
+```bash
+python manage.py migrate django_qstash_schedules
+```
+
+
+## Schedule a Task
+
+Tasks must exist before you can schedule them. Review [Define a Task](#define-a-task) for more information.
+
+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
+
+all_available_tasks = discover_tasks(paths_only=True)
+
+desired_task = "django_qstash.results.clear_stale_results_task"
+# or desired_task = "example_app.tasks.my_task"
+
+task_to_use = desired_task
+if desired_task not in available_task_locations:
+    task_to_use = available_task_locations[0]
+
+print(f"Using task: {task_to_use}")
+
+TaskSchedule.objects.create(
+    name="My Schedule",
+    cron="0 0 * * *",
+    task_name=task_to_use,
+    args=["arg1", "arg2"],
+    kwargs={"kwarg1": "value1", "kwarg2": "value2"},
+)
+```
+- `django_qstash.results.clear_stale_results_task` is a built-in task that `django_qstash.results` provides
+- `args` and `kwargs` are the arguments to pass to the task
+- `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.
 
@@ -278,6 +382,7 @@ To install it, just add `django_qstash.results` to your `INSTALLED_APPS` setting
 ```python
 INSTALLED_APPS = [
     # ...
+    "django_qstash",
     "django_qstash.results",
     # ...
 ]
@@ -285,14 +390,14 @@ INSTALLED_APPS = [
 
 Run migrations:
 ```bash
-python manage.py migrate
+python manage.py migrate django_qstash_results
 ```
 
 ### Clear Stale Results
 
 We recommend purging the `TaskResult` model after a certain amount of time.
 ```bash
-python manage.py clear_stale_results
+python manage.py clear_stale_results --since 604800
 ```
 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).

{django_qstash-0.0.9 → django_qstash-0.0.11}/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)
@@ -39,8 +56,13 @@ This allows us to:
       - [`.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)
+  - [Management Commands](#management-commands)
+  - [Development Usage](#development-usage)
+  - [Django Settings Configuration](#django-settings-configuration)
+  - [Schedule Tasks (Optional)](#schedule-tasks-optional)
+    - [Installation](#installation-1)
+  - [Schedule a Task](#schedule-a-task)
+  - [Store Task Results (Optional)](#store-task-results-optional)
     - [Clear Stale Results](#clear-stale-results)
   - [Definitions](#definitions)
   - [Motivation](#motivation)
@@ -60,12 +82,13 @@ INSTALLED_APPS = [
     ##...
     "django_qstash",
     "django_qstash.results",
+    "django_qstash.schedules",
     ##...
 ]
 ```
-- `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_ `@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
 
@@ -109,7 +132,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 `stashed_task` decorator.
 
 Here's how it works:
 - Define a Task
@@ -117,10 +140,10 @@ Here's how it works:
 
 ### Define a Task
 ```python
-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}.")
@@ -128,7 +151,6 @@ def hello_world(name: str, age: int = None, activity: str = None):
     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.
 
@@ -191,10 +213,13 @@ print(json.dumps(data))
 
 ```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:
@@ -225,22 +250,101 @@ math_add_task.apply_async(
 The `.delay()` method does not support a countdown parameter because it simply passes the arguments (*args, **kwargs) to the `apply_async()` method.
 
 
-## Configuration
+## Management Commands
+
+- `python manage.py available_tasks` to view all available tasks
+
+_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
+
+django-qstash requires a public 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:
 
-`DJANGO_QSTASH_DOMAIN`: Must be a valid and publicly accessible domain. For example `https://djangoqstash.com`
+- `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_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.
 
-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_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_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.
+## Schedule Tasks (Optional)
 
-`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).
+The `django_qstash.schedules` app schedules tasks using Upstash [QStash Schedules](https://upstash.com/docs/qstash/features/schedules) and the django-qstash `@stashed_task` decorator.
 
+### Installation
 
-## Storing Task Results (Optional)
+Update your `INSTALLED_APPS` setting to include `django_qstash.schedules`.
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_qstash",  # required
+    "django_qstash.schedules",
+    # ...
+]
+```
+
+Run migrations:
+```bash
+python manage.py migrate django_qstash_schedules
+```
+
+
+## Schedule a Task
+
+Tasks must exist before you can schedule them. Review [Define a Task](#define-a-task) for more information.
+
+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
+
+all_available_tasks = discover_tasks(paths_only=True)
+
+desired_task = "django_qstash.results.clear_stale_results_task"
+# or desired_task = "example_app.tasks.my_task"
+
+task_to_use = desired_task
+if desired_task not in available_task_locations:
+    task_to_use = available_task_locations[0]
+
+print(f"Using task: {task_to_use}")
+
+TaskSchedule.objects.create(
+    name="My Schedule",
+    cron="0 0 * * *",
+    task_name=task_to_use,
+    args=["arg1", "arg2"],
+    kwargs={"kwarg1": "value1", "kwarg2": "value2"},
+)
+```
+- `django_qstash.results.clear_stale_results_task` is a built-in task that `django_qstash.results` provides
+- `args` and `kwargs` are the arguments to pass to the task
+- `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.
 
@@ -249,6 +353,7 @@ To install it, just add `django_qstash.results` to your `INSTALLED_APPS` setting
 ```python
 INSTALLED_APPS = [
     # ...
+    "django_qstash",
     "django_qstash.results",
     # ...
 ]
@@ -256,14 +361,14 @@ INSTALLED_APPS = [
 
 Run migrations:
 ```bash
-python manage.py migrate
+python manage.py migrate django_qstash_results
 ```
 
 ### Clear Stale Results
 
 We recommend purging the `TaskResult` model after a certain amount of time.
 ```bash
-python manage.py clear_stale_results
+python manage.py clear_stale_results --since 604800
 ```
 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).

{django_qstash-0.0.9 → django_qstash-0.0.11}/pyproject.toml

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

django_qstash-0.0.11/src/django_qstash/__init__.py

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

{django_qstash-0.0.9 → django_qstash-0.0.11}/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"]

{django_qstash-0.0.9 → django_qstash-0.0.11}/src/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-0.0.9 → django_qstash-0.0.11}/src/django_qstash/discovery/fields.py

@@ -16,10 +16,10 @@ class TaskChoiceField(forms.ChoiceField):
         kwargs.pop("max_length", None)
 
         # Get tasks before calling parent to set choices
-        tasks = discover_tasks()
+        tasks = discover_tasks(locations_only=False)
 
         # Convert tasks to choices using (task_name, task_name) format
-        task_choices = [(task_value, task_label) for task_value, task_label in tasks]
+        task_choices = [(task["location"], task["field_label"]) for task in tasks]
 
         kwargs["choices"] = task_choices
         kwargs["validators"] = [task_exists_validator] + kwargs.get("validators", [])
@@ -30,9 +30,9 @@ class TaskChoiceField(forms.ChoiceField):
         Returns the actual task dot notation path for the selected value
         """
         if self.data:
-            tasks = discover_tasks()
+            tasks = discover_tasks(locations_only=False)
 
-            for task_value, task_label in tasks:
-                if task_label == self.data:
-                    return task_value
+            for task in tasks:
+                if task["field_label"] == self.data:
+                    return task["location"]
         return None

{django_qstash-0.0.9 → django_qstash-0.0.11}/src/django_qstash/discovery/utils.py

@@ -19,7 +19,7 @@ DJANGO_QSTASH_DISCOVER_INCLUDE_SETTINGS_DIR = getattr(
 
 
 @lru_cache(maxsize=None)
-def discover_tasks() -> list[tuple[str, str]]:
+def discover_tasks(locations_only: bool = False) -> list[str] | list[dict]:
     """
     Automatically discover tasks in Django apps and return them as a list of tuples.
     Each tuple contains (dot_notation_path, task_name).
@@ -72,13 +72,21 @@ def discover_tasks() -> list[tuple[str, str]]:
                         label = value
                     else:
                         label = f"{attr.name} ({package}.tasks)"
-                    discovered_tasks.append((value, label))
+                    discovered_tasks.append(
+                        {
+                            "name": attr.name,
+                            "field_label": label,
+                            "location": f"{package}.tasks.{attr_name}",
+                        }
+                    )
         except Exception as e:
             warnings.warn(
                 f"Failed to import tasks from {package}: {str(e)}",
                 RuntimeWarning,
                 stacklevel=2,
             )
+    if locations_only:
+        return [x["location"] for x in discovered_tasks]
     return discovered_tasks
 
 

{django_qstash-0.0.9 → django_qstash-0.0.11}/src/django_qstash/discovery/validators.py

@@ -15,8 +15,8 @@ def task_exists_validator(task_name):
     Raises:
         ValidationError: If the task cannot be found
     """
-    tasks = discover_tasks()
-    available_tasks = [task[0] for task in tasks]
+    discover_tasks.cache_clear()
+    available_tasks = discover_tasks(locations_only=True)
 
     if task_name not in available_tasks:
         raise ValidationError(

django_qstash-0.0.11/src/django_qstash/management/commands/available_tasks.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from django.core.management.base import BaseCommand
+
+from django_qstash.discovery.utils import discover_tasks
+
+
+class Command(BaseCommand):
+    help = "View all available tasks"
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--locations",
+            action="store_true",
+            help="Only show task paths",
+        )
+
+    def handle(self, *args, **options):
+        locations_only = options["locations"] or False
+        self.stdout.write("Available tasks:")
+        discover_tasks.cache_clear()
+        if locations_only:
+            tasks = discover_tasks(locations_only=locations_only)
+            for task in tasks:
+                self.stdout.write(f"\t- {self.style.SQL_FIELD(task)}")
+        else:
+            tasks = discover_tasks(locations_only=False)
+            for task in tasks:
+                name = task["name"]
+                field_label = task["field_label"]
+                location = task["location"]
+                self.stdout.write(
+                    f"  Name: {self.style.SQL_FIELD(name)}\n"
+                    f"  Location: {self.style.SQL_FIELD(location)}\n"
+                    f"  Field Label: {self.style.SQL_FIELD(field_label)}"
+                )
+                self.stdout.write("")

{django_qstash-0.0.9 → django_qstash-0.0.11}/src/django_qstash/results/tasks.py

@@ -7,14 +7,14 @@ 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
 
 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
 ):

{django_qstash-0.0.9 → django_qstash-0.0.11}/src/django_qstash.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-qstash
-Version: 0.0.9
+Version: 0.0.11
 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)
@@ -68,8 +85,13 @@ This allows us to:
       - [`.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)
+  - [Management Commands](#management-commands)
+  - [Development Usage](#development-usage)
+  - [Django Settings Configuration](#django-settings-configuration)
+  - [Schedule Tasks (Optional)](#schedule-tasks-optional)
+    - [Installation](#installation-1)
+  - [Schedule a Task](#schedule-a-task)
+  - [Store Task Results (Optional)](#store-task-results-optional)
     - [Clear Stale Results](#clear-stale-results)
   - [Definitions](#definitions)
   - [Motivation](#motivation)
@@ -89,12 +111,13 @@ INSTALLED_APPS = [
     ##...
     "django_qstash",
     "django_qstash.results",
+    "django_qstash.schedules",
     ##...
 ]
 ```
-- `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_ `@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
 
@@ -138,7 +161,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 `stashed_task` decorator.
 
 Here's how it works:
 - Define a Task
@@ -146,10 +169,10 @@ Here's how it works:
 
 ### Define a Task
 ```python
-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}.")
@@ -157,7 +180,6 @@ def hello_world(name: str, age: int = None, activity: str = None):
     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.
 
@@ -220,10 +242,13 @@ print(json.dumps(data))
 
 ```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:
@@ -254,22 +279,101 @@ math_add_task.apply_async(
 The `.delay()` method does not support a countdown parameter because it simply passes the arguments (*args, **kwargs) to the `apply_async()` method.
 
 
-## Configuration
+## Management Commands
+
+- `python manage.py available_tasks` to view all available tasks
+
+_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
+
+django-qstash requires a public 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:
 
-`DJANGO_QSTASH_DOMAIN`: Must be a valid and publicly accessible domain. For example `https://djangoqstash.com`
+- `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_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.
 
-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_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_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.
+## Schedule Tasks (Optional)
 
-`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).
+The `django_qstash.schedules` app schedules tasks using Upstash [QStash Schedules](https://upstash.com/docs/qstash/features/schedules) and the django-qstash `@stashed_task` decorator.
 
+### Installation
 
-## Storing Task Results (Optional)
+Update your `INSTALLED_APPS` setting to include `django_qstash.schedules`.
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_qstash",  # required
+    "django_qstash.schedules",
+    # ...
+]
+```
+
+Run migrations:
+```bash
+python manage.py migrate django_qstash_schedules
+```
+
+
+## Schedule a Task
+
+Tasks must exist before you can schedule them. Review [Define a Task](#define-a-task) for more information.
+
+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
+
+all_available_tasks = discover_tasks(paths_only=True)
+
+desired_task = "django_qstash.results.clear_stale_results_task"
+# or desired_task = "example_app.tasks.my_task"
+
+task_to_use = desired_task
+if desired_task not in available_task_locations:
+    task_to_use = available_task_locations[0]
+
+print(f"Using task: {task_to_use}")
+
+TaskSchedule.objects.create(
+    name="My Schedule",
+    cron="0 0 * * *",
+    task_name=task_to_use,
+    args=["arg1", "arg2"],
+    kwargs={"kwarg1": "value1", "kwarg2": "value2"},
+)
+```
+- `django_qstash.results.clear_stale_results_task` is a built-in task that `django_qstash.results` provides
+- `args` and `kwargs` are the arguments to pass to the task
+- `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.
 
@@ -278,6 +382,7 @@ To install it, just add `django_qstash.results` to your `INSTALLED_APPS` setting
 ```python
 INSTALLED_APPS = [
     # ...
+    "django_qstash",
     "django_qstash.results",
     # ...
 ]
@@ -285,14 +390,14 @@ INSTALLED_APPS = [
 
 Run migrations:
 ```bash
-python manage.py migrate
+python manage.py migrate django_qstash_results
 ```
 
 ### Clear Stale Results
 
 We recommend purging the `TaskResult` model after a certain amount of time.
 ```bash
-python manage.py clear_stale_results
+python manage.py clear_stale_results --since 604800
 ```
 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).

{django_qstash-0.0.9 → django_qstash-0.0.11}/src/django_qstash.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ src/django_qstash/discovery/utils.py
 src/django_qstash/discovery/validators.py
 src/django_qstash/management/__init__.py
 src/django_qstash/management/commands/__init__.py
+src/django_qstash/management/commands/available_tasks.py
 src/django_qstash/management/commands/clear_stale_results.py
 src/django_qstash/management/commands/task_schedules.py
 src/django_qstash/results/__init__.py

django_qstash-0.0.9/src/django_qstash/__init__.py

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