django-queuebie 0.1.0__tar.gz → 0.2.0__tar.gz

django_queuebie-0.2.0/.ambient-package-update/templates/snippets/content.tpl

@@ -0,0 +1,53 @@
+## 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
+
+```python
+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",
+    )
+)
+```

{django_queuebie-0.1.0 → django_queuebie-0.2.0}/.gitignore

@@ -156,5 +156,3 @@ _build
 
 # Test databases
 *.sqlite
-
-

django_queuebie-0.2.0/CHANGES.md

@@ -0,0 +1,7 @@
+# Changelog
+
+* *0.2.0* (2025-03-17)
+  * Extend strict mode to prohibit event (!) handlers to talk to the database
+
+* *0.1.0* (2025-01-29)
+  * Project init

{django_queuebie-0.1.0 → django_queuebie-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-queuebie
-Version: 0.1.0
+Version: 0.2.0
 Summary: Simple message queue for commands and events (CQRS)
 Author-email: Ambient Digital <hello@ambient.digital>
 Description-Content-Type: text/markdown
@@ -65,6 +65,52 @@ A simple message queue for commands and events (CQRS) for Django.
 * 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
 
+```python
+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:

{django_queuebie-0.1.0 → django_queuebie-0.2.0}/README.md

@@ -21,6 +21,52 @@ A simple message queue for commands and events (CQRS) for Django.
 * 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
 
+```python
+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:

django_queuebie-0.2.0/docs/features/motivation.md

@@ -0,0 +1,30 @@
+# Motivation
+
+You might wonder what's the USP for this package. Messages (event) queues are usually async and use a broker, etc.
+
+The main goal is to provide a way to separate your domains in Django and reduce coupling between domains or Django apps.
+
+So why should you use "django-queuebie"?
+
+* Thinking in commands and events splits up your business logic from one big chunk to manageable sizes
+* Handlers are function-based with a defined input (the context), they are predictable and easy to test
+* Decoupling different parts of your application by listening to events instead of imperative programming
+* Avoid putting business logic in your view layer since it has to live inside a handler function
+* Creates an explicit pattern for connecting services (places of different business logic) instead of chaining them
+  individually
+
+# Why not Django signals?
+
+The reader might think "Hey, sync queues in Django? I already have this!" — and that's true, somehow.
+
+The key differences are mostly on a semantic level.
+
+First, commands and events are a concept that doesn't exist for Django signals. They provide a proven way of separating
+your business logic, and in addition, provide a basis for discussion with non-technical folks.
+
+Furthermore, queuebie messages (commands and events) don't belong to a model. Models represent the way you store your
+data. That's not necessarily the best way to structure your custom logic. So by using signals, you're strongly primed to
+think in models, meaning database structure, and not in domain concerns.
+
+Messages provide an explicit context via a dataclass which can be interpreted as an explicit internal API to communicate
+between your domains. That's a huge plus since explicit is better than implicit.

{django_queuebie-0.1.0 → django_queuebie-0.2.0}/docs/features/settings.md

@@ -33,8 +33,8 @@ Take care to use the same name in the logging configuration in your Django setti
 
 ## QUEUEBIE_STRICT_MODE
 
-Queuebie enforces by default that commands are not used outside its domain (aka Django app). If you want to skip that
-restriction for whatever reason, you can do so.
+Queuebie enforces by default that commands are not used outside its domain (aka Django app) and event handlers don't
+talk to the database. If you want to skip that restriction for whatever reason, you can do so.
 
 ```python
 QUEUEBIE_STRICT_MODE = False

{django_queuebie-0.1.0 → django_queuebie-0.2.0}/pyproject.toml

@@ -93,8 +93,8 @@ lint.select = [
     "INP"      # Ban PEP-420 implicit namespace packages
 ]
 lint.ignore = [
-    'TD002', # Missing author in TODO
-    'TD003', # Missing issue link on the line following this TODO
+    "TD002", # Missing author in TODO
+    "TD003", # Missing issue link on the line following this TODO
 ]
 
 # Allow autofix for all enabled rules (when `--fix`) is provided.
@@ -179,26 +179,23 @@ line-ending = "auto"
   # Allow seemingly unused imports
   "F401",
 ]
-
 "**/tests/**/test_*.py" = [
   # Allow boolean positional params in tests (for assertIs())
   "FBT003",
 ]
-
 "scripts/*.py" = [
   # Checks for packages that are missing an __init__.py file
   "INP001",
 ]
-
 ".ambient-package-update/*.py" = [
   # Checks for packages that are missing an __init__.py file
   "INP001",
 ]
-
 "docs/*.py" = [
   # Checks for packages that are missing an __init__.py file
   "INP001",
 ]
+
 [tool.tox]
 legacy_tox_ini = """
 [testenv]

{django_queuebie-0.1.0 → django_queuebie-0.2.0}/queuebie/__init__.py

@@ -1,6 +1,6 @@
 """Simple message queue for commands and events (CQRS)"""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 from queuebie.registry import MessageRegistry
 

django_queuebie-0.2.0/queuebie/database_blocker.py

@@ -0,0 +1,25 @@
+from unittest.mock import patch
+
+from django.db import connections
+
+
+class DatabaseAccessDeniedError(RuntimeError):
+    def __init__(self):
+        super().__init__("Database access is disabled in this context.")
+
+
+class BlockDatabaseAccess:
+    def __enter__(self):
+        # Patcht alle aktiven DB-Verbindungen, sodass jede Query fehlschlägt
+        self.patches = [
+            patch.object(connections[alias], "cursor", side_effect=self._raise_error) for alias in connections
+        ]
+        for p in self.patches:
+            p.start()
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        for p in self.patches:
+            p.stop()
+
+    def _raise_error(self, *args, **kwargs):
+        raise DatabaseAccessDeniedError()

{django_queuebie-0.1.0 → django_queuebie-0.2.0}/queuebie/runner.py

@@ -1,11 +1,14 @@
 import importlib
+from contextlib import nullcontext
 
 from django.db import transaction
 
 from queuebie import message_registry
+from queuebie.database_blocker import BlockDatabaseAccess
 from queuebie.exceptions import InvalidMessageTypeError
 from queuebie.logger import get_logger
 from queuebie.messages import Command, Event, Message
+from queuebie.settings import get_queuebie_strict_mode
 
 
 def handle_message(messages: Message | list[Message]) -> None:
@@ -18,25 +21,27 @@ def handle_message(messages: Message | list[Message]) -> None:
     # Run auto-registry
     message_registry.autodiscover()
 
-    handler_list = []
     while queue:
         message = queue.pop(0)
         if isinstance(message, Command):
             handler_list = message_registry.command_dict.get(message.module_path(), [])
+            block_db_access = False
         else:
             handler_list = message_registry.event_dict.get(message.module_path(), [])
+            block_db_access = True if get_queuebie_strict_mode() else False
 
-        new_messages = _process_message(handler_list=handler_list, message=message)
+        new_messages = _process_message(handler_list=handler_list, message=message, block_db_access=block_db_access)
         queue.extend(new_messages)
 
 
-def _process_message(*, handler_list: list, message: [Command, Event]):
+def _process_message(*, handler_list: list, message: [Command, Event], block_db_access: bool) -> list[Message]:
     """
     Handler to process messages of type "Command"
     """
     logger = get_logger()
     messages = []
 
+    # TODO: should the whole chain be atomic and not just the handler?
     with transaction.atomic():
         for handler in handler_list:
             try:
@@ -45,7 +50,8 @@ def _process_message(*, handler_list: list, message: [Command, Event]):
                 )
                 module = importlib.import_module(handler["module"])
                 handler_function = getattr(module, handler["name"])
-                handler_messages = handler_function(context=message) or []
+                with BlockDatabaseAccess() if block_db_access else nullcontext():
+                    handler_messages = handler_function(context=message) or []
                 handler_messages = handler_messages if isinstance(handler_messages, list) else [handler_messages]
                 if len(handler_messages) > 0:
                     messages.extend(handler_messages)

{django_queuebie-0.1.0 → django_queuebie-0.2.0}/testapp/handlers/commands/testapp.py

@@ -1,10 +1,12 @@
+from random import randint
+
 from django.contrib.auth.models import User
 
 from queuebie import message_registry
 from queuebie.logger import get_logger
 from queuebie.messages import Event
-from testapp.messages.commands.my_commands import CriticalCommand, DoSomething
-from testapp.messages.events.my_events import SomethingHappened
+from testapp.messages.commands.my_commands import CriticalCommand, DoSomething, PersistSomething
+from testapp.messages.events.my_events import SomethingHappened, SomethingHappenedThatWantsToBePersisted
 
 
 @message_registry.register_command(command=DoSomething)
@@ -14,6 +16,13 @@ def handle_my_command(*, context: DoSomething) -> list[Event] | Event:
     return SomethingHappened(other_var=context.my_var + 1)
 
 
+@message_registry.register_command(command=PersistSomething)
+def handle_something_that_needs_persistance(*, context: PersistSomething) -> Event:
+    User.objects.create(username="testuser" + str(randint(1, 100)))
+
+    return SomethingHappenedThatWantsToBePersisted(any_var=1)
+
+
 @message_registry.register_command(command=CriticalCommand)
 def handle_critical_command(*, context: CriticalCommand) -> None:
     if context.my_var == 0:

django_queuebie-0.2.0/testapp/handlers/events/testapp.py

@@ -0,0 +1,20 @@
+import random
+
+from django.contrib.auth.models import User
+
+from queuebie import message_registry
+from queuebie.logger import get_logger
+from queuebie.messages import Command
+from testapp.messages.events.my_events import SomethingHappened, SomethingHappenedThatWantsToBePersistedViaEvent
+
+
+@message_registry.register_event(event=SomethingHappened)
+def handle_my_event(*, context: SomethingHappened) -> list[Command] | Command:
+    logger = get_logger()
+    logger.info(f'Event "SomethingHappened" executed with other_var={context.other_var}.')
+    return []
+
+
+@message_registry.register_event(event=SomethingHappenedThatWantsToBePersistedViaEvent)
+def handle_event_and_try_to_persist_something(*, context: SomethingHappenedThatWantsToBePersistedViaEvent):
+    User.objects.create(username="testuser" + str(random.randint(1, 100)))

{django_queuebie-0.1.0 → django_queuebie-0.2.0}/testapp/messages/commands/my_commands.py

@@ -16,3 +16,8 @@ class CriticalCommand(Command):
 @dataclass(kw_only=True)
 class SameNameCommand(Command):
     name: str
+
+
+@dataclass(kw_only=True)
+class PersistSomething(Command):
+    any_var: str

django_queuebie-0.2.0/testapp/messages/events/my_events.py

@@ -0,0 +1,18 @@
+import dataclasses
+
+from queuebie.messages import Event
+
+
+@dataclasses.dataclass(kw_only=True)
+class SomethingHappened(Event):
+    other_var: int
+
+
+@dataclasses.dataclass(kw_only=True)
+class SomethingHappenedThatWantsToBePersisted(Event):
+    any_var: int
+
+
+@dataclasses.dataclass(kw_only=True)
+class SomethingHappenedThatWantsToBePersistedViaEvent(Event):
+    any_var: int

django_queuebie-0.2.0/tests/test_database_blocker.py

@@ -0,0 +1,17 @@
+import pytest
+from django.contrib.auth.models import User
+
+from queuebie.database_blocker import BlockDatabaseAccess, DatabaseAccessDeniedError
+
+
+def test_block_database_access_use_db():
+    with pytest.raises(DatabaseAccessDeniedError, match="Database access is disabled in this context."):
+        with BlockDatabaseAccess():
+            User.objects.get(pk=1)
+
+
+def test_block_database_access_dont_use_db():
+    with BlockDatabaseAccess():
+        user = User(pk=1)
+
+    assert user.id == 1

{django_queuebie-0.1.0 → django_queuebie-0.2.0}/tests/test_registry.py

@@ -10,7 +10,10 @@ from queuebie import MessageRegistry
 from queuebie.exceptions import RegisterOutOfScopeCommandError
 from queuebie.settings import get_queuebie_cache_key
 from testapp.messages.commands.my_commands import CriticalCommand, DoSomething
-from testapp.messages.events.my_events import SomethingHappened
+from testapp.messages.events.my_events import (
+    SomethingHappened,
+    SomethingHappenedThatWantsToBePersistedViaEvent,
+)
 from tests.helpers.commands import DoTestThings
 
 
@@ -121,7 +124,7 @@ def test_message_autodiscover_regular():
     message_registry.autodiscover()
 
     # Assert one command registered
-    assert len(message_registry.command_dict) == 2  # noqa: PLR2004
+    assert len(message_registry.command_dict) == 3  # noqa: PLR2004
     assert DoSomething.module_path() in message_registry.command_dict.keys()
     assert CriticalCommand.module_path() in message_registry.command_dict.keys()
 
@@ -132,11 +135,12 @@ def test_message_autodiscover_regular():
         "name": "handle_my_command",
     } == message_registry.command_dict[DoSomething.module_path()][0]
 
-    # Assert one event registered
-    assert len(message_registry.event_dict) == 1
+    # Assert two events registered
+    assert len(message_registry.event_dict) == 2  # noqa: PLR2004
     assert SomethingHappened.module_path() in message_registry.event_dict.keys()
+    assert SomethingHappenedThatWantsToBePersistedViaEvent.module_path() in message_registry.event_dict.keys()
 
-    # Assert one handler registered
+    # Assert two handlers registered
     assert len(message_registry.event_dict[SomethingHappened.module_path()]) == 1
     assert {"module": "testapp.handlers.events.testapp", "name": "handle_my_event"} == message_registry.event_dict[
         SomethingHappened.module_path()

{django_queuebie-0.1.0 → django_queuebie-0.2.0}/tests/test_runner.py

@@ -3,12 +3,17 @@ from unittest import mock
 
 import pytest
 from django.contrib.auth.models import User
+from django.test import override_settings
 
 from queuebie import MessageRegistry
+from queuebie.database_blocker import DatabaseAccessDeniedError
 from queuebie.exceptions import InvalidMessageTypeError
 from queuebie.runner import _process_message, handle_message
-from testapp.messages.commands.my_commands import CriticalCommand, DoSomething, SameNameCommand
-from testapp.messages.events.my_events import SomethingHappened
+from testapp.messages.commands.my_commands import CriticalCommand, DoSomething, PersistSomething, SameNameCommand
+from testapp.messages.events.my_events import (
+    SomethingHappened,
+    SomethingHappenedThatWantsToBePersistedViaEvent,
+)
 
 
 @pytest.mark.django_db
@@ -65,6 +70,23 @@ def test_handle_message_pass_invalid_type():
         handle_message(messages=MessageRegistry())
 
 
+@pytest.mark.django_db
+def test_handle_message_command_with_db_hit_is_ok():
+    handle_message(messages=[PersistSomething(any_var="noodle")])
+
+
+@pytest.mark.django_db
+def test_handle_message_event_with_db_hit_fails():
+    with pytest.raises(DatabaseAccessDeniedError, match="Database access is disabled in this context"):
+        handle_message(messages=[SomethingHappenedThatWantsToBePersistedViaEvent(any_var=1)])
+
+
+@pytest.mark.django_db
+@override_settings(QUEUEBIE_STRICT_MODE=False)
+def test_handle_message_event_with_db_hit_ok_when_not_on_strict_mode(*args):
+    handle_message(messages=[SomethingHappenedThatWantsToBePersistedViaEvent(any_var=1)])
+
+
 @pytest.mark.django_db
 @mock.patch("queuebie.registry.get_queuebie_strict_mode", return_value=False)
 @mock.patch.object(MessageRegistry, "autodiscover")
@@ -112,6 +134,6 @@ def test_process_message_atomic_works(mocked_handle_command, *args):
     message = DoSomething(my_var=1)
 
     with pytest.raises(RuntimeError, match="Something is broken."):
-        _process_message(handler_list=handler_list, message=message)
+        _process_message(handler_list=handler_list, message=message, block_db_access=False)
 
     assert User.objects.filter(username="username").exists() is False

django_queuebie-0.1.0/.ambient-package-update/templates/snippets/content.tpl

@@ -1,7 +0,0 @@
-## 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

django_queuebie-0.1.0/CHANGES.md

@@ -1,4 +0,0 @@
-# Changelog
-
-* *0.1.0* (2025-01-29)
-  * Project init

django_queuebie-0.1.0/docs/features/motivation.md

@@ -1,14 +0,0 @@
-# Motivation
-
-You might wonder what's the USP for this package. Messages (event) queues are usually async and use a broker, etc.
-
-The main goal is to provide a way to separate your domains in Django and reduce coupling between domains or Django apps.
-
-So why should you use "django-queuebie"?
-
-* Thinking in commands and events splits up your business logic from one big chunk to manageable sizes
-* Handlers are function-based with a defined input (the context), they are predictable and easy to test
-* Decoupling different parts of your application by listening to events instead of imperative programming
-* Avoid putting business logic in your view layer since it has to live inside a handler function
-* Creates an explicit pattern for connecting services (places of different business logic) instead of chaining them
-  individually

django_queuebie-0.1.0/testapp/handlers/events/testapp.py

@@ -1,11 +0,0 @@
-from queuebie import message_registry
-from queuebie.logger import get_logger
-from queuebie.messages import Command
-from testapp.messages.events.my_events import SomethingHappened
-
-
-@message_registry.register_event(event=SomethingHappened)
-def handle_my_event(*, context: SomethingHappened) -> list[Command] | Command:
-    logger = get_logger()
-    logger.info(f'Event "SomethingHappened" executed with other_var={context.other_var}.')
-    return []

django_queuebie-0.1.0/testapp/messages/events/my_events.py

@@ -1,8 +0,0 @@
-import dataclasses
-
-from queuebie.messages import Event
-
-
-@dataclasses.dataclass(kw_only=True)
-class SomethingHappened(Event):
-    other_var: int