django-database-task 0.2.4__tar.gz → 0.3.0__tar.gz

{django_database_task-0.2.4/django_database_task.egg-info → django_database_task-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: django-database-task
-Version: 0.2.4
-Summary: A database-backed task queue backend for Django 6.0's built-in task framework
+Version: 0.3.0
+Summary: A database-backed task queue backend for Django's built-in task framework
 Author-email: Shinya Okano <tokibito@gmail.com>
 Maintainer-email: Shinya Okano <tokibito@gmail.com>
 License-Expression: MIT
@@ -9,10 +9,11 @@ Project-URL: Homepage, https://github.com/tokibito/django-database-task
 Project-URL: Repository, https://github.com/tokibito/django-database-task
 Project-URL: Issues, https://github.com/tokibito/django-database-task/issues
 Keywords: django,task,queue,background,database,async
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Web Environment
 Classifier: Framework :: Django
 Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
@@ -31,7 +32,7 @@ Requires-Dist: google-auth>=2.0.0; extra == "cloudtasks"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-django>=4.5; extra == "dev"
-Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
 Dynamic: license-file
 
 # django-database-task
@@ -41,7 +42,7 @@ Dynamic: license-file
 [![Python versions](https://img.shields.io/pypi/pyversions/django-database-task.svg)](https://pypi.org/project/django-database-task/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A database-backed task queue backend for Django 6.0's built-in task framework.
+A database-backed task queue backend for Django's built-in task framework.
 
 ## Features
 
@@ -51,6 +52,7 @@ A database-backed task queue backend for Django 6.0's built-in task framework.
 - **Exclusive locking** - Prevents duplicate task execution with `SELECT FOR UPDATE SKIP LOCKED`
 - **Django Admin integration** - View and manage tasks from the admin interface
 - **Async support** - Supports async task functions
+- **Graceful shutdown** - Workers finish the running task before exiting on `SIGTERM`
 - **Google Cloud Tasks integration** - Optional backend for GAE/Cloud Run with auto-detection
 
 ## Architecture
@@ -94,15 +96,16 @@ sequenceDiagram
 
 ### Supported Databases
 
-Django 6.0 officially supports the following database versions:
+The minimum database versions are the ones Django itself requires, and Django
+6.1 raised most of them:
 
-| Database | Minimum Version | Notes |
-|----------|-----------------|-------|
-| PostgreSQL | 14+ | Recommended for production. Full `SELECT FOR UPDATE SKIP LOCKED` support. |
-| MySQL | 8.0.11+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
-| MariaDB | 10.6+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
-| SQLite | 3.31.0+ | Works for development/testing, but no row-level locking. |
-| Oracle | 19c+ | Supported but not tested with this package. |
+| Database | Django 6.0 | Django 6.1 | Notes |
+|----------|------------|------------|-------|
+| PostgreSQL | 14+ | 15+ | Recommended for production. Full `SELECT FOR UPDATE SKIP LOCKED` support. |
+| MySQL | 8.0.11+ | 8.4+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
+| MariaDB | 10.6+ | 10.11+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
+| SQLite | 3.31.0+ | 3.37.0+ | Works for development/testing, but no row-level locking. |
+| Oracle | 19c+ | 19c+ | Supported but not tested with this package. |
 
 **Note**: `SELECT FOR UPDATE SKIP LOCKED` is used to prevent duplicate task execution in multi-worker environments. SQLite does not support row-level locking, so it is only recommended for development or single-worker deployments.
 
@@ -279,6 +282,24 @@ python manage.py run_database_tasks [options]
 | `--continuous` | Keep polling even when no tasks |
 | `--interval` | Polling interval in seconds (default: 5) |
 | `--max-tasks` | Maximum number of tasks to process (0=unlimited) |
+| `--shutdown-timeout` | Maximum seconds to wait for the running task after `SIGTERM`/`SIGINT` before forcing exit (0=wait indefinitely, default: 0) |
+| `--no-graceful-shutdown` | Do not install signal handlers (terminate immediately, even while a task is running) |
+| `--verbosity` | Output level: `0` silent (errors only), `1` normal (default), `2` also print an idle heartbeat dot per poll |
+
+See [Graceful Shutdown](#graceful-shutdown) for details.
+
+#### Output verbosity
+
+At the default verbosity the worker only prints the startup banner and one
+block per task, so its output stays readable in a log aggregator. Idle polls in
+`--continuous` mode print nothing.
+
+Pass `-v 2` to print a `.` for every poll that found no task - useful when
+watching a worker interactively to confirm it is alive, but it buries real log
+output if left on in production.
+
+Pass `-v 0` to suppress the informational output entirely; task failures and
+errors are still reported.
 
 ### purge_completed_database_tasks
 
@@ -295,6 +316,177 @@ python manage.py purge_completed_database_tasks [options]
 | `--batch-size` | Number of tasks to delete at once (default: 1000) |
 | `--dry-run` | Show count only without deleting |
 
+## Graceful Shutdown
+
+When a worker is redeployed, the orchestrator (Kubernetes, Cloud Run, systemd,
+Docker, supervisord, ...) sends `SIGTERM` and kills the process with `SIGKILL`
+after a grace period. Without any handling, a task that happens to be running
+at that moment is killed halfway through and stays in `RUNNING` status forever.
+
+`run_database_tasks` installs `SIGTERM` and `SIGINT` handlers by default:
+
+1. On the first signal the worker stops fetching new tasks.
+2. The task currently being executed keeps running until it finishes and its
+   result is written to the database.
+3. The worker then exits with status code 0.
+
+While no task is running (the polling sleep in `--continuous` mode), the signal
+is handled immediately - the worker does not wait out the remaining interval.
+
+```console
+$ python manage.py run_database_tasks --continuous
+Worker ID: worker-1-3f2a9c11
+Backend: default
+Continuous mode: interval=5.0s
+Graceful shutdown: enabled (timeout=unlimited)
+
+Processing task: 1e2d... (myapp.tasks.send_report)
+^C
+Received SIGINT: no new tasks will be started. Waiting for the running task to finish (send the signal again to force exit).
+  Task completed successfully
+
+Shutdown complete (no task was interrupted).
+
+Total tasks processed: 1
+```
+
+### Shutdown timeout
+
+By default the worker waits as long as the running task needs. Use
+`--shutdown-timeout` to put an upper bound on it, so the process exits on its
+own terms instead of being `SIGKILL`ed by the platform:
+
+```bash
+python manage.py run_database_tasks --continuous --shutdown-timeout 25
+```
+
+If the task is still running when the timeout expires, the process exits
+immediately with status code 1 and the task stays in `RUNNING` status.
+Set this to a value slightly below the platform's termination grace period,
+and keep the grace period longer than your longest task whenever possible.
+
+Sending the signal a second time (for example pressing Ctrl-C twice) also
+forces an immediate exit.
+
+### Cooperating from inside a task
+
+Long running tasks can check whether a shutdown was requested and stop early,
+so the worker does not have to wait for the whole task to complete:
+
+```python
+from django.tasks import task
+
+from django_database_task import is_shutdown_requested
+
+
+@task
+def import_rows(row_ids):
+    processed = []
+    for row_id in row_ids:
+        if is_shutdown_requested():
+            # Requeue the remaining work and return early
+            import_rows.enqueue([i for i in row_ids if i not in processed])
+            break
+        handle(row_id)
+        processed.append(row_id)
+    return len(processed)
+```
+
+`is_shutdown_requested()` returns `False` when no worker with graceful shutdown
+is active, so tasks using it stay safe to call from a web request, a test, or
+the HTTP endpoints.
+
+### Deployment examples
+
+**Kubernetes** - set `terminationGracePeriodSeconds` longer than the worker's
+shutdown timeout:
+
+```yaml
+spec:
+  terminationGracePeriodSeconds: 60
+  containers:
+    - name: worker
+      command:
+        - python
+        - manage.py
+        - run_database_tasks
+        - --continuous
+        - --shutdown-timeout=50
+```
+
+**systemd** - `TimeoutStopSec` controls how long systemd waits before
+`SIGKILL`:
+
+```ini
+[Service]
+ExecStart=/srv/app/venv/bin/python manage.py run_database_tasks --continuous --shutdown-timeout=50
+KillSignal=SIGTERM
+TimeoutStopSec=60
+Restart=always
+```
+
+**Docker / Docker Compose** - `docker stop` sends `SIGTERM` and waits for
+`--time` (10 seconds by default):
+
+```yaml
+services:
+  worker:
+    command: python manage.py run_database_tasks --continuous --shutdown-timeout=25
+    stop_grace_period: 30s
+```
+
+Make sure the worker is PID 1 or that the signal reaches it (use the exec form
+of `CMD`, or an init such as `tini`, rather than wrapping the command in a
+shell script that swallows signals).
+
+### Tasks left in RUNNING status
+
+If a worker is killed with `SIGKILL` (grace period exceeded, node failure,
+`--no-graceful-shutdown`), the task it was running stays in `RUNNING` status
+because no process is left to update it. Such tasks are not picked up again by
+other workers. They can be found and requeued from the Django admin, or with a
+query like:
+
+```python
+from datetime import timedelta
+
+from django.tasks.base import TaskResultStatus
+from django.utils import timezone
+
+from django_database_task.models import DatabaseTask
+
+stale = DatabaseTask.objects.filter(
+    status=TaskResultStatus.RUNNING,
+    last_attempted_at__lt=timezone.now() - timedelta(hours=1),
+)
+stale.update(status=TaskResultStatus.READY)
+```
+
+Only requeue tasks that are safe to run twice (idempotent).
+
+### Using it in your own worker loop
+
+The shutdown handling is available as a public API, for custom worker loops:
+
+```python
+from django_database_task import GracefulShutdown, process_tasks
+
+with GracefulShutdown(timeout=50) as shutdown:
+    while not shutdown.is_set():
+        results = process_tasks(max_tasks=10, stop_event=shutdown)
+        if not results and shutdown.wait(5):  # interruptible sleep
+            break
+```
+
+| API | Description |
+|-----|-------------|
+| `GracefulShutdown(signals=None, timeout=0, on_signal=None, force_on_repeat=True)` | Context manager that installs the signal handlers |
+| `shutdown.is_set()` | True once a shutdown has been requested |
+| `shutdown.wait(seconds)` | Sleep, returning early (True) when a shutdown is requested |
+| `shutdown.set()` | Request a shutdown programmatically |
+| `process_tasks(..., stop_event=...)` | Stop starting new tasks once the event is set |
+| `is_shutdown_requested()` | True if the active worker was asked to shut down |
+
 ## Programmatic API
 
 You can also process tasks programmatically without management commands:
@@ -330,8 +522,17 @@ if result:
 
 # Retry a failed task
 result = run_task_by_id("...", allow_retry=True)
+
+# Stop starting new tasks when the process receives SIGTERM/SIGINT
+from django_database_task import GracefulShutdown
+
+with GracefulShutdown() as shutdown:
+    results = process_tasks(stop_event=shutdown)
 ```
 
+See [Graceful Shutdown](#graceful-shutdown) for details on `stop_event` and
+`GracefulShutdown`.
+
 ## HTTP Endpoints (Optional)
 
 For environments where cron or direct command execution is not available

{django_database_task-0.2.4 → django_database_task-0.3.0}/README.md

@@ -5,7 +5,7 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/django-database-task.svg)](https://pypi.org/project/django-database-task/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A database-backed task queue backend for Django 6.0's built-in task framework.
+A database-backed task queue backend for Django's built-in task framework.
 
 ## Features
 
@@ -15,6 +15,7 @@ A database-backed task queue backend for Django 6.0's built-in task framework.
 - **Exclusive locking** - Prevents duplicate task execution with `SELECT FOR UPDATE SKIP LOCKED`
 - **Django Admin integration** - View and manage tasks from the admin interface
 - **Async support** - Supports async task functions
+- **Graceful shutdown** - Workers finish the running task before exiting on `SIGTERM`
 - **Google Cloud Tasks integration** - Optional backend for GAE/Cloud Run with auto-detection
 
 ## Architecture
@@ -58,15 +59,16 @@ sequenceDiagram
 
 ### Supported Databases
 
-Django 6.0 officially supports the following database versions:
+The minimum database versions are the ones Django itself requires, and Django
+6.1 raised most of them:
 
-| Database | Minimum Version | Notes |
-|----------|-----------------|-------|
-| PostgreSQL | 14+ | Recommended for production. Full `SELECT FOR UPDATE SKIP LOCKED` support. |
-| MySQL | 8.0.11+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
-| MariaDB | 10.6+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
-| SQLite | 3.31.0+ | Works for development/testing, but no row-level locking. |
-| Oracle | 19c+ | Supported but not tested with this package. |
+| Database | Django 6.0 | Django 6.1 | Notes |
+|----------|------------|------------|-------|
+| PostgreSQL | 14+ | 15+ | Recommended for production. Full `SELECT FOR UPDATE SKIP LOCKED` support. |
+| MySQL | 8.0.11+ | 8.4+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
+| MariaDB | 10.6+ | 10.11+ | Full `SELECT FOR UPDATE SKIP LOCKED` support. |
+| SQLite | 3.31.0+ | 3.37.0+ | Works for development/testing, but no row-level locking. |
+| Oracle | 19c+ | 19c+ | Supported but not tested with this package. |
 
 **Note**: `SELECT FOR UPDATE SKIP LOCKED` is used to prevent duplicate task execution in multi-worker environments. SQLite does not support row-level locking, so it is only recommended for development or single-worker deployments.
 
@@ -243,6 +245,24 @@ python manage.py run_database_tasks [options]
 | `--continuous` | Keep polling even when no tasks |
 | `--interval` | Polling interval in seconds (default: 5) |
 | `--max-tasks` | Maximum number of tasks to process (0=unlimited) |
+| `--shutdown-timeout` | Maximum seconds to wait for the running task after `SIGTERM`/`SIGINT` before forcing exit (0=wait indefinitely, default: 0) |
+| `--no-graceful-shutdown` | Do not install signal handlers (terminate immediately, even while a task is running) |
+| `--verbosity` | Output level: `0` silent (errors only), `1` normal (default), `2` also print an idle heartbeat dot per poll |
+
+See [Graceful Shutdown](#graceful-shutdown) for details.
+
+#### Output verbosity
+
+At the default verbosity the worker only prints the startup banner and one
+block per task, so its output stays readable in a log aggregator. Idle polls in
+`--continuous` mode print nothing.
+
+Pass `-v 2` to print a `.` for every poll that found no task - useful when
+watching a worker interactively to confirm it is alive, but it buries real log
+output if left on in production.
+
+Pass `-v 0` to suppress the informational output entirely; task failures and
+errors are still reported.
 
 ### purge_completed_database_tasks
 
@@ -259,6 +279,177 @@ python manage.py purge_completed_database_tasks [options]
 | `--batch-size` | Number of tasks to delete at once (default: 1000) |
 | `--dry-run` | Show count only without deleting |
 
+## Graceful Shutdown
+
+When a worker is redeployed, the orchestrator (Kubernetes, Cloud Run, systemd,
+Docker, supervisord, ...) sends `SIGTERM` and kills the process with `SIGKILL`
+after a grace period. Without any handling, a task that happens to be running
+at that moment is killed halfway through and stays in `RUNNING` status forever.
+
+`run_database_tasks` installs `SIGTERM` and `SIGINT` handlers by default:
+
+1. On the first signal the worker stops fetching new tasks.
+2. The task currently being executed keeps running until it finishes and its
+   result is written to the database.
+3. The worker then exits with status code 0.
+
+While no task is running (the polling sleep in `--continuous` mode), the signal
+is handled immediately - the worker does not wait out the remaining interval.
+
+```console
+$ python manage.py run_database_tasks --continuous
+Worker ID: worker-1-3f2a9c11
+Backend: default
+Continuous mode: interval=5.0s
+Graceful shutdown: enabled (timeout=unlimited)
+
+Processing task: 1e2d... (myapp.tasks.send_report)
+^C
+Received SIGINT: no new tasks will be started. Waiting for the running task to finish (send the signal again to force exit).
+  Task completed successfully
+
+Shutdown complete (no task was interrupted).
+
+Total tasks processed: 1
+```
+
+### Shutdown timeout
+
+By default the worker waits as long as the running task needs. Use
+`--shutdown-timeout` to put an upper bound on it, so the process exits on its
+own terms instead of being `SIGKILL`ed by the platform:
+
+```bash
+python manage.py run_database_tasks --continuous --shutdown-timeout 25
+```
+
+If the task is still running when the timeout expires, the process exits
+immediately with status code 1 and the task stays in `RUNNING` status.
+Set this to a value slightly below the platform's termination grace period,
+and keep the grace period longer than your longest task whenever possible.
+
+Sending the signal a second time (for example pressing Ctrl-C twice) also
+forces an immediate exit.
+
+### Cooperating from inside a task
+
+Long running tasks can check whether a shutdown was requested and stop early,
+so the worker does not have to wait for the whole task to complete:
+
+```python
+from django.tasks import task
+
+from django_database_task import is_shutdown_requested
+
+
+@task
+def import_rows(row_ids):
+    processed = []
+    for row_id in row_ids:
+        if is_shutdown_requested():
+            # Requeue the remaining work and return early
+            import_rows.enqueue([i for i in row_ids if i not in processed])
+            break
+        handle(row_id)
+        processed.append(row_id)
+    return len(processed)
+```
+
+`is_shutdown_requested()` returns `False` when no worker with graceful shutdown
+is active, so tasks using it stay safe to call from a web request, a test, or
+the HTTP endpoints.
+
+### Deployment examples
+
+**Kubernetes** - set `terminationGracePeriodSeconds` longer than the worker's
+shutdown timeout:
+
+```yaml
+spec:
+  terminationGracePeriodSeconds: 60
+  containers:
+    - name: worker
+      command:
+        - python
+        - manage.py
+        - run_database_tasks
+        - --continuous
+        - --shutdown-timeout=50
+```
+
+**systemd** - `TimeoutStopSec` controls how long systemd waits before
+`SIGKILL`:
+
+```ini
+[Service]
+ExecStart=/srv/app/venv/bin/python manage.py run_database_tasks --continuous --shutdown-timeout=50
+KillSignal=SIGTERM
+TimeoutStopSec=60
+Restart=always
+```
+
+**Docker / Docker Compose** - `docker stop` sends `SIGTERM` and waits for
+`--time` (10 seconds by default):
+
+```yaml
+services:
+  worker:
+    command: python manage.py run_database_tasks --continuous --shutdown-timeout=25
+    stop_grace_period: 30s
+```
+
+Make sure the worker is PID 1 or that the signal reaches it (use the exec form
+of `CMD`, or an init such as `tini`, rather than wrapping the command in a
+shell script that swallows signals).
+
+### Tasks left in RUNNING status
+
+If a worker is killed with `SIGKILL` (grace period exceeded, node failure,
+`--no-graceful-shutdown`), the task it was running stays in `RUNNING` status
+because no process is left to update it. Such tasks are not picked up again by
+other workers. They can be found and requeued from the Django admin, or with a
+query like:
+
+```python
+from datetime import timedelta
+
+from django.tasks.base import TaskResultStatus
+from django.utils import timezone
+
+from django_database_task.models import DatabaseTask
+
+stale = DatabaseTask.objects.filter(
+    status=TaskResultStatus.RUNNING,
+    last_attempted_at__lt=timezone.now() - timedelta(hours=1),
+)
+stale.update(status=TaskResultStatus.READY)
+```
+
+Only requeue tasks that are safe to run twice (idempotent).
+
+### Using it in your own worker loop
+
+The shutdown handling is available as a public API, for custom worker loops:
+
+```python
+from django_database_task import GracefulShutdown, process_tasks
+
+with GracefulShutdown(timeout=50) as shutdown:
+    while not shutdown.is_set():
+        results = process_tasks(max_tasks=10, stop_event=shutdown)
+        if not results and shutdown.wait(5):  # interruptible sleep
+            break
+```
+
+| API | Description |
+|-----|-------------|
+| `GracefulShutdown(signals=None, timeout=0, on_signal=None, force_on_repeat=True)` | Context manager that installs the signal handlers |
+| `shutdown.is_set()` | True once a shutdown has been requested |
+| `shutdown.wait(seconds)` | Sleep, returning early (True) when a shutdown is requested |
+| `shutdown.set()` | Request a shutdown programmatically |
+| `process_tasks(..., stop_event=...)` | Stop starting new tasks once the event is set |
+| `is_shutdown_requested()` | True if the active worker was asked to shut down |
+
 ## Programmatic API
 
 You can also process tasks programmatically without management commands:
@@ -294,8 +485,17 @@ if result:
 
 # Retry a failed task
 result = run_task_by_id("...", allow_retry=True)
+
+# Stop starting new tasks when the process receives SIGTERM/SIGINT
+from django_database_task import GracefulShutdown
+
+with GracefulShutdown() as shutdown:
+    results = process_tasks(stop_event=shutdown)
 ```
 
+See [Graceful Shutdown](#graceful-shutdown) for details on `stop_event` and
+`GracefulShutdown`.
+
 ## HTTP Endpoints (Optional)
 
 For environments where cron or direct command execution is not available

django_database_task-0.3.0/django_database_task/__init__.py

@@ -0,0 +1,44 @@
+"""
+django-database-task: A database-backed task queue backend for Django's task framework.
+"""
+
+__version__ = "0.3.0"
+
+_EXECUTOR_EXPORTS = (
+    "fetch_task",
+    "get_pending_task_count",
+    "process_one_task",
+    "process_tasks",
+    "run_task_by_id",
+)
+
+_SHUTDOWN_EXPORTS = (
+    "GracefulShutdown",
+    "get_active_shutdown",
+    "is_shutdown_requested",
+)
+
+
+def __getattr__(name):
+    """Lazy import to avoid AppRegistryNotReady errors."""
+    if name in _EXECUTOR_EXPORTS:
+        from . import executor
+
+        return getattr(executor, name)
+    if name in _SHUTDOWN_EXPORTS:
+        from . import shutdown
+
+        return getattr(shutdown, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "GracefulShutdown",
+    "fetch_task",
+    "get_active_shutdown",
+    "get_pending_task_count",
+    "is_shutdown_requested",
+    "process_one_task",
+    "process_tasks",
+    "run_task_by_id",
+]

{django_database_task-0.2.4 → django_database_task-0.3.0}/django_database_task/executor.py

@@ -105,6 +105,7 @@ def process_tasks(
     backend_name="default",
     max_tasks=0,
     worker_id=None,
+    stop_event=None,
 ):
     """
     Process multiple pending tasks.
@@ -114,6 +115,11 @@ def process_tasks(
         backend_name: Backend name (default: "default").
         max_tasks: Maximum number of tasks to process (0 = unlimited).
         worker_id: Optional worker ID. If not provided, one will be generated.
+        stop_event: Optional object with an ``is_set()`` method (for example a
+            :class:`threading.Event` or a
+            :class:`~django_database_task.GracefulShutdown`). No new task is
+            started once it is set; the task already running is not
+            interrupted.
 
     Returns:
         List of TaskResult objects for all processed tasks.
@@ -124,6 +130,11 @@ def process_tasks(
         >>> print(f"Processed {len(results)} tasks")
         >>> for result in results:
         ...     print(f"  {result.id}: {result.status}")
+
+        # Stop starting new tasks on SIGTERM/SIGINT
+        >>> from django_database_task import GracefulShutdown
+        >>> with GracefulShutdown() as shutdown:
+        ...     results = process_tasks(stop_event=shutdown)
     """
     if worker_id is None:
         worker_id = _generate_worker_id()
@@ -132,6 +143,9 @@ def process_tasks(
     tasks_processed = 0
 
     while True:
+        if stop_event is not None and stop_event.is_set():
+            break
+
         result = process_one_task(
             queue_name=queue_name,
             backend_name=backend_name,