django-qstash 0.0.13__py3-none-any.whl → 0.0.15__py3-none-any.whl

django_qstash/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = "0.0.13"
+__version__ = "0.0.15"
 
 from django_qstash.app import shared_task
 from django_qstash.app import stashed_task

django_qstash/client.py

@@ -1,7 +1,25 @@
 from __future__ import annotations
 
+import os
+import warnings
+
 from qstash import QStash
 
 from django_qstash.settings import QSTASH_TOKEN
 
-qstash_client = QStash(QSTASH_TOKEN)
+QSTASH_URL = os.environ.get("QSTASH_URL", None)
+
+
+def init_qstash():
+    kwargs = {
+        "token": QSTASH_TOKEN,
+    }
+    if QSTASH_URL is not None:
+        warning_msg = f"\n\n\033[93mUsing {QSTASH_URL} as your QStash URL. \
+            \nThis configuration should only be used in development.\n\033[0m"
+        warnings.warn(warning_msg, RuntimeWarning, stacklevel=2)
+        kwargs["base_url"] = QSTASH_URL
+    return QStash(**kwargs)
+
+
+qstash_client = init_qstash()

django_qstash/settings.py

@@ -11,7 +11,7 @@ DJANGO_QSTASH_WEBHOOK_PATH = getattr(
 )
 if not QSTASH_TOKEN or not DJANGO_QSTASH_DOMAIN:
     warnings.warn(
-        "QSTASH_TOKEN and DJANGO_QSTASH_DOMAIN should be set for QStash functionality",
+        "DJANGO_SETTINGS_MODULE (settings.py required) requires QSTASH_TOKEN and DJANGO_QSTASH_DOMAIN should be set for QStash functionality",
         RuntimeWarning,
         stacklevel=2,
     )

django_qstash/urls.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from django.urls import path
+
+from django_qstash.views import qstash_webhook_view
+
+urlpatterns = [
+    path("", qstash_webhook_view),
+]

