django_tasks_pubsub

Google Cloud Pub/Sub backend for Django tasks

Installation

Package manager

pip

pip install django_tasks_pubsub

uv

uv add django_tasks_pubsub

Add to INSTALLED_APPS

INSTALLED_APPS = [
    ...
    "django_tasks_pubsub",
]

Settings

Idempotency check

add to settings what prefix you want for me to check idempotency

this will ensure that the task is not executed multiple times for the same message

uses django cache framework to check status of ongoing tasks

PUBSUB_CACHE_PREFIX = 'some_prefix'

Add required Google Cloud Pub/Sub settings

PUBSUB_PROJECT_ID = "your-google-cloud-project-id"
PUBSUB_DEFAULT_TOPIC_ID = "your-default-topic-id"

Optional telemetry propagation hooks

The queue layer stays telemetry-agnostic. If your app wants to propagate tracing information via message attributes, configure a getter and a restorer hook.

# settings.py
DJANGO_TASKS_PUBSUB_TRACE_PROPAGATION_GETTER = "myapp.telemetry.get_message_trace_metadata"
DJANGO_TASKS_PUBSUB_TRACE_PROPAGATION_RESTORER = "myapp.telemetry.restore_trace_context"

# myapp/telemetry.py
def get_message_trace_metadata() -> dict[str, str]:
    return {
        "sentry-trace": sentry_sdk.get_traceparent(),
        "baggage": sentry_sdk.get_baggage() or "",
    }


def restore_trace_context(metadata: dict[str, str]) -> object:
    return sentry_sdk.continue_trace(metadata)

If no hook is configured, the library behaves as a no-op and sends no tracing attributes or context restoration.

Add the backend to the TASKS setting

TASKS = {
    "default": {
        "BACKEND": "django_tasks_pubsub.PubSubBackend",
    }
}

Authentication

Check out the Google Cloud Pub/Sub documentation for more information.

In short the the client works well within a Google Cloud environment.

URLs

In order to receive push messages from Google Cloud Pub/Sub, you need to register the endpoint in your project's urls.py:

from django.urls import path, include

urlpatterns = [
    ...
    path("", include("django_tasks_pubsub.urls")),
]

This will expose the endpoint at /pubsub/push/. You should configure your Google Cloud Pub/Sub push subscription to use this endpoint (e.g. https://your-domain.com/pubsub/push/).

Usage

Configure Django task functions

from django.tasks import task

@task
def send_email(user_id):
    print(f"Sending email to {user_id}")

Configure specifics for the task

Specify a topic

To specify a topic, you need to decorate the task with @task and @pubsub_task(topic="topic-name") in this order:

from django.tasks import task
from django_tasks_pubsub import pubsub_task


@task
@pubsub_task(topic_id="images")
def function(image_id: int):
    ...

Development

Commit Messages

All commits to this repository must follow the Conventional Commits specification.

This is required because the automated release and tagging workflow relies on conventional commit prefixes (such as feat:, fix:, chore:, docs:, etc.) to automatically calculate the next semantic version.

License

MIT