django-qstash 0.0.3__py3-none-any.whl → 0.0.4__py3-none-any.whl

django_qstash/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = "0.0.3"
+__version__ = "0.0.4"
 
 from .tasks import shared_task
 

django_qstash/tasks.py

@@ -1,5 +1,9 @@
+from __future__ import annotations
+
 import functools
-from typing import Any, Callable, Dict, Optional, Tuple
+import warnings
+from typing import Any
+from typing import Callable
 
 from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured
@@ -11,7 +15,11 @@ DJANGO_QSTASH_WEBHOOK_PATH = getattr(
     settings, "DJANGO_QSTASH_WEBHOOK_PATH", "/qstash/webhook/"
 )
 if not QSTASH_TOKEN or not DJANGO_QSTASH_DOMAIN:
-    raise ImproperlyConfigured("QSTASH_TOKEN and DJANGO_QSTASH_DOMAIN must be set")
+    warnings.warn(
+        "QSTASH_TOKEN and DJANGO_QSTASH_DOMAIN should be set for QStash functionality",
+        RuntimeWarning,
+        stacklevel=2,
+    )
 
 # Initialize QStash client once
 qstash_client = QStash(QSTASH_TOKEN)
@@ -20,11 +28,11 @@ qstash_client = QStash(QSTASH_TOKEN)
 class QStashTask:
     def __init__(
         self,
-        func: Optional[Callable] = None,
-        name: Optional[str] = None,
-        delay_seconds: Optional[int] = None,
+        func: Callable | None = None,
+        name: str | None = None,
+        delay_seconds: int | None = None,
         deduplicated: bool = False,
-        **options: Dict[str, Any],
+        **options: dict[str, Any],
     ):
         self.func = func
         self.name = name or (func.__name__ if func else None)
@@ -45,6 +53,10 @@ class QStashTask:
         """
         Execute the task, either directly or via QStash based on context
         """
+        if not QSTASH_TOKEN or not DJANGO_QSTASH_DOMAIN:
+            raise ImproperlyConfigured(
+                "QSTASH_TOKEN and DJANGO_QSTASH_DOMAIN must be set to use django-qstash"
+            )
         # Handle the case when the decorator is used without parameters
         if self.func is None:
             return self.__class__(
@@ -89,18 +101,18 @@ class QStashTask:
         # Return an AsyncResult-like object for Celery compatibility
         return AsyncResult(response.message_id)
 
-    def delay(self, *args, **kwargs) -> "AsyncResult":
+    def delay(self, *args, **kwargs) -> AsyncResult:
         """Celery-compatible delay() method"""
         self._is_delayed = True
         return self(*args, **kwargs)
 
     def apply_async(
         self,
-        args: Optional[Tuple] = None,
-        kwargs: Optional[Dict] = None,
-        countdown: Optional[int] = None,
-        **options: Dict[str, Any],
-    ) -> "AsyncResult":
+        args: tuple | None = None,
+        kwargs: dict | None = None,
+        countdown: int | None = None,
+        **options: dict[str, Any],
+    ) -> AsyncResult:
         """Celery-compatible apply_async() method"""
         self._is_delayed = True
         if countdown is not None:
@@ -119,7 +131,7 @@ class AsyncResult:
     def __init__(self, task_id: str):
         self.task_id = task_id
 
-    def get(self, timeout: Optional[int] = None) -> Any:
+    def get(self, timeout: int | None = None) -> Any:
         """Simulate Celery's get() method"""
         raise NotImplementedError("QStash doesn't support result retrieval")
 
