Weni EDA

weni-eda is a Python library that simplifies Event-Driven Architecture (EDA) with Django and AMQP brokers. It supports:

Both scopes share the same consumer and publisher APIs — you only swap the connection params factory (and the matching env vars).

Features

• Easy integration with Django
• RabbitMQ (plain AMQP) and AmazonMQ (AMQP over SSL)
• Transport-agnostic Message and Channel abstractions
• Optional event envelopes (event_id, event_type, producer, timestamp, data)
• Optional buffered consumers for high-throughput workloads

Installation

pip install weni-eda

Django setup

Add the app to INSTALLED_APPS:

# settings.py
INSTALLED_APPS = [
    # ...
    "weni.eda.django.eda_app",
]

Point EDA_CONSUMERS_HANDLE to the function that registers your consumers (used by both brokers unless overridden per process):

# settings.py
EDA_CONSUMERS_HANDLE = "myapp.messages.handle.handle_consumers"

RabbitMQ (no SSL)

Use this for a standard RabbitMQ broker on port 5672.

Environment variables

Publisher

from weni.eda.django import ConnectionParamsFactory
from weni.eda.eda_publisher import EDAPublisher

publisher = EDAPublisher(ConnectionParamsFactory)
publisher.send_message(
    {"event": "order.created", "order_id": 123},
    exchange="orders",
    routing_key="order.created",
)

ConnectionParamsFactory reads the EDA_* settings above.

Consumer

1. Implement a consumer:

from weni.eda.django.consumers import EDAConsumer
from weni.eda.messages import Message


class ExampleConsumer(EDAConsumer):
    def consume(self, message: Message):
        body = message.json()
        # ... handle body ...
        self.ack()

1. Register it in handle_consumers:

from weni.eda.channels import Channel
from .example_consumer import ExampleConsumer


def handle_consumers(channel: Channel):
    channel.basic_consume("example-queue", callback=ExampleConsumer().handle)

1. Start consuming (default params factory = RabbitMQ / no SSL):

python manage.py edaconsume

AmazonMQ (SSL)

Use this for AmazonMQ (or any AMQP broker that requires TLS). Connections use SSL on port 5671 via AMQConnectionParamsFactory.

Environment variables

You still need EDA_CONSUMERS_HANDLE (or --handle) so the process knows which consumers to register.

Publisher

from weni.eda.django import AMQConnectionParamsFactory
from weni.eda.eda_publisher import EDAPublisher

publisher = EDAPublisher(AMQConnectionParamsFactory)
publisher.send_message(
    {"event": "order.created", "order_id": 123},
    exchange="orders",
    routing_key="order.created",
)

AMQConnectionParamsFactory reads the AMQ_* settings and enables SSL automatically.

Consumer

Consumers and handle_consumers are identical to RabbitMQ. The only difference is which params factory you pass when starting the process:

python manage.py edaconsume \
  --params-class "weni.eda.django.AMQConnectionParamsFactory"

Event envelopes (optional)

By default send_message publishes the body as-is (backward compatible). Pass event_type to wrap the payload in a standardized envelope:

{
  "event_id": "c6b84b6c-1da4-4c4c-83b6-2c97441584c0",
  "event_type": "project.updated",
  "producer": "weni-engine",
  "timestamp": "2026-05-20T11:15:00Z",
  "data": {
    "uuid": "8e7d8a",
    "name": "Novo Nome do Projeto",
    "user_id": "owner@example.com",
    "updated_fields": ["name"]
  }
}

Publisher

publisher.send_message(
    {"uuid": "8e7d8a", "name": "Novo Nome do Projeto"},
    exchange="projects",
    routing_key="project.updated",
    event_type="project.updated",
)

Consumer

class ProjectUpdatedConsumer(EDAConsumer):
    def consume(self, message: Message):
        event = message.event()
        # event.event_id, event.event_type, event.producer, event.timestamp
        payload = event.data  # or message.data()
        self.ack()

Legacy consumers that call message.json() keep working for raw (non-envelope) messages.

Event API

Consumers reference

Message API

Consumers receive a weni.eda.messages.Message (transport-agnostic — no need to import amqp):

If consume raises, the message is rejected and the error is logged.

Channel API

handle_consumers receives a weni.eda.channels.Channel:

edaconsume flags

Useful when one project talks to both brokers (or multiple consumer groups):

python manage.py edaconsume \
  --handle "myapp.messages.handle.handle_consumers" \
  --backend "weni.eda.backends.pyamqp_flush_backend.PyAMQPFlushConnectionBackend" \
  --params-class "weni.eda.django.AMQConnectionParamsFactory"

Quick reference:

# RabbitMQ (no SSL)
python manage.py edaconsume

# AmazonMQ (SSL)
python manage.py edaconsume --params-class "weni.eda.django.AMQConnectionParamsFactory"

Buffered consumers (optional)

By default each consumer acks messages one by one. For high-throughput workloads that batch DB writes, use PyAMQPFlushConnectionBackend.

Your handle_consumers must register consumers and return an iterable of flushable objects, each exposing:

• flush() — persist and ack buffered work
• flush_interval (optional float) — max seconds between flushes (default 1.0)

from weni.eda.backends.pyamqp_flush_backend import PyAMQPFlushConnectionBackend
from weni.eda.channels import Channel
from weni.eda.django import AMQConnectionParamsFactory


def handle_consumers(channel: Channel):
    consumer = BufferedConsumer()  # exposes flush() and flush_interval
    consumer.setup(channel)        # channel.basic_qos(...) + channel.basic_consume(...)
    return [consumer]


def run():
    params = AMQConnectionParamsFactory.get_params()
    PyAMQPFlushConnectionBackend(handle_consumers).start_consuming(params)

Or via the management command:

python manage.py edaconsume \
  --backend "weni.eda.backends.pyamqp_flush_backend.PyAMQPFlushConnectionBackend" \
  --params-class "weni.eda.django.AMQConnectionParamsFactory"

Returning None (or an empty iterable) disables periodic flushing. You can also set settings.EDA_CONNECTION_BACKEND.

Both backends use Python logging for connection lifecycle and errors — configure handlers in your Django app (or Sentry) as needed.

License

This project is licensed under the Mozilla Public License 2.0. See the LICENSE file for the full text.