Add Django integration

Override the runserver and runserver_plus management commands to wrap
inner_run in activate(), providing automatic broker lifecycle management
during development. Support configurable base class resolution via
tool.queueio.django.runserver in pyproject.toml to allow chaining with
providers like daphne or django.contrib.staticfiles.

Integrate with django-cmd for settings discovery from
tool.django.settings in pyproject.toml, and with djp for automatic
INSTALLED_APPS registration. Fall back to DJANGO_SETTINGS_MODULE
environment variable when django-cmd is not installed.

Include a sample Django app in queueio/samples/django/ with an
end-to-end integration test that spins up a real Django server and
queueio worker, submits a job via HTTP, and verifies ORM updates.

Author: ryanhiebert

CHANGELOG.md

@@ -8,8 +8,14 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com).
 [Unreleased]
 ------------
 
+[0.6.0] - 2026-02-16
+--------------------
+
 ### Added
 
+- Django integration (`queueio.django`) with `runserver` lifecycle management.
+- [djp](https://djp.readthedocs.io/) support for automatic `INSTALLED_APPS` registration.
+- [django-cmd](https://pypi.org/project/django-cmd/) integration for settings discovery.
 - Documentation site.
 
 [0.5.0] - 2026-02-08
@@ -100,7 +106,8 @@ Thank you to Nick Anderegg for allowing me to use the queueio name for this proj
 - The queuespec syntax to `queue run` to consume multiple queues with shared capacity.
 - `queueio monitor` command to monitor activity in the queueio system.
 
-[Unreleased]: https://github.com/ryanhiebert/queueio/compare/tag/0.5.0...HEAD
+[Unreleased]: https://github.com/ryanhiebert/queueio/compare/tag/0.6.0...HEAD
+[0.6.0]: https://github.com/ryanhiebert/queueio/compare/tag/0.5.0...tag/0.6.0
 [0.5.0]: https://github.com/ryanhiebert/queueio/compare/tag/0.4.0...tag/0.5.0
 [0.4.0]: https://github.com/ryanhiebert/queueio/compare/tag/0.3.0...tag/0.4.0
 [0.3.0]: https://github.com/ryanhiebert/queueio/compare/tag/0.2.2...tag/0.3.0

mkdocs.yml

@@ -20,6 +20,7 @@ theme:
       primary: black
 
 markdown_extensions:
+  - admonition
   - pymdownx.highlight
   - pymdownx.superfences
 
@@ -36,4 +37,5 @@ nav:
   - Invocation: queueio/invocation.md
   - QueueSpec: queueio/queuespec.md
   - QueueVar: queueio/queuevar.md
+  - Django: queueio/django.md
   - Changelog: CHANGELOG.md

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "queueio"
-version = "0.5.0"
+version = "0.6.0"
 description = "Python background queues with an async twist"
 readme = "README.md"
 license = "MIT"
@@ -27,12 +27,21 @@ dependencies = [
     "typer>=0.15.4",
 ]
 
+[project.optional-dependencies]
+django = ["django>=6.0", "django-cmd>=3.0"]
+
+[project.entry-points.djp]
+queueio = "queueio.django.djp"
+
 [project.scripts]
 queueio = "queueio.__main__:app"
 
 [dependency-groups]
 dev = [
     "basedpyright>=1.32.1",
+    "django-extensions",
+    "djp",
+    "queueio[django]",
     "mkdocs-material>=9.7.1",
     "mkdocs-same-dir>=0.1.3",
     "pytest>=8.4.1",
@@ -60,6 +69,7 @@ pika = "amqp://localhost:5672"
 
 [tool.pytest.ini_options]
 timeout = 30
+norecursedirs = ["site"]
 
 [tool.coverage.run]
 branch = true

queueio/django.md

@@ -0,0 +1,82 @@
+# Django Integration
+
+## Settings
+
+When running `queueio run`,
+Django isn't started automatically.
+If your routines use the Django ORM or other Django features,
+queueio needs to call `django.setup()` before importing routine modules.
+
+The `queueio[django]` extra includes
+[django-cmd](https://pypi.org/project/django-cmd/),
+which reads `tool.django.settings` from `pyproject.toml`
+and sets `DJANGO_SETTINGS_MODULE` automatically:
+
+```toml
+[tool.django]
+settings = "myproject.settings"
+```
+
+If `DJANGO_SETTINGS_MODULE` is set in the environment
+(whether by `django-cmd` or directly),
+queueio calls `django.setup()` before registering routines.
+
+## Runserver
+
+!!! warning "Development server only"
+
+    The runserver integration only affects the `runserver` management command.
+    Production servers like gunicorn need their own lifecycle hooks.
+
+queueio ships a Django app
+that overrides the `runserver` management command
+to wrap the server in `with activate():`,
+giving you automatic lifecycle management
+of the broker connection and background threads
+during development.
+
+### Setup
+
+If you use [djp](https://djp.readthedocs.io/),
+`queueio.django` is added to `INSTALLED_APPS` automatically.
+
+Otherwise, add it manually:
+
+```python
+INSTALLED_APPS = [
+    "queueio.django",
+    # ...
+]
+```
+
+This must come **after** whichever app provides the `runserver` command
+you want to chain with
+(e.g. `daphne`, `django.contrib.staticfiles`),
+because Django resolves management commands by last-app-wins order.
+
+### Custom provider
+
+If you use a custom `runserver` provider
+like `django.contrib.staticfiles` or `daphne`,
+tell queueio which app to chain with:
+
+```toml
+[tool.queueio.django]
+runserver = "daphne"
+```
+
+The value is the app label (or dotted module path).
+queueio resolves it to `{value}.management.commands.runserver`
+and subclasses that command.
+If omitted, it defaults to Django's built-in `runserver`.
+
+### `runserver_plus`
+
+There is also a built-in `runserver_plus` command
+that wraps [django-extensions](https://django-extensions.readthedocs.io/)' `runserver_plus`
+with `activate()`.
+This is available automatically
+when `django-extensions` is installed
+and `queueio.django` is in `INSTALLED_APPS`.
+
+A complete working example is in `queueio/samples/django/`.

queueio/django/__init__.py

@@ -0,0 +1,17 @@
+import os
+
+
+def setup():
+    try:
+        from django_cmd import configure
+
+        configure()
+    except ImportError:
+        pass
+
+    if "DJANGO_SETTINGS_MODULE" not in os.environ:
+        return
+
+    import django
+
+    django.setup()

queueio/django/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class QueueIOConfig(AppConfig):
+    name = "queueio.django"
+    label = "queueio"

queueio/django/djp.py

@@ -0,0 +1,6 @@
+import djp
+
+
+@djp.hookimpl
+def installed_apps():
+    return ["queueio.django"]

queueio/django/management/__init__.py

@@ -0,0 +1,41 @@
+import tomllib
+from importlib import import_module
+from pathlib import Path
+
+
+def _find_pyproject() -> Path | None:
+    for path in [cwd := Path.cwd(), *cwd.parents]:
+        candidate = path / "pyproject.toml"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _queueio_django_config() -> dict:
+    if pyproject := _find_pyproject():
+        with pyproject.open("rb") as f:
+            config = tomllib.load(f)
+        return config.get("tool", {}).get("queueio", {}).get("django", {})
+    return {}
+
+
+def _resolve_base_command(config: dict):
+    runserver_app = config.get("runserver", "django.core")
+    module = import_module(f"{runserver_app}.management.commands.runserver")
+    return module.Command
+
+
+def _build_command():
+    base = _resolve_base_command(_queueio_django_config())
+
+    class Command(base):
+        def inner_run(self, *args, **options):
+            from queueio import activate
+
+            with activate():
+                super().inner_run(*args, **options)
+
+    return Command
+
+
+Command = _build_command()