Metadata-Version: 2.4
Name: dramatiq-gcpubsub
Version: 0.1.0
Summary: A Google Cloud Pub/Sub broker for Dramatiq.
Project-URL: Repository, https://github.com/dakaii/dramatiq-gcpubsub
Project-URL: Issues, https://github.com/dakaii/dramatiq-gcpubsub/issues
Author: dakaii
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: dramatiq,google-cloud,pubsub
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Requires-Dist: dramatiq
Requires-Dist: google-cloud-pubsub
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# dramatiq-gcpubsub

A [Dramatiq](https://dramatiq.io/) broker for [Google Cloud Pub/Sub](https://cloud.google.com/pubsub).

**Status:** alpha (`0.1.0`). APIs may change; see [limitations](#limitations-and-future-work).

## Installation

```bash
pip install dramatiq-gcpubsub
```

For local development of this repo:

```bash
pip install -e ".[dev]"
# or: make install
```

## Usage

```python
import dramatiq
from dramatiq_gcpubsub import PubSubBroker

broker = PubSubBroker(project_id="your-gcp-project-id")
dramatiq.set_broker(broker)

@dramatiq.actor
def my_task(x, y):
    return x + y

my_task.send(3, 7)
```

## Example app (emulator)

In-repo demo under [`examples/`](examples/). Fastest path:

```bash
# Terminal A: emulator + worker
make example

# Terminal B: enqueue sample tasks
make example-send
```

See [examples/README.md](examples/README.md) for non-Docker usage.

## Local development with the emulator

```bash
export PUBSUB_EMULATOR_HOST=localhost:8085
export PUBSUB_PROJECT_ID=test-project
dramatiq myapp.tasks
```

Start the emulator:

```bash
make up
# or:
docker compose up -d pubsub-emulator
```

## Limitations and future work

- **Delayed messages** — `enqueue(..., delay=...)` is not supported yet; calling it raises `NotImplementedError`. Planned: use Pub/Sub scheduled publish (`publish_time`).
- **Dead-letter topic** — Subscriptions are created without a dead-letter policy. Planned: optional broker parameter to attach a dead-letter topic to subscriptions.
- **Publish batching** — Messages are published one at a time. Planned: optional batching for higher throughput.

## GCP permissions

For production, the service account used by your worker needs at least:

- `pubsub.topics.create`, `pubsub.topics.publish`
- `pubsub.subscriptions.create`, `pubsub.subscriptions.consume`, `pubsub.subscriptions.update`

Or use the predefined role `roles/pubsub.admin` for full access.

## Testing

You do **not** need a real GCP project for tests. Use the Pub/Sub emulator.

### Unit tests (no emulator)

```bash
make test-unit
# or: pytest tests/unit/ -v
```

### Integration tests (emulator)

```bash
make test
# or: docker compose run --rm tests
```

Integration tests are skipped if `PUBSUB_EMULATOR_HOST` is not set.

### CI

GitHub Actions runs lint, unit tests on Python 3.10–3.12, and integration tests via docker compose on every push/PR. Releases re-run that suite before publishing to PyPI.

## Publishing to PyPI

See [docs/PUBLISHING.md](docs/PUBLISHING.md).

## License

Apache 2.0
