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

django_qstash/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = "0.0.8"
+__version__ = "0.0.10"
 
 from django_qstash.app import shared_task
 

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/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/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/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/schedules/services.py

@@ -20,7 +20,9 @@ def sync_task_schedule_instance_to_qstash(instance: TaskSchedule) -> TaskSchedul
     and updates existing schedules when active.
     """
     data = format_task_schedule_for_qstash(instance)
-    qstash_client.schedule.create(**data)
+    schedule_id = qstash_client.schedule.create(**data)
+    if not instance.schedule_id:
+        TaskSchedule.objects.filter(id=instance.id).update(schedule_id=schedule_id)
 
     sync_state_changes(instance)
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-qstash
-Version: 0.0.8
+Version: 0.0.10
 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
@@ -68,8 +68,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 +94,13 @@ INSTALLED_APPS = [
     ##...
     "django_qstash",
     "django_qstash.results",
+    "django_qstash.schedules",
     ##...
 ]
 ```
 - `django_qstash` Includes the `@shared_task` decorator 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.
 
 ### Configure Webhook URL
 
@@ -157,7 +163,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.
 
@@ -254,22 +259,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.
 
-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_FORCE_HTTPS` (default:`True`): Whether to force HTTPS for the webhook.
 
-`DJANGO_QSTASH_WEBHOOK_PATH` (default:`/qstash/webhook/`): The path where QStash will send webhooks to your Django application.
+- `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_FORCE_HTTPS` (default:`True`): Whether to force HTTPS for the webhook.
 
-`DJANGO_QSTASH_RESULT_TTL` (default:`604800`): A number of seconds after which task result data can be safely deleted. Defaults to 604800 seconds (7 days or 7 * 24 * 60 * 60).
+## 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.
 
-## Storing Task Results (Optional)
+### Installation
+
+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 +362,7 @@ To install it, just add `django_qstash.results` to your `INSTALLED_APPS` setting
 ```python
 INSTALLED_APPS = [
     # ...
+    "django_qstash",
     "django_qstash.results",
     # ...
 ]
@@ -285,14 +370,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.8.dist-info → django_qstash-0.0.10.dist-info}/RECORD

@@ -1,4 +1,4 @@
-django_qstash/__init__.py,sha256=NkydB5VW3zGO7c9-nveE0LELDPNix3lLQIZxWDeFBtI,128
+django_qstash/__init__.py,sha256=LX7-S0Qx-tBkMzcbIy-Fv4WyLP_wY0GnNsO2YG1bJoA,129
 django_qstash/callbacks.py,sha256=VG5tGdNzAmUEh7NlpghrxhWvnpRNXZucWmWwxaemw0M,530
 django_qstash/client.py,sha256=cgHf-g6lDAltY_Vt6GUVJNY2JSz1czBOHL-WVkkLs2M,149
 django_qstash/exceptions.py,sha256=pH6kKRJFIVFkDHUJQ9yRWmtGdBBSXpNAwMSFuNzMgPw,392
@@ -10,12 +10,13 @@ django_qstash/app/__init__.py,sha256=353w1JyvIinkr3aHjyT7I01utFM56lrgIjSSfqtJkA4
 django_qstash/app/base.py,sha256=gM7GIJh_omZcxbmsrwAEadA-N6EuUJbPzh0CflOIVRg,3864
 django_qstash/app/decorators.py,sha256=Gn0TAxUHfS4fKUdKdArvHeWlxrRvj9_NOVnC1a6pGTQ,732
 django_qstash/discovery/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-django_qstash/discovery/fields.py,sha256=qZDKMpl6VMRJL0FkGwXkeN_rcCT32cupDaXJOz-bFzs,1226
+django_qstash/discovery/fields.py,sha256=h-31sysbIU05KGKGBAu7uQo9bZnZg3kgjN_ZhPPMTGU,1260
 django_qstash/discovery/models.py,sha256=9ml9lTKEqEKx2uqYvejZw_BjdnowgFOPE7rYNt_8E9A,685
-django_qstash/discovery/utils.py,sha256=NxX6Y-Hd_AALgeESUW8AbIHReYPpbntvZjhlbrXTYnw,3224
-django_qstash/discovery/validators.py,sha256=NNCf7ltW--sTw0w8FWwTp-4PtiS35U6DITEApx-D7X4,645
+django_qstash/discovery/utils.py,sha256=OW-sbHWSnA1Hop5X0ys1hlxoYi5fNTXfAg0rKku5sx0,3561
+django_qstash/discovery/validators.py,sha256=50-GxdSNj00eY-EGxDR8u1kUQDj0g8PoeWHAGG1cvzk,657
 django_qstash/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 django_qstash/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_qstash/management/commands/available_tasks.py,sha256=l-do7Mry83NxbCdyMLcLZKtwE_T428i8wA42FIn5fq0,1295
 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
@@ -33,13 +34,13 @@ django_qstash/schedules/exceptions.py,sha256=fvXArrK24ZBGITijuJ_I5xixURmFrJpQ6Db
 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/services.py,sha256=DqwYn2kSEJ7f06WskmWRWIzeadV70aHURgWGvmg9FK0,2055
+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/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.8.dist-info/METADATA,sha256=bK9_Xyk6YmMJZO1FF3L3mZTuOlXkUIU7azMroDV6IQY,12307
-django_qstash-0.0.8.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-django_qstash-0.0.8.dist-info/top_level.txt,sha256=AlV3WSK1A0ZvKuCLsINtIJhJW8zo7SEB-D3_RAjZ0hI,14
-django_qstash-0.0.8.dist-info/RECORD,,
+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,,