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

{django_queuebie-0.4.1 → django_queuebie-0.6.0}/.github/workflows/quality-gate.yml

@@ -26,18 +26,14 @@ jobs:
     strategy:
       matrix:
         python-version: ['3.11', '3.12', '3.13', '3.14', ]
-        django-version: ['42', '52', '60', ]
+        django-version: ['52', '60', '61', ]
 
         # Exclude Python/Django combinations that are not supported upstream.
         exclude:
           - python-version: '3.11'
             django-version: 60
-          - python-version: '3.13'
-            django-version: 42
-          - python-version: '3.14'
-            django-version: 42
-          - python-version: '3.14'
-            django-version: 52
+          - python-version: '3.11'
+            django-version: 61
 
     steps:
       - uses: actions/checkout@v6

{django_queuebie-0.4.1 → django_queuebie-0.6.0}/.pre-commit-config.yaml

@@ -3,7 +3,7 @@
 
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.8
+    rev: v0.16.4
     hooks:
       # Run the Ruff formatter.
       - id: ruff-format
@@ -16,7 +16,7 @@ repos:
     hooks:
       - id: blacken-docs
         additional_dependencies:
-        - black==25.9.0
+        - black==26.5.1
         files: '(?:README\.md|\.ambient-package-update\/templates\/snippets\/.*\.tpl|docs\/.*\.(?:md|rst))'
 
   - repo: https://github.com/asottile/pyupgrade
@@ -26,16 +26,16 @@ repos:
         args: [ --py311-plus ]
 
   - repo: https://github.com/adamchainz/django-upgrade
-    rev: 1.30.0
+    rev: 1.32.0
     hooks:
       - id: django-upgrade
-        args: [--target-version, "4.2"]
+        args: [--target-version, "5.2"]
 
   - repo: https://github.com/adamchainz/djade-pre-commit
     rev: 1.9.0
     hooks:
     -   id: djade
