django-queuebie 0.6.0__tar.gz → 0.7.0__tar.gz

{django_queuebie-0.6.0 → django_queuebie-0.7.0}/CHANGES.md

@@ -1,5 +1,11 @@
 # Changelog
 
+**0.7.0** (2026-10-05)
+  * `handle_message()` returns the handled messages in the order they were processed - the initial message(s)
+    followed by every command and event raised along the way - so the caller can tell whether its command led to the
+    expected event
+  * `handle_message()` no longer empties a list passed in by the caller
+
 **0.6.0** (2026-09-09)
   * Auto-discovery now walks the whole subtree of every local Django app, so `handlers/commands` and `handlers/events`
     directories may live in sub-packages instead of only at the app root

{django_queuebie-0.6.0 → django_queuebie-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-queuebie
-Version: 0.6.0
+Version: 0.7.0
 Summary: A simple and synchronous message queue for commands and events for Django
 Project-URL: Homepage, https://github.com/ambient-innovation/django-queuebie/
 Project-URL: Documentation, https://django-queuebie.readthedocs.io/en/latest/index.html

{django_queuebie-0.6.0 → django_queuebie-0.7.0}/docs/features/getting-started.md

@@ -102,3 +102,19 @@ handle_message(
     )
 )
 ```
+
+`handle_message()` returns every message it handled, in the order they were processed: the message(s) you passed in,
+followed by all commands and events the handlers returned along the way. Use it to find out what your command led to,
+for example when a command handler can decide to do nothing and return `None`:
+
+```python
+handled = handle_message(BuyProduct(...))
+
+if any(isinstance(message, ProductBought) for message in handled):
+    messages.success(request, "Thank you for your purchase.")
+else:
+    messages.error(request, "The product could not be bought.")
+```
+
+The returned list tells you which handlers ran, not that their changes are committed. If you call `handle_message()`
+inside an outer `transaction.atomic()` block, that outer transaction can still roll everything back.

{django_queuebie-0.6.0 → django_queuebie-0.7.0}/queuebie/__init__.py

@@ -1,6 +1,6 @@
 """A simple and synchronous message queue for commands and events for Django"""
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 from queuebie.registry import MessageRegistry
 

{django_queuebie-0.6.0 → django_queuebie-0.7.0}/queuebie/runner.py

@@ -11,8 +11,16 @@ from queuebie.messages import Command, Event, Message
 from queuebie.settings import get_queuebie_strict_mode
 
 
-def handle_message(messages: Message | list[Message]) -> None:
-    queue: list[Message] = messages if isinstance(messages, list) else [messages]
+def handle_message(messages: Message | list[Message]) -> list[Message]:
+    """
+    Process the given message(s) and every message their handlers return, until the queue is drained.
+
+    Returns all handled messages in the order they were processed - the initial message(s) first, followed by
+    everything raised along the way. The caller can inspect it to learn what its command led to, e.g. whether a
+    handler returned an event or bailed out with `None`.
+    """
+    # Copy the input, so draining the queue doesn't empty the caller's list
+    queue: list[Message] = list(messages) if isinstance(messages, list) else [messages]
 
     for message in queue:
         if not isinstance(message, (Command, Event)):
@@ -21,9 +29,11 @@ def handle_message(messages: Message | list[Message]) -> None:
     # Run auto-registry
     message_registry.autodiscover()
 
+    handled: list[Message] = []
     with transaction.atomic():
         while queue:
             message = queue.pop(0)
+            handled.append(message)
             if isinstance(message, Command):
                 handler_list = message_registry.command_dict.get(message.module_path(), [])
                 block_db_access = False
@@ -34,6 +44,8 @@ def handle_message(messages: Message | list[Message]) -> None:
             new_messages = _process_message(handler_list=handler_list, message=message, block_db_access=block_db_access)
             queue.extend(new_messages)
 
+    return handled
+
 
 def _process_message(*, handler_list: list, message: [Command, Event], block_db_access: bool) -> list[Message]:
     """

{django_queuebie-0.6.0 → django_queuebie-0.7.0}/tests/test_runner.py

@@ -136,3 +136,47 @@ def test_handle_message_atomic_works(*args):
         handle_message([CreateUser(username="username"), RaiseRuntimeError(error_msg="Something is broken.")])
 
     assert User.objects.filter(username="username").exists() is False
+
+
+@pytest.mark.django_db
+def test_handle_message_returns_handled_messages_in_order():
+    command = DoSomething(my_var=1)
+
+    handled = handle_message(messages=command)
+
+    assert len(handled) == 2  # noqa: PLR2004
+    assert handled[0] is command
+    assert isinstance(handled[1], SomethingHappened)
+    assert handled[1].other_var == 2  # noqa: PLR2004
+
+
+@pytest.mark.django_db
+def test_handle_message_returns_only_initial_message_if_handler_returns_none():
+    command = CriticalCommand(my_var=1)
+
+    handled = handle_message(messages=command)
+
+    assert handled == [command]
+
+
+@pytest.mark.django_db
+def test_handle_message_returns_all_initial_messages_of_list():
+    command = DoSomething(my_var=1)
+    event = SomethingHappened(other_var=5)
+
+    handled = handle_message(messages=[command, event])
+
+    assert handled[0] is command
+    assert handled[1] is event
+    assert isinstance(handled[2], SomethingHappened)
+    assert handled[2].other_var == 2  # noqa: PLR2004
+    assert len(handled) == 3  # noqa: PLR2004
+
+
+@pytest.mark.django_db
+def test_handle_message_does_not_empty_passed_list():
+    message_list = [CriticalCommand(my_var=1)]
+
+    handle_message(messages=message_list)
+
+    assert len(message_list) == 1