{django_qstash-0.0.13.dist-info → django_qstash-0.0.15.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: django-qstash
-Version: 0.0.13
+Version: 0.0.15
 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
@@ -72,7 +72,7 @@ This allows us to:
   - [Installation](#installation)
     - [Using Pip](#using-pip)
     - [Update Settings (`settings.py`)](#update-settings-settingspy)
-    - [Configure Webhook URL](#configure-webhook-url)
+    - [Configure QStash Webhook Handler](#configure-qstash-webhook-handler)
     - [Required Environment Variables](#required-environment-variables)
   - [Sample Project](#sample-project)
   - [Dependencies](#dependencies)
@@ -86,7 +86,9 @@ This allows us to:
     - [Arguments Must be JSON-ready](#arguments-must-be-json-ready)
     - [Example Task](#example-task)
   - [Management Commands](#management-commands)
-  - [Public Domain In Development](#public-domain-in-development)
+  - [Development](#development)
+    - [Development with a Public Domain](#development-with-a-public-domain)
+    - [Development with Docker Compose](#development-with-docker-compose)
   - [Django Settings Configuration](#django-settings-configuration)
     - [`DJANGO_QSTASH_DOMAIN`](#django_qstash_domain)
     - [`DJANGO_QSTASH_WEBHOOK_PATH`](#django_qstash_webhook_path)
@@ -123,20 +125,27 @@ INSTALLED_APPS = [
 - `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
+### Configure QStash Webhook Handler
+
+Set it and forget it. `django_qstash` will handle the webhook from qstash automatically for you.
 
 In your `ROOT_URLCONF` (e.g. `urls.py`), add the following:
+
 ```python
-from django_qstash.views import qstash_webhook_view
+from django.urls import include
 
 urlpatterns = [
     # ...
-    path("qstash/webhook/", qstash_webhook_view),
+    path("qstash/webhook/", include("django_qstash.urls")),
     # ...
 ]
 ```
 Be sure to use this path in your `DJANGO_QSTASH_WEBHOOK_PATH` environment variable.
 
+
+The `django_qstash` webhook handler runs your `@shared_task` or `@stashed_task` functions via the `importlib` module. In other words, you should not need to modify the webhook handler.
+
+
 ### Required Environment Variables
 
 Get your QStash token and signing keys from [Upstash](https://upstash.com/).
@@ -312,15 +321,33 @@ _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.
 
-## Public Domain In Development
+## Development
+
+During development, you have two options:
+
+- Use Upstash.com with a publicly accessible domain (preferred)
+- Use Docker Compose with [compose.dev.yaml](./compose.dev.yaml)
 
-django-qstash _requires_ a publicly accessible domain to work (e.g. `https://djangoqstash.com`). There are many ways to do this, we recommend:
+### Development with a Public Domain
+
+The closer your development environment is to production the better. For that reason, using a publicly accessible domain is the preferred with to develop with _django-qstash_.
+
+To get a public domain during development, we recommend any of the following:
 
 - [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.
 
+### Development with Docker Compose
+Upstash covers how to run QStash during development on [this guide](https://upstash.com/docs/qstash/howto/local-development)
+
+In our case we need to the following things:
+
+- `docker compose -f compose.dev.yaml up`
+- Add `QSTASH_URL=http://127.0.0.1:8585` to your `.env` file.
+- Use the `QSTASH_TOKEN`, `QSTASH_CURRENT_SIGNING_KEY`, and `QSTASH_NEXT_SIGNING_KEY` the terminal output of Docker compose _or_ the values listed in [compose.dev.yaml](./compose.dev.yaml).
+
 ## Django Settings Configuration
 
 Various options are available to configure django-qstash.
@@ -348,7 +375,7 @@ Various options are available to configure django-qstash.
 
 ### 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).
+For a complete example, review [sample_project/cfehome/settings.py](sample_project/cfehome/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
@@ -364,10 +391,13 @@ CSRF_TRUSTED_ORIGINS = [os.environ.get("CSRF_TRUSTED_ORIGIN")]
 ###########################
 # qstash-py settings
 ###########################
+USE_LOCAL_QSTASH = str(os.environ.get("USE_LOCAL_QSTASH")) == "1"
 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")
-
+if DJANGO_DEBUG and USE_LOCAL_QSTASH:
+    # connect to the docker compose qstash instance
+    os.environ["QSTASH_URL"] = "http://127.0.0.1:8585"
 ###########################
 # django_qstash settings
 ###########################
@@ -504,7 +534,7 @@ I think serverless is the answer. Pay for what you use and scale to zero when yo
 
 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.
+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. In a traditional Django setup with Celery and Redis, you need to run 3 to 4 different processes. 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.
 
@@ -518,4 +548,6 @@ It works by leveraging Upstash QStash to deliver messages about your tasks (e.g.
 >
 > 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.
 
+Compared to a traditional setup with Django, Celery, and Redis, which requires 3 to 4 processes, you only need to run a single process and can delegate the rest to Upstash QStash, significantly simplifying your infrastructure.
+
 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.13.dist-info → django_qstash-0.0.15.dist-info}/RECORD

@@ -1,10 +1,11 @@
-django_qstash/__init__.py,sha256=YxzkGaAxjJrK8LRaZOcuwlnwzmTIBbfSOmhFmFG4oKk,188
+django_qstash/__init__.py,sha256=flZbUo7KZBqp_bfv_j-M02CRYxQovuoQF4OCVi9SF3o,188
 django_qstash/callbacks.py,sha256=IQ-D8sPlSRuREZ1zwkRyd2GtxfmrJJh2x4jLd39rZCE,813
-django_qstash/client.py,sha256=cgHf-g6lDAltY_Vt6GUVJNY2JSz1czBOHL-WVkkLs2M,149
+django_qstash/client.py,sha256=9xO4iwR62PkEQhzC92yKRlzqEIF5Yi0HpYc88v_drsI,612
 django_qstash/cron.py,sha256=13OzTMGXFgjNEXjs2Et20WGZYtW9lKlu79BjbRySnVc,716
 django_qstash/exceptions.py,sha256=pH6kKRJFIVFkDHUJQ9yRWmtGdBBSXpNAwMSFuNzMgPw,392
 django_qstash/handlers.py,sha256=TtYZ-Sr858ajISBpDuHIT7-qaVsoVfTE6vVFJ9-kpPE,5820
-django_qstash/settings.py,sha256=YvpXMo1AdIWvbotISWJmhg0vrW3A3UQ4BieNzMfRC7Y,524
+django_qstash/settings.py,sha256=s5xn4Rim8ip98q5Jiy1O6VVva2mUuAwUjbjo18fjqKA,579
+django_qstash/urls.py,sha256=1dNblYOCIBdqSXbA1jSL9H0aiXN5gIDVwhfZeC4-DQw,172
 django_qstash/utils.py,sha256=wrTU30cobO2di18BNEFtKD4ih2euf7eQNpg6p6TkQ1Y,1185
 django_qstash/views.py,sha256=H32f_jGnlwOTO0YG9znNo2b-GRYZ8TM-Wt0T62SGdXM,639
 django_qstash/app/__init__.py,sha256=kmoCVoESInzCZ_oGUiPVY4GsFQwBC07cqFJCyn9Loyk,240
@@ -45,7 +46,7 @@ django_qstash/schedules/migrations/0001_initial.py,sha256=66cA8xnJV3h7QgzCaOiv-N
 django_qstash/schedules/migrations/0002_taskschedule_updated_at.py,sha256=6hZO0a9P2ZpOROkk7O5UXBhahghU0QfxZl4E-c3HKGw,459
 django_qstash/schedules/migrations/0003_alter_taskschedule_cron.py,sha256=oBW_FcvosKsa0l_l3eVDRIZli5K1wQaN_DJjamVe23s,826
 django_qstash/schedules/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-django_qstash-0.0.13.dist-info/METADATA,sha256=6Vu2KEGFnQqPikFsTWo1cUJBRTq9Qi6CAJQsBuCijBM,19422
-django_qstash-0.0.13.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-django_qstash-0.0.13.dist-info/top_level.txt,sha256=AlV3WSK1A0ZvKuCLsINtIJhJW8zo7SEB-D3_RAjZ0hI,14
-django_qstash-0.0.13.dist-info/RECORD,,
+django_qstash-0.0.15.dist-info/METADATA,sha256=J8-nvVXGScbpWZfZdcQO-1n4O5pL6EiRdzJOUkczT8s,21209
+django_qstash-0.0.15.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+django_qstash-0.0.15.dist-info/top_level.txt,sha256=AlV3WSK1A0ZvKuCLsINtIJhJW8zo7SEB-D3_RAjZ0hI,14
+django_qstash-0.0.15.dist-info/RECORD,,