Metadata-Version: 2.4
Name: django-tasks-pubsub
Version: 0.2.1
Summary: Django tasks backend for Google Cloud Pub/Sub
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: django>=6.0.5
Requires-Dist: google-cloud-pubsub>=2.38.0

# django_tasks_pubsub

Google Cloud Pub/Sub backend for Django tasks

## Installation

### Package manager

#### pip
```bash
pip install django_tasks_pubsub
```

#### uv
```bash
uv add django_tasks_pubsub
```

### Add to INSTALLED_APPS
```python
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

```python
PUBSUB_CACHE_PREFIX = 'some_prefix'
```

### Add required Google Cloud Pub/Sub settings
```python
PUBSUB_PROJECT_ID = "your-google-cloud-project-id"
PUBSUB_DEFAULT_TOPIC_ID = "your-default-topic-id"
```

### Add the backend to the TASKS setting

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

### Authentication

Check out the Google Cloud Pub/Sub documentation for [more information](https://docs.cloud.google.com/python/docs/reference/pubsub/latest).

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`:

```python
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
```python
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:

```python
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](https://www.conventionalcommits.org/) 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