@@ -129,10 +141,10 @@ class AsyncResult:
 
 
 def shared_task(
-    func: Optional[Callable] = None,
-    name: Optional[str] = None,
+    func: Callable | None = None,
+    name: str | None = None,
     deduplicated: bool = False,
-    **options: Dict[str, Any],
+    **options: dict[str, Any],
 ) -> QStashTask:
     """
     Decorator that mimics Celery's shared_task

django_qstash-0.0.4.dist-info/METADATA

@@ -0,0 +1,343 @@
+Metadata-Version: 2.1
+Name: django-qstash
+Version: 0.0.4
+Summary: A drop-in replacement for Celery's shared_task with Upstash QStash.
+Author-email: Justin Mitchel <justin@codingforentrepreneurs.com>
+Project-URL: Changelog, https://github.com/jmitchel3/django-qstash
+Project-URL: Documentation, https://github.com/jmitchel3/django-qstash
+Project-URL: Funding, https://github.com/jmitchel3/django-qstash
+Project-URL: Repository, https://github.com/jmitchel3/django-qstash
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: django>=4.2
+Requires-Dist: qstash>=2
+Requires-Dist: requests>=2.30
+
+> :warning: **BETA Software**: Working on being production-ready soon.
+
+# django-qstash
+
+_django-qstash_ is a drop-in replacement for Celery's `shared_task`.
+
+To do this, we use:
+
+- [Upstash QStash](https://upstash.com/docs/qstash/overall/getstarted)
+- A single public _webhook_ to call `@shared_task` functions automatically
+
+This allows us to:
+
+- Focus just on Django
+- Drop Celery
+- Truly scale Django to zero
+- 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.
+
+
+## Table of Contents
+
+- [django-qstash](#django-qstash)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+    - [Using Pip](#using-pip)
+    - [Update Settings (`settings.py`)](#update-settings-settingspy)
+    - [Configure Webhook URL](#configure-webhook-url)
+    - [Required Environment Variables](#required-environment-variables)
+  - [Sample Project](#sample-project)
+  - [Dependencies](#dependencies)
+  - [Usage](#usage)
+    - [Define a Task](#define-a-task)
+    - [Regular Task Call](#regular-task-call)
+    - [Async Task](#async-task)
+      - [`.delay()`](#delay)
+      - [`.apply_async()`](#apply_async)
+      - [`.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)
+    - [Clear Stale Results](#clear-stale-results)
+  - [Definitions](#definitions)
+  - [Motivation](#motivation)
+
+
+## Installation
+
+### Using Pip
+```bash
+pip install django-qstash
+```
+
+### Update Settings (`settings.py`)
+
+```python
+INSTALLED_APPS = [
+    ##...
+    "django_qstash",
+    "django_qstash.results",
+    ##...
+]
+```
+- `django_qstash` Includes the `@shared_task` decorator and webhook view
+- `django_qstash.results` (Optional): Store task results in Django DB
+
+
+### Configure Webhook URL
+
+In your `ROOT_URLCONF` (e.g. `urls.py`), add the following:
+```python
+from django_qstash.views import qstash_webhook_view
+
+urlpatterns = [
+    # ...
+    path("qstash/webhook/", qstash_webhook_view),
+    # ...
+]
+```
+Be sure to use this path in your `DJANGO_QSTASH_WEBHOOK_PATH` environment variable.
+
+### Required Environment Variables
+
+Get your QStash token and signing keys from [Upstash](https://upstash.com/).
+
+```python
+QSTASH_TOKEN = "your_token"
+QSTASH_CURRENT_SIGNING_KEY = "your_current_signing_key"
+QSTASH_NEXT_SIGNING_KEY = "your_next_signing_key"
+
+# required for django-qstash
+DJANGO_QSTASH_DOMAIN = "https://example.com"
+DJANGO_QSTASH_WEBHOOK_PATH = "/qstash/webhook/"
+```
+> Review [.env.sample](.env.sample) to see all the environment variables you need to set.
+
+
+## Sample Project
+There is a sample project in [sample_project/](sample_project/) that shows how all this is implemented.
+
+## Dependencies
+
+- [Python 3.10+](https://www.python.org/)
+- [Django 5+](https://docs.djangoproject.com/)
+- [qstash-py](https://github.com/upstash/qstash-py)
+- [Upstash](https://upstash.com/) account
+
+## Usage
+
+Django-QStash revolves around the `shared_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
+- Call a Task with `.delay()` or `.apply_async()`
+
+### Define a Task
+```python
+from django_qstash import shared_task
+
+
+@shared_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.")
+```
+
+
+### Regular Task Call
+Nothing special here. Just call the function like any other to verify it works.
+
+```python
+# normal function call
+hello_world("Tony Stark", age=40, activity="building in a cave with a box of scraps.")
+```
+
+### Async 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.
+
+
+#### `.delay()`
+```python
+hello_world.delay(
+    "Tony Stark", age=40, activity="building in a cave with a box of scraps."
+)
+```
+
+#### `.apply_async()`
+```python
+hello_world.apply_async(
+    args=("Tony Stark",),
+    kwargs={"activity": "building in a cave with a box of scraps."},
+)
+```
+
+#### `.apply_async()` With Time Delay
+
+Just use the `countdown` parameter to delay the task by N seconds. (always in seconds): `.apply_async(*args, **kwargs, countdown=N)`
+
+
+```python
+# async task delayed 35 seconds
+delay_35_seconds = 35
+hello_world.apply_async(
+    args=("Tony Stark",),
+    kwargs={"activity": "building in a cave with a box of scraps."},
+    countdown=delay_35_seconds,
+)
+```
+
+### JSON-ready Arguments
+
+Each argument needs to be _JSON_ serializable. The way you find out:
+
+```python
+import json
+
+data = {
+    "args": ("Tony Stark",),
+    "kwargs": {"activity": "building in a cave with a box of scraps."},
+}
+print(json.dumps(data))
+# no errors, you're good to go.
+```
+
+### Example Task
+
+```python
+# from celery import shared_task
+from django_qstash import shared_task
+
+
+@shared_task
+def math_add_task(a, b, save_to_file=False, *args, **kwargs):
+    logger.info(f"Adding {a} and {b}")
+    if save_to_file:
+        with open("math-add-result.txt", "w") as f:
+            f.write(f"{a} + {b} = {a + b}")
+    return a + b
+```
+
+
+Calling:
+```python
+math_add_task.apply_async(args=(12, 454), save_to_file=True)
+```
+is the same as
+```python
+math_add_task.delay(12, 454, save_to_file=True)
+```
+
+But if you need to delay the task, use `.apply_async()` with the `countdown` parameter.
+
+```python
+five_hours = 5 * 60 * 60
+math_add_task.apply_async(
+    args=(12, 454), kwargs={"save_to_file": True}, countdown=five_hours
+)
+```
+
+The `.delay()` method does not support a countdown parameter because it simply passes the arguments (*args, **kwargs) to the `apply_async()` method.
+
+
+## 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`
+
+In development mode, we recommend using a tunnel like [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with a domain name you control. You can also consider [ngrok](https://ngrok.com/).
+
+`DJANGO_QSTASH_WEBHOOK_PATH` (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.
+
+`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).
+
+
+## Storing 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.
+
+To install it, just add `django_qstash.results` to your `INSTALLED_APPS` setting.
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_qstash.results",
+    # ...
+]
+```
+
+Run migrations:
+```bash
+python manage.py migrate
+```
+
+### Clear Stale Results
+
+We recommend purging the `TaskResult` model after a certain amount of time.
+```bash
+python manage.py clear_stale_results
+```
+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).
+- `--no-input` is a flag to skip the confirmation prompt to delete the results.
+
+
+
+## Definitions
+
+- **Background Task**: A function or task that is not part of the request/response cycle.
+  - Examples include as sending an email, running a report, or updating a database.
+  - Pro: Background tasks can drastically improve the end-user experience since they can move on with their day while the task runs in the background.
+  - Con: Processes that run background tasks (like Celery) typically have to run 24/7.
+- **Scale-to-Zero**: Depending on the amount of traffic, Django can be effectively turned off. If done right, when more traffic comes in, Django can be turned back on very quickly.
+- **Serverless**: A cloud computing model where code runs without server management, with scaling and billing tied to usage. Often used interchangeably with "scale-to-zero".
+
+
+## Motivation
+
+TLDR - Celery cannot be serverless. I want serverless "Celery" so I only pay for the apps that have attention and traffic. Upstash created QStash to help solve the problem of message queues in a serverless environment. django-qstash is the goldilocks that combines the functionality of Celery with the functionality of QStash all to unlock fully serverless Django.
+
+I run a lot of side projects with Django. Some as demos for tutorials based on my work at [@codingforentrepreneurs](https://cfe.sh/github) and some are new businesses that haven't found much traction yet.
+
+Most web apps can benefit from async background tasks such as sending emails, running reports, or updating databases.
+
+But how?
+
+Traditionally, I'd reach for Celery but that can get expensive really quick. Running a lot of Django projects can add up too -- "death by a thousand cuts" if you will. A server for Django, for celery worker, for celery beat scheduler, and so on. It adds up fast.
+
+I think serverless is the answer. Pay for what you use and scale to zero when you don't need it and scale up when you do -- all automated.
+
+Django can be serverless and is pretty easy to do thanks to Docker and the countless hosting options and services out there. Celery cannot be serverless, at least yet.
+
+Let's face it. Celery is a powerful tool to run async background tasks but it comes at a cost. It needs at least one server running 24/7. For best performance it needs 2 (one worker, one beat). It also needs Redis or RabbitMQ. Most background processes that are tied to web apps are not serverless; they have to "listen" for their next task.
+
+To make Django truly scale-to-zero and serverless, we need to drop Celery.
+
+Enter __django-qstash__.
+
+django-qstash is designed to be a near drop-in replacement for Celery's `shared_task` decorator.
+
+It works by leveraging Upstash QStash to deliver messages about your tasks (e.g. the function's arguments) via webhooks to your Django application.  In the QStash [docs](https://upstash.com/docs/qstash/overall/getstarted), it is described as:
+
+> QStash is a serverless messaging and scheduling solution. It fits easily into your existing workflow and allows you to build reliable systems without managing infrastructure.
+>
+> Instead of calling an endpoint directly, QStash acts as a middleman between you and an API to guarantee delivery, perform automatic retries on failure, and more.
+
+django-qstash has a webhook handler that converts a QStash message to run a specific `@shared_task` function (the one that called `.delay()` or `.apply_async()`). It's easy, it's cheap, it's effective, and best of all, it unlocks the scale-to-zero potential of Django as a serverless app.

{django_qstash-0.0.3.dist-info → django_qstash-0.0.4.dist-info}/RECORD

@@ -1,7 +1,7 @@
-django_qstash/__init__.py,sha256=KLUoDDQqN2L9ikWuv1pbu1hY2VEXh93Kzn09C6TbmLI,117
+django_qstash/__init__.py,sha256=wkPLjMVFXjwiEliBROhlszOouSwzpvgVAXU0IfHtlAw,117
 django_qstash/exceptions.py,sha256=pH6kKRJFIVFkDHUJQ9yRWmtGdBBSXpNAwMSFuNzMgPw,392
 django_qstash/handlers.py,sha256=mmm8TJOqV3j1rQXooNOa128gtmALXFNCAaDZ5xwIcuw,4950
-django_qstash/tasks.py,sha256=X2gFILRvUF2GFuwyAUT43Zvw7OsdFci7870VhRNQ5-M,4929
+django_qstash/tasks.py,sha256=tiBJz8BIOYRD6MN0k4_1ncKCjLlptP3BvTad9lz7YVo,5220
 django_qstash/utils.py,sha256=wrTU30cobO2di18BNEFtKD4ih2euf7eQNpg6p6TkQ1Y,1185
 django_qstash/views.py,sha256=H32f_jGnlwOTO0YG9znNo2b-GRYZ8TM-Wt0T62SGdXM,639
 django_qstash/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -13,7 +13,7 @@ django_qstash/results/models.py,sha256=aEiAhGJOuLRtjibUw6xdQqUt3eYKLqY2as4I4QSrF
 django_qstash/results/services.py,sha256=HvNp5D1tQ__nz4LVUTAGxuyLl_dnlBps4pJ6E9HD2kA,991
 django_qstash/results/migrations/0001_initial.py,sha256=A90SKgWmBf4SIJYG1Jh6-b_81Ia1zIzGj3Bfl1O4-kg,1902
 django_qstash/results/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-django_qstash-0.0.3.dist-info/METADATA,sha256=t_nf7LAsZI-R5PEyKI2yPxxsRobQ6QoI33e_9div-kE,3332
-django_qstash-0.0.3.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-django_qstash-0.0.3.dist-info/top_level.txt,sha256=AlV3WSK1A0ZvKuCLsINtIJhJW8zo7SEB-D3_RAjZ0hI,14
-django_qstash-0.0.3.dist-info/RECORD,,
+django_qstash-0.0.4.dist-info/METADATA,sha256=D8RJT4Ivi3TlKjhD8hGw_YcLJvBo6r4XK6Vp7_pJ8e8,12307
+django_qstash-0.0.4.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+django_qstash-0.0.4.dist-info/top_level.txt,sha256=AlV3WSK1A0ZvKuCLsINtIJhJW8zo7SEB-D3_RAjZ0hI,14
+django_qstash-0.0.4.dist-info/RECORD,,

django_qstash-0.0.3.dist-info/METADATA

@@ -1,99 +0,0 @@
-Metadata-Version: 2.1
-Name: django-qstash
-Version: 0.0.3
-Summary: A drop-in replacement for Celery's shared_task with Upstash QStash.
-Author-email: Justin Mitchel <justin@codingforentrepreneurs.com>
-Project-URL: Changelog, https://github.com/jmitchel3/django-qstash
-Project-URL: Documentation, https://github.com/jmitchel3/django-qstash
-Project-URL: Funding, https://github.com/jmitchel3/django-qstash
-Project-URL: Repository, https://github.com/jmitchel3/django-qstash
-Classifier: Development Status :: 4 - Beta
-Classifier: Framework :: Django :: 4.2
-Classifier: Framework :: Django :: 5.0
-Classifier: Framework :: Django :: 5.1
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Natural Language :: English
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: django>=4.2
-Requires-Dist: qstash>=2
-Requires-Dist: requests>=2.30
-
-> :warning: **BETA Software**: Working on being production-ready soon.
-
-# Django QStash `pip install django-qstash`
-
-A drop-in replacement for Celery's shared_task leveraging Upstash QStash for a truly serverless Django application to run background tasks asynchronously from the request/response cycle.
-
-## Installation
-
-```bash
-pip install django-qstash
-```
-
-Depends on:
-
-- [Python 3.10+](https://www.python.org/)
-- [Django 5+](https://docs.djangoproject.com/)
-- [qstash-py](https://github.com/upstash/qstash-py)
-
-## Usage
-
-```python
-# from celery import shared_task
-from django_qstash import shared_task
-
-
-@shared_task
-def math_add_task(a, b, save_to_file=False):
-    logger.info(f"Adding {a} and {b}")
-    if save_to_file:
-        with open("math-add-result.txt", "w") as f:
-            f.write(f"{a} + {b} = {a + b}")
-    return a + b
-```
-
-```python
-math_add_task.apply_async(args=(12, 454), save_to_file=True)
-
-# or
-
-math_add_task.delay(12, 454, save_to_file=True)
-```
-
-
-## Configuration
-
-### Environment variables
-
-
-```python
-QSTASH_TOKEN = "your_token"
-QSTASH_CURRENT_SIGNING_KEY = "your_current_signing_key"
-QSTASH_NEXT_SIGNING_KEY = "your_next_signing_key"
-
-# required for django-qstash
-DJANGO_QSTASH_DOMAIN = "https://example.com"
-DJANGO_QSTASH_WEBHOOK_PATH = "/qstash/webhook/"
-```
-
-
-`DJANGO_QSTASH_DOMAIN`: Must be a valid and publicly accessible domain. For example `https://djangoqstash.com`
-
-In development mode, we recommend using a tunnel like [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with a domain name you control. You can also consider [ngrok](https://ngrok.com/).
-
-
-`DJANGO_QSTASH_WEBHOOK_PATH` (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.
-
-`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).