A simple and synchronous message queue for commands and events for Django.

PyPI | GitHub | Full documentation

Creator & Maintainer: Ambient Digital

Features

• Split up your business logic in commands and events
• Commands are imperatives telling your system what to do, events reflect that something has happened
• Register light-weight functions via a decorator to listen to your commands and events
• Message handlers receive the context of the message (command or event), providing an explicit API
• No magic, no side effects since the queue works synchronously

import dataclasses

from queuebie.runner import handle_message
from queuebie.messages import Command, Event
from queuebie import message_registry


# Example command
@dataclasses.dataclass(kw_only=True)
class BuyProduct(Command):
    product_id: int
    customer_id: int
    price: float
    currency: str


# Example event
@dataclasses.dataclass(kw_only=True)
class ProductBought(Event):
    product_id: int
    customer_id: int


# Example handler
@message_registry.register_command(BuyProduct)
def handle_buy_product(context: BuyProduct) -> Event:
    # Here lives your business logic

    return ProductBought(
        product_id=context.product_id,
        customer_id=context.customer_id,
    )


# Start queue and process messages
handle_message(
    BuyProduct(
        product_id=product.id,
        customer_id=customer.id,
        price=12.99,
        currency="EUR",
    )
)

Installation

• Install the package via pip:

  pip install django_queuebie

  or via uv:

  uv add django_queuebie

• Add module to INSTALLED_APPS within the main django settings.py:

INSTALLED_APPS = (
    # ...
    "queuebie",
)

Publish to ReadTheDocs.io

• Fetch the latest changes in GitHub mirror and push them
• Trigger new build at ReadTheDocs.io (follow instructions in admin panel at RTD) if the GitHub webhook is not yet set up.

Preparation and building

This package uses uv for dependency management and building.

• Update documentation about new/changed functionality

• Update the CHANGES.md

• Increment version in main __init__.py

• Create pull request / merge to "main"

• This project uses uv to publish to PyPI. This will create distribution files in the dist/ directory.

  uv build

Publishing to PyPI

To publish to the production PyPI:

uv publish

To publish to TestPyPI first (recommended for testing):

uv publish --publish-url https://test.pypi.org/legacy/

You can then test the installation from TestPyPI:

uv pip install --index-url https://test.pypi.org/simple/ ambient-package-update

Maintenance

Please note that this package supports the ambient-package-update. So you don't have to worry about the maintenance of this package. This updater is rendering all important configuration and setup files. It works similar to well-known updaters like pyupgrade or django-upgrade.

To run an update, refer to the documentation page of the "ambient-package-update".