-        args: [--target-version, "4.2"]
+        args: [--target-version, "5.2"]
         exclude: |
           (?x)^(
             charts/.*

django_queuebie-0.6.0/CHANGES.md

@@ -0,0 +1,86 @@
+# Changelog
+
+**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
+  * Auto-discovery skips the directory names which occur inside Django apps but never hold handlers -
+    `__pycache__`, `fixtures`, `locale`, `media`, `migrations`, `node_modules`, `static`, `templates` and `tests`.
+    `QUEUEBIE_DEFAULT_EXCLUDED_DIRECTORIES` holds that list and can be overwritten
+  * Added the setting `QUEUEBIE_EXCLUDED_DIRECTORIES` for project-specific directory names. It is added to the list
+    above instead of replacing it
+  * **Breaking change:** Strict mode compares the package owning the `handlers/` or `messages/` directory instead of
+    the Django app. Nested layouts get the boundary enforced they always described, and two cases which used to pass
+    the check unconditionally are now validated:
+    * handlers and commands living outside any installed Django app
+    * commands living inside an app but outside a `messages/` directory - a command in, say,
+      `my_app/domain/orders/commands.py` has no owning `messages/` directory, so its scope is its full module path,
+      which only a handler in that same module can share. Registering a handler from anywhere else raises
+      `RegisterOutOfScopeCommandError` at import time. Move such commands into a `messages/` directory or turn
+      strict mode off
+  * **Breaking change:** Replaced `queuebie.utils.is_part_of_app()` with `queuebie.utils.is_same_scope()` and
+    `queuebie.utils.message_scope()`
+  * **Breaking change:** `RegisterOutOfScopeCommandError` now names both scopes instead of only the command and the
+    handler, so a mismatch between two sub-packages of the same app can be read off the message
+  * Handlers are now registered in a deterministic order - the handler package first, then its modules sorted by
+    name. Where a message has more than one handler, and since the bus is synchronous, that order is observable and
+    may differ from the one the file system happened to yield before
+
+**0.5.0** (2026-08-27)
+  * Added support for Django 6.1
+  * **Breaking change:** Dropped support for Django 4.2, whose extended support ended in April 2026
+  * Updated the linting and CI setup to the current ambient-package-update template
+
+**0.4.1** (2026-07-03)
+  * Updated company and maintainer information to "Beyonder Deutschland"
+
+**0.4.0** (2026-07-03)
+  * **Breaking change:** Dropped support for Python 3.10 (nearing end-of-life in October 2026)
+  * Added support for Python 3.14
+  * Added native uv support to the rendered Read the Docs configuration
+  * Replaced the unmaintained "m2r2" documentation dependency with "sphinx-mdinclude"
+  * Added a Code of Conduct, issue templates and a pull request template to rendered packages
+  * Made the single-version CI and Read the Docs jobs track the newest supported Python version
+  * Bumped rendered single-version jobs to Python 3.14
+  * Added a cache suffix to the uv setup step to avoid CI cache namespace conflicts
+  * Excluded unsupported Python/Django combinations (Python 3.14 with Django 4.2 and 5.2) from the rendered CI matrix
+  * Fixed the rendered ruff target-version to track the minimum supported Python (matching requires-python) instead of the newest
+  * Removed the stale .md source suffix from the rendered Sphinx config, since sphinx-mdinclude provides only the mdinclude directive (not a Markdown source parser)
+
+**0.3.10** (2026-03-30)
+  * Maintenance updates via ambient-package-update
+
+**0.3.9** (2026-03-30)
+  * Maintenance updates via ambient-package-update
+
+**0.3.8** (2025-12-11)
+  * Maintenance updates via ambient-package-update
+
+**0.3.7** (2025-10-15)
+  * Maintenance updates via ambient-package-update
+
+**0.3.6** (2025-10-10)
+  * Maintenance updates via ambient-package-update
+
+**0.3.5** (2025-10-09)
+  * Maintenance updates via ambient-package-update
+
+**0.3.4** (2025-05-29)
+  * Maintenance updates via ambient-package-update
+
+**0.3.3** (2025-04-03)
+  * Clarified package tagline
+
+**0.3.2** (2025-04-03)
+  * Maintenance updates via ambient-package-update
+
+* *0.3.1* (2025-03-19)
+  * Added a paranoid-ish test to check that the import logic isn't breaking any testing functionality
+
+* *0.3.0* (2025-03-19)
+  * The whole queue iteration now is wrapped in a transaction atomic
+
+* *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.4.1 → django_queuebie-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: django-queuebie
-Version: 0.4.1
+Version: 0.6.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
@@ -33,9 +33,9 @@ License-File: LICENSE.md
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Web Environment
 Classifier: Framework :: Django
-Classifier: Framework :: Django :: 4.2
 Classifier: Framework :: Django :: 5.2
 Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
@@ -48,7 +48,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Utilities
 Requires-Python: >=3.11
-Requires-Dist: django>=4.2
+Requires-Dist: django>=5.2
 Provides-Extra: dev
 Requires-Dist: ambient-package-update; extra == 'dev'
 Requires-Dist: keyring~=25.7; extra == 'dev'

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

@@ -52,15 +52,21 @@ class ProductBought(Event):
 Here's an example of a simple handler function. By design, these are functions and not objects to keep it as simple,
 understandable and testable as possible.
 
-They have to live inside your Django app in `my_app/handlers/commands/[your_filename].py` or
-respectively `handlers/events/[your_filename].py` for the auto-discovery to find it.
+They have to live in a `handlers/commands/[your_filename].py` or respectively `handlers/events/[your_filename].py`
+directory for the auto-discovery to find them. Such a directory may sit at any depth below the root of a Django app,
+so `my_app/handlers/commands/product.py` and `my_app/shipping/handlers/commands/product.py` both work. Directories
+listed in `QUEUEBIE_EXCLUDED_DIRECTORIES` are skipped.
 
 A handler becomes a handler when three conditions are met:
 
 * The function is registered as such via one of the two decorators `register_command` and `register_event`
-* The function lives within `my_app/handlers/commands/` or `my_app/handlers/events/`
+* The function lives within a `handlers/commands/` or `handlers/events/` directory inside one of your Django apps
 * The function takes a message (command or event) and returns optionally the other type of message (event or command).
 
+The package owning that `handlers/` directory is the handler's *scope*. In strict mode, a command handler may only
+handle commands whose `messages/` directory has the same owner. See
+[QUEUEBIE_STRICT_MODE](settings.md#queuebie_strict_mode) for the details.
+
 ```python
 # my_app/handlers/commands/product.py
 from queuebie import message_registry

django_queuebie-0.6.0/docs/features/settings.md

@@ -0,0 +1,106 @@
+# Settings
+
+## QUEUEBIE_APP_BASE_PATH
+
+Queuebie needs to know where your project lives to detect local Django apps. It defaults to `settings.BASE_PATH`
+but you can overwrite it with a string or a `Pathlib` object.
+
+```python
+from pathlib import Path
+
+QUEUEBIE_APP_BASE_PATH = Path(__file__).resolve(strict=True).parent
+```
+
+## QUEUEBIE_CACHE_KEY
+
+Queuebie will cache all detected message handlers in Django's default cache. The default cache key is "queuebie".
+You can overwrite it with this variable.
+
+```python
+QUEUEBIE_CACHE_KEY = "my_very_special_cache_key"
+```
+
+## QUEUEBIE_LOGGER_NAME
+
+Queuebie defines a Django logger with the default name "queuebie". If you want to rename that logger, you can set this
+variable.
+
+```python
+QUEUEBIE_LOGGER_NAME = "my_very_special_logger"
+```
+
+Take care to use the same name in the logging configuration in your Django settings.
+
+## QUEUEBIE_EXCLUDED_DIRECTORIES
+
+Queuebie searches the whole subtree of every local Django app for `handlers/commands` and `handlers/events`
+directories. Directory names listed here are skipped, which keeps handler-shaped trees that are not meant to be
+registered - most notably a test suite mirroring your handler layout - out of the auto-discovery.
+
+Whatever you put here is **added to** the built-in list below, so you only name what is special about your project.
+
+```python
+QUEUEBIE_EXCLUDED_DIRECTORIES = {"vendor"}
+```
+
+A directory is skipped when any part of its path below the app root matches one of these names.
+
+## QUEUEBIE_DEFAULT_EXCLUDED_DIRECTORIES
+
+The built-in list of directory names which occur inside Django apps but never hold message handlers:
+
+```python
+QUEUEBIE_DEFAULT_EXCLUDED_DIRECTORIES = {
+    "__pycache__",
+    "fixtures",
+    "locale",
+    "media",
+    "migrations",
+    "node_modules",
+    "static",
+    "templates",
+    "tests",
+}
+```
+
+You can overwrite it, but you probably don't want to - use `QUEUEBIE_EXCLUDED_DIRECTORIES` to add names and leave
+this one alone. Overwriting is the way to get one of these directories searched after all, for instance if your
+handlers really do live under `tests/`. Note that an overwritten list is frozen: names a later queuebie release adds
+to the built-in list won't reach your project.
+
+## QUEUEBIE_STRICT_MODE
+
+Queuebie enforces by default that commands are not used outside their scope 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
+```
+
+### What a scope is
+
+The scope of a message or a handler is the package which owns the `handlers/` or `messages/` directory the module
+lives in - the last such directory in the module path, so a package legitimately called `messages` further up doesn't
+truncate the scope.
+
+| Module                                             | Scope                    |
+|----------------------------------------------------|--------------------------|
+| `apps.shipping.messages.commands.shipment`           | `apps.shipping`          |
+| `apps.shipping.handlers.commands.shipment`           | `apps.shipping`          |
+| `apps.logistics.billing.handlers.commands.invoice`   | `apps.logistics.billing` |
+
+A module which lives in neither directory has no owning package, so its full module path becomes its scope. Only a
+handler in that very module shares it; registering one from anywhere else raises `RegisterOutOfScopeCommandError` at
+import time. Keep your commands in a `messages/` directory.
+
+Put them in a module *inside* that directory - `messages/commands/orders.py` - and not in `messages/__init__.py`
+itself. A class defined there reports `apps.shipping.messages` as its module, which is indistinguishable from a
+module called `messages.py`, so the last path segment is never treated as the marker and the scope ends up as
+`apps.shipping.messages` rather than `apps.shipping`. Every handler in `apps/shipping/handlers/commands/` then fails
+the strict-mode check.
+
+A command handler may only handle commands of its own scope. For the common layout - one `handlers/` directory at the
+root of a Django app - the scope is that app, so nothing changes. If you organise a Django app into sub-packages, the
+boundary follows those sub-packages instead.
+
+Event handlers are deliberately not scope-checked: crossing scopes is what events are for.

{django_queuebie-0.4.1 → django_queuebie-0.6.0}/pyproject.toml

@@ -12,9 +12,9 @@ classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: Web Environment",
     "Framework :: Django",
-    "Framework :: Django :: 4.2",
     "Framework :: Django :: 5.2",
     "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Natural Language :: English",
@@ -32,7 +32,7 @@ description = "A simple and synchronous message queue for commands and events fo
 license = {"file" = "LICENSE.md"}
 requires-python = ">=3.11"
 dependencies = [
-    'Django>=4.2',
+    'Django>=5.2',
 ]
 
 [project.optional-dependencies]
@@ -196,26 +196,28 @@ line-ending = "auto"
 
 [tool.tox]
 requires = ["tox>=4", "tox-uv>=1.0.0"]
-env_list = ["django42", "django52", "django60", ]
+env_list = ["django52", "django60", "django61", ]
 
 [tool.tox.env_run_base]
 # Django deprecation overview: https://www.djangoproject.com/download/
 package = "wheel"
 wheel_build_env = ".pkg"
+# This runner syncs from the lockfile and ignores "deps", so every environment below
+# installs its matrix Django version on top of the synced environment.
 runner = "uv-venv-lock-runner"
 extras = ["dev", ]
 commands = [
     ["pytest", "--cov=queuebie", "--cov-report=term", "--cov-report=xml", "--ds", "settings", "tests"]
 ]
 
-[tool.tox.env.django42]
-deps = ["Django==4.2.*"]
-
 [tool.tox.env.django52]
-deps = ["Django==5.2.*"]
+commands_pre = [["uv", "pip", "install", "Django==5.2.*"]]
 
 [tool.tox.env.django60]
-deps = ["Django==6.0.*"]
+commands_pre = [["uv", "pip", "install", "Django==6.0.*"]]
+
+[tool.tox.env.django61]
+commands_pre = [["uv", "pip", "install", "Django==6.1.*"]]
 
 [tool.tox.gh_actions.python]
 "3.11" = "py311"

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

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

django_queuebie-0.6.0/queuebie/exceptions.py

@@ -0,0 +1,49 @@
+from django.core.exceptions import ImproperlyConfigured
+
+# Unpickling replays an exception's rendered message through "args", so every exception below accepts it
+# positionally and renders a new one only when constructed without. Frameworks which ship exceptions
+# between processes - Celery, a multiprocessing test runner - rely on that.
+
+
+class RegisterWrongMessageTypeError(TypeError):
+    def __init__(self, *args, message_name: str = "", decoratee_name: str = ""):
+        if not args:
+            args = (
+                f'Trying to register message function of wrong type: "{message_name}" on handler "{decoratee_name}".',
+            )
+
+        super().__init__(*args)
+
+
+class RegisterOutOfScopeCommandError(TypeError):
+    def __init__(
+        self,
+        *args,
+        message_name: str = "",
+        message_scope: str = "",
+        decoratee_name: str = "",
+        decoratee_scope: str = "",
+    ):
+        if not args:
+            args = (
+                f'Command "{message_name}" (scope "{message_scope}") cannot be handled by '
+                f'"{decoratee_name}" (scope "{decoratee_scope}").',
+            )
+
+        super().__init__(*args)
+
+
+class InvalidMessageTypeError(TypeError):
+    def __init__(self, *args, class_name: str = ""):
+        if not args:
+            args = (f'"{class_name}" is not an Event or Command',)
+
+        super().__init__(*args)
+
+
+class InvalidExcludedDirectoriesError(ImproperlyConfigured):
+    def __init__(self, *args, setting_name: str = "QUEUEBIE_EXCLUDED_DIRECTORIES"):
+        if not args:
+            args = (f"{setting_name} has to be a collection of directory names, not a string.",)
+
+        super().__init__(*args)

{django_queuebie-0.4.1 → django_queuebie-0.6.0}/queuebie/registry.py

@@ -11,8 +11,15 @@ from django.core.cache import cache
 from queuebie.exceptions import RegisterOutOfScopeCommandError, RegisterWrongMessageTypeError
 from queuebie.logger import get_logger
 from queuebie.messages import Command, Event
-from queuebie.settings import get_queuebie_app_base_path, get_queuebie_cache_key, get_queuebie_strict_mode
-from queuebie.utils import is_part_of_app, unique_append_to_inner_list
+from queuebie.settings import (
+    get_queuebie_app_base_path,
+    get_queuebie_cache_key,
+    get_queuebie_excluded_directories,
+    get_queuebie_strict_mode,
+)
+from queuebie.utils import HANDLERS_DIRECTORY_NAME, is_same_scope, message_scope, unique_append_to_inner_list
+
+MESSAGE_TYPE_DIRECTORY_NAMES = ("commands", "events")
 
 
 @dataclasses.dataclass(kw_only=True)
@@ -44,8 +51,13 @@ class MessageRegistry:
             if not (issubclass(command, Command)):
                 raise RegisterWrongMessageTypeError(message_name=command.__name__, decoratee_name=decoratee.__name__)
 
-            if get_queuebie_strict_mode() and not is_part_of_app(function=decoratee, class_type=command):
-                raise RegisterOutOfScopeCommandError(message_name=command.__name__, decoratee_name=decoratee.__name__)
+            if get_queuebie_strict_mode() and not is_same_scope(function=decoratee, class_type=command):
+                raise RegisterOutOfScopeCommandError(
+                    message_name=command.__name__,
+                    message_scope=message_scope(module_path=command.__module__),
+                    decoratee_name=decoratee.__name__,
+                    decoratee_scope=message_scope(module_path=decoratee.__module__),
+                )
 
             # Add decoratee to dependency list
             function_definition = dataclasses.asdict(
@@ -86,7 +98,7 @@ class MessageRegistry:
 
         return decorator
 
-    def autodiscover(self) -> None:  # noqa: C901
+    def autodiscover(self) -> None:
         """
         Detects message registries which have been registered via the "register_*" decorator.
         """
@@ -101,6 +113,8 @@ class MessageRegistry:
         project_path = get_queuebie_app_base_path()
         logger = get_logger()
 
+        excluded_directories = get_queuebie_excluded_directories()
+
         for app_config in apps.get_app_configs():
             app_path = Path(app_config.path).resolve()
 
@@ -108,21 +122,23 @@ class MessageRegistry:
             if project_path not in app_path.parents:
                 continue
 
-            for message_type in ("commands", "events"):
-                try:
-                    for module in os.listdir(app_path / "handlers" / message_type):
-                        if module[-3:] != ".py":
-                            continue
-                        module_name = module.replace(".py", "")
-                        module_path = f"{app_config.name}.handlers.{message_type}.{module_name}"
-                        sys_module = sys.modules.get(module_path)
-                        if sys_module:
-                            importlib.reload(sys_module)
-                        else:
-                            importlib.import_module(module_path)
-                        logger.debug(f'"{module_path}" imported.')
-                except FileNotFoundError:
-                    pass
+            for directory, directory_names, file_names in os.walk(app_path):
+                # Excluded directories are pruned from the walk so their subtrees are never visited
+                directory_names[:] = sorted(name for name in directory_names if name not in excluded_directories)
+
+                current_path = Path(directory)
+                if (
+                    current_path.name not in MESSAGE_TYPE_DIRECTORY_NAMES
+                    or current_path.parent.name != HANDLERS_DIRECTORY_NAME
+                ):
+                    continue
+
+                package_path = f"{app_config.name}.{'.'.join(current_path.relative_to(app_path).parts)}"
+
+                # Importing the package covers handlers registered in its "__init__.py"
+                self._import_handler_module(module_path=package_path)
+                for file_name in sorted(name for name in file_names if name.endswith(".py") and name != "__init__.py"):
+                    self._import_handler_module(module_path=f"{package_path}.{Path(file_name).stem}")
 
         # Log to shell which functions have been detected
         logger.debug("Message autodiscovery running for commands...")
@@ -139,6 +155,18 @@ class MessageRegistry:
         # Update cache
         cache.set(get_queuebie_cache_key(), json.dumps({"commands": self.command_dict, "events": self.event_dict}))
 
+    def _import_handler_module(self, *, module_path: str) -> None:
+        """
+        Imports a module containing message handlers, reloading it if it was imported before.
+        """
+        sys_module = sys.modules.get(module_path)
+        if sys_module:
+            importlib.reload(sys_module)
+        else:
+            importlib.import_module(module_path)
+
+        get_logger().debug('"%s" imported.', module_path)
+
     def _load_handlers_from_cache(self) -> tuple[dict, dict]:
         """
         Get registered handler definitions from Django cache

django_queuebie-0.6.0/queuebie/settings.py

@@ -0,0 +1,72 @@
+from pathlib import Path
+
+from django.conf import settings
+
+from queuebie.exceptions import InvalidExcludedDirectoriesError
+
+DEFAULT_EXCLUDED_DIRECTORIES = {
+    "__pycache__",
+    "fixtures",
+    "locale",
+    "media",
+    "migrations",
+    "node_modules",
+    "static",
+    "templates",
+    "tests",
+}
+
+
+def get_queuebie_app_base_path() -> Path | str:
+    """
+    Base path of the application queuebie should look for registered handlers.
+    :return:
+    """
+    return getattr(settings, "QUEUEBIE_APP_BASE_PATH", getattr(settings, "BASE_PATH", None))
+
+
+def get_queuebie_cache_key() -> str:
+    """
+    Cache key to store registered handlers in.
+    """
+    return getattr(settings, "QUEUEBIE_CACHE_KEY", "queuebie")
+
+
+def get_queuebie_logger_name() -> str:
+    """
+    Django logger name
+    """
+    return getattr(settings, "QUEUEBIE_LOGGER_NAME", "queuebie")
+
+
+def get_queuebie_strict_mode() -> bool:
+    """
+    Determines if commands are allowed to be handled outside the scope they are defined in.
+    """
+    return getattr(settings, "QUEUEBIE_STRICT_MODE", True)
+
+
+def get_queuebie_default_excluded_directories() -> set[str]:
+    """
+    Directory names which occur inside Django apps but never hold message handlers.
+    """
+    return _directory_names(setting_name="QUEUEBIE_DEFAULT_EXCLUDED_DIRECTORIES", default=DEFAULT_EXCLUDED_DIRECTORIES)
+
+
+def get_queuebie_excluded_directories() -> set[str]:
+    """
+    Directory names which are skipped when searching for handler modules.
+    """
+    return get_queuebie_default_excluded_directories() | _directory_names(
+        setting_name="QUEUEBIE_EXCLUDED_DIRECTORIES", default=set()
+    )
+
+
+def _directory_names(*, setting_name: str, default: set[str]) -> set[str]:
+    directory_names = getattr(settings, setting_name, default)
+
+    # A string would decay into a set of single characters, silently excluding the wrong directories
+    if isinstance(directory_names, str):
+        raise InvalidExcludedDirectoriesError(setting_name=setting_name)
+
+    return set(directory_names)

django_queuebie-0.6.0/queuebie/utils.py

@@ -0,0 +1,38 @@
+from collections.abc import Callable
+
+HANDLERS_DIRECTORY_NAME = "handlers"
+MESSAGES_DIRECTORY_NAME = "messages"
+SCOPE_MARKERS = (HANDLERS_DIRECTORY_NAME, MESSAGES_DIRECTORY_NAME)
+
+
+def message_scope(*, module_path: str) -> str:
+    """
+    Determines the package owning the "handlers" or "messages" directory the given module lives in.
+    Falls back to the full module path for modules outside such a directory.
+    """
+    parts = module_path.split(".")
+    # The last segment is the module itself, so a module called "messages.py" is not a marker
+    marker_indices = [index for index, part in enumerate(parts[:-1]) if part in SCOPE_MARKERS]
+
+    return ".".join(parts[: marker_indices[-1]]) if marker_indices else module_path
+
+
+def is_same_scope(*, function: Callable, class_type: type) -> bool:
+    """
+    Checks if a class and the given function belong to the same scope.
+    """
+    return message_scope(module_path=class_type.__module__) == message_scope(module_path=function.__module__)
+
+
+def unique_append_to_inner_list(*, data: dict, key: str | int, value) -> dict:
+    """
+    Inserts "value" in the dictionary "data" on "key".
+    If "key" doesn't exist yet, it will create a new list containing "value".
+    If "value" at "key" already exists, it won't be appended.
+    """
+    if key not in data:
+        data[key] = [value]
+    elif value not in data[key]:
+        data[key].append(value)
+
+    return data

django_queuebie-0.6.0/testapp/handlers/commands/messages.py

@@ -0,0 +1,9 @@
+from queuebie import message_registry
+from queuebie.logger import get_logger
+from testapp.messages.commands.messages import SendMessage
+
+
+@message_registry.register_command(command=SendMessage)
+def handle_send_message(*, context: SendMessage) -> None:
+    logger = get_logger()
+    logger.info(f'Command "SendMessage" executed with text={context.text}.')

django_queuebie-0.6.0/testapp/messages/commands/messages.py

@@ -0,0 +1,13 @@
+import dataclasses
+
+from queuebie.messages import Command
+
+
+@dataclasses.dataclass(kw_only=True)
+class SendMessage(Command):
+    """
+    Lives in a module called "messages" on purpose: the module name must not be mistaken for the
+    directory determining the scope.
+    """
+
+    text: str