django-database-task 0.1.0__tar.gz → 0.2.0__tar.gz

{django_database_task-0.1.0/django_database_task.egg-info → django_database_task-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-database-task
-Version: 0.1.0
+Version: 0.2.0
 Summary: A database-backed task queue backend for Django 6.0's built-in task framework
 Author-email: Shinya Okano <tokibito@gmail.com>
 Maintainer-email: Shinya Okano <tokibito@gmail.com>
@@ -25,6 +25,9 @@ Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: Django>=6.0
+Provides-Extra: cloudtasks
+Requires-Dist: google-cloud-tasks>=2.0.0; extra == "cloudtasks"
+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"
@@ -43,6 +46,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
+- **Google Cloud Tasks integration** - Optional backend for GAE/Cloud Run with auto-detection
 
 ## Architecture
 
@@ -291,7 +295,12 @@ python manage.py purge_completed_database_tasks [options]
 You can also process tasks programmatically without management commands:
 
 ```python
-from django_database_task import process_one_task, process_tasks, get_pending_task_count
+from django_database_task import (
+    process_one_task,
+    process_tasks,
+    get_pending_task_count,
+    run_task_by_id,
+)
 
 # Process a single task
 result = process_one_task()
@@ -308,6 +317,14 @@ results = process_tasks(queue_name="emails", max_tasks=5)
 # Get pending task count
 count = get_pending_task_count()
 print(f"Pending tasks: {count}")
+
+# Execute a specific task by ID
+result = run_task_by_id("550e8400-e29b-41d4-a716-446655440000")
+if result:
+    print(f"Executed: {result.id}, status: {result.status}")
+
+# Retry a failed task
+result = run_task_by_id("...", allow_retry=True)
 ```
 
 ## HTTP Endpoints (Optional)
@@ -335,6 +352,8 @@ urlpatterns = [
 | `/tasks/run/` | POST | Process multiple pending tasks |
 | `/tasks/run-one/` | POST | Process a single pending task |
 | `/tasks/status/` | GET | Get pending task count |
+| `/tasks/execute/<uuid>/` | POST | Execute a specific task by ID |
+| `/tasks/purge/` | POST | Delete completed tasks |
 
 ### Request Parameters
 
@@ -385,6 +404,52 @@ Response:
 {"pending_count": 5}
 ```
 
+#### POST `/tasks/execute/<uuid>/`
+
+Execute a specific task by ID. This endpoint is designed for external trigger systems
+(e.g., Cloud Tasks, webhooks) that need to execute a specific task.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `fail_on_error` | query string | "false" | Return HTTP 500 on task failure |
+| `allow_retry` | query string | "false" | Allow re-execution of FAILED tasks |
+
+Response (success):
+```json
+{"executed": true, "result": {"id": "uuid", "status": "SUCCESSFUL", "task_path": "..."}}
+```
+
+Response (task not in executable status):
+```json
+{"executed": false, "reason": "Task is not in READY status"}
+```
+
+Response (task not found):
+```json
+{"error": "Task not found"}  // HTTP 404
+```
+
+#### POST `/tasks/purge/`
+
+Delete completed tasks from the database. Useful for cron-based cleanup.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `days` | int | 0 | Delete tasks completed more than N days ago (0=all) |
+| `status` | string | "SUCCESSFUL,FAILED" | Target statuses, comma-separated |
+| `batch_size` | int | 1000 | Number of tasks to delete at once (max: 10000) |
+| `dry_run` | bool | false | If true, return count without deleting |
+
+Response:
+```json
+{"deleted": 150, "dry_run": false}
+```
+
+Response (dry run):
+```json
+{"count": 150, "dry_run": true}
+```
+
 ### Example Usage
 
 ```bash
@@ -400,6 +465,16 @@ curl -X POST http://localhost:8000/tasks/run/ \
 
 # Get pending task count
 curl http://localhost:8000/tasks/status/
+
+# Delete tasks completed more than 7 days ago
+curl -X POST http://localhost:8000/tasks/purge/ \
+  -H "Content-Type: application/json" \
+  -d '{"days": 7}'
+
+# Dry run to check how many tasks would be deleted
+curl -X POST http://localhost:8000/tasks/purge/ \
+  -H "Content-Type: application/json" \
+  -d '{"days": 30, "dry_run": true}'
 ```
 
 ### Use Cases
@@ -446,13 +521,31 @@ if [ "$count" -gt 100 ]; then
 fi
 ```
 
+#### Scheduled Cleanup
+
+Use cron or Cloud Scheduler to delete old completed tasks:
+
+```bash
+# Daily cleanup via cron or Cloud Scheduler
+# Delete tasks completed more than 30 days ago
+curl -X POST https://your-app.com/tasks/purge/ \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"days": 30}'
+```
+
 ### Security
 
 The endpoints are CSRF-exempt for API/webhook use. **Always add authentication in production:**
 
 ```python
 from django.contrib.admin.views.decorators import staff_member_required
-from django_database_task.views import RunTasksView, RunOneTaskView, TaskStatusView
+from django_database_task.views import (
+    RunTasksView,
+    RunOneTaskView,
+    TaskStatusView,
+    PurgeCompletedTasksView,
+)
 
 urlpatterns = [
     path(
@@ -470,6 +563,11 @@ urlpatterns = [
         staff_member_required(TaskStatusView.as_view()),
         name="task_status",
     ),
+    path(
+        "tasks/purge/",
+        staff_member_required(PurgeCompletedTasksView.as_view()),
+        name="purge_completed_tasks",
+    ),
 ]
 ```
 
@@ -492,15 +590,157 @@ urlpatterns = [
 ]
 ```
 
+## Google Cloud Tasks Integration
+
+For serverless environments like Google App Engine or Cloud Run, you can use the Cloud Tasks backend to automatically create Cloud Tasks when tasks are enqueued.
+
+### Installation
+
+```bash
+pip install django-database-task[cloudtasks]
+```
+
+### Quick Setup
+
+```python
+# settings.py
+TASKS = {
+    "default": {
+        "BACKEND": "django_database_task.cloudtasks.CloudTasksDatabaseBackend",
+        "OPTIONS": {
+            "CLOUD_TASKS_QUEUE": "default",  # Only required setting
+        },
+    },
+}
+```
+
+Project ID, location, and handler URL are auto-detected from GAE/Cloud Run environment variables.
+
+### How It Works
+
+```
+1. App enqueues task → Task saved to database + Cloud Task created
+2. Cloud Task triggers HTTP request → /tasks/execute/<task_id>/
+3. Handler retrieves task from database and executes it
+```
+
+The Cloud Task only contains the task ID. All task parameters are stored in the database, ensuring:
+- **Blue/Green deployment support**: Tasks execute on the same version that enqueued them
+- **Database as source of truth**: Task parameters are never lost
+- **Automatic retry**: Cloud Tasks handles retry with the task ID
+
+### Configuration Options
+
+```python
+TASKS = {
+    "default": {
+        "BACKEND": "django_database_task.cloudtasks.CloudTasksDatabaseBackend",
+        "OPTIONS": {
+            # Required
+            "CLOUD_TASKS_QUEUE": "default",
+
+            # Auto-detected (override if needed)
+            # "CLOUD_TASKS_PROJECT": "my-project",
+            # "CLOUD_TASKS_LOCATION": "asia-northeast1",
+            # "TASK_HANDLER_URL": "https://myapp.example.com/tasks/execute/{task_id}/",
+            # "TASK_HANDLER_PATH": "/tasks/execute/{task_id}/",
+
+            # OIDC authentication (optional)
+            # "OIDC_SERVICE_ACCOUNT_EMAIL": "...",
+            # "OIDC_AUDIENCE": "https://...",
+        },
+    },
+}
+```
+
+### Auto-Detection
+
+| Setting | Environment Variable | Description |
+|---------|---------------------|-------------|
+| Project | `GOOGLE_CLOUD_PROJECT` | GCP project ID |
+| Location | `CLOUD_RUN_REGION` / `GAE_REGION` | Cloud Tasks region |
+| Handler URL | Built from `K_SERVICE`, `GAE_SERVICE`, `GAE_VERSION` | Task execution endpoint |
+
+### OIDC Authentication
+
+When `OIDC_SERVICE_ACCOUNT_EMAIL` is configured, Cloud Tasks will send OIDC tokens with each request. The backend automatically verifies these tokens on the `/tasks/execute/` and `/tasks/purge/` endpoints.
+
+```python
+# settings.py - Automatic OIDC verification
+TASKS = {
+    "default": {
+        "BACKEND": "django_database_task.cloudtasks.CloudTasksDatabaseBackend",
+        "OPTIONS": {
+            "CLOUD_TASKS_QUEUE": "default",
+            "OIDC_SERVICE_ACCOUNT_EMAIL": "my-sa@project.iam.gserviceaccount.com",
+            # OIDC_AUDIENCE is auto-detected from handler URL if not set
+        },
+    },
+}
+```
+
+Alternatively, you can use the decorator directly on your URL configuration:
+
+```python
+# urls.py
+from django.urls import path
+from django_database_task.views import ExecuteTaskView
+from django_database_task.cloudtasks import verify_cloud_tasks_oidc
+
+urlpatterns = [
+    path(
+        "tasks/execute/<uuid:task_id>/",
+        verify_cloud_tasks_oidc(
+            ExecuteTaskView.as_view(),
+            audience="https://myapp.example.com"
+        ),
+        name="execute_task",
+    ),
+]
+```
+
+### Detection Utilities
+
+You can use the detection functions directly:
+
+```python
+from django_database_task.cloudtasks import (
+    detect_gcp_project,
+    detect_gcp_location,
+    detect_task_handler_host,
+    is_cloud_run,
+    is_app_engine,
+)
+
+if is_cloud_run():
+    print(f"Running on Cloud Run in {detect_gcp_location()}")
+elif is_app_engine():
+    print(f"Running on App Engine in project {detect_gcp_project()}")
+```
+
 ## Django Admin
 
-The package includes a Django Admin integration to view task status:
+The package includes a Django Admin integration to view and manage tasks:
 
 - Task list with status badges
 - Filter by status, queue, backend
 - Search by task ID or path
 - View task arguments and results
 
+### Admin Actions
+
+The admin interface provides the following bulk actions:
+
+| Action | Description |
+|--------|-------------|
+| **Run selected tasks** | Execute selected tasks that are in READY status |
+| **Retry failed tasks** | Reset FAILED tasks to READY status and re-execute them |
+
+These actions are useful for:
+- Manually triggering task execution from the admin
+- Retrying failed tasks after fixing issues
+- Testing task execution during development
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.

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

@@ -10,6 +10,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
+- **Google Cloud Tasks integration** - Optional backend for GAE/Cloud Run with auto-detection
 
 ## Architecture
 
@@ -258,7 +259,12 @@ python manage.py purge_completed_database_tasks [options]
 You can also process tasks programmatically without management commands:
 
 ```python
-from django_database_task import process_one_task, process_tasks, get_pending_task_count
+from django_database_task import (
+    process_one_task,
+    process_tasks,
+    get_pending_task_count,
+    run_task_by_id,
+)
 
 # Process a single task
 result = process_one_task()
@@ -275,6 +281,14 @@ results = process_tasks(queue_name="emails", max_tasks=5)
 # Get pending task count
 count = get_pending_task_count()
 print(f"Pending tasks: {count}")
+
+# Execute a specific task by ID
+result = run_task_by_id("550e8400-e29b-41d4-a716-446655440000")
+if result:
+    print(f"Executed: {result.id}, status: {result.status}")
+
+# Retry a failed task
+result = run_task_by_id("...", allow_retry=True)
 ```
 
 ## HTTP Endpoints (Optional)
@@ -302,6 +316,8 @@ urlpatterns = [
 | `/tasks/run/` | POST | Process multiple pending tasks |
 | `/tasks/run-one/` | POST | Process a single pending task |
 | `/tasks/status/` | GET | Get pending task count |
+| `/tasks/execute/<uuid>/` | POST | Execute a specific task by ID |
+| `/tasks/purge/` | POST | Delete completed tasks |
 
 ### Request Parameters
 
@@ -352,6 +368,52 @@ Response:
 {"pending_count": 5}
 ```
 
+#### POST `/tasks/execute/<uuid>/`
+
+Execute a specific task by ID. This endpoint is designed for external trigger systems
+(e.g., Cloud Tasks, webhooks) that need to execute a specific task.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `fail_on_error` | query string | "false" | Return HTTP 500 on task failure |
+| `allow_retry` | query string | "false" | Allow re-execution of FAILED tasks |
+
+Response (success):
+```json
+{"executed": true, "result": {"id": "uuid", "status": "SUCCESSFUL", "task_path": "..."}}
+```
+
+Response (task not in executable status):
+```json
+{"executed": false, "reason": "Task is not in READY status"}
+```
+
+Response (task not found):
+```json
+{"error": "Task not found"}  // HTTP 404
+```
+
+#### POST `/tasks/purge/`
+
+Delete completed tasks from the database. Useful for cron-based cleanup.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `days` | int | 0 | Delete tasks completed more than N days ago (0=all) |
+| `status` | string | "SUCCESSFUL,FAILED" | Target statuses, comma-separated |
+| `batch_size` | int | 1000 | Number of tasks to delete at once (max: 10000) |
+| `dry_run` | bool | false | If true, return count without deleting |
+
+Response:
+```json
+{"deleted": 150, "dry_run": false}
+```
+
+Response (dry run):
+```json
+{"count": 150, "dry_run": true}
+```
+
 ### Example Usage
 
 ```bash
@@ -367,6 +429,16 @@ curl -X POST http://localhost:8000/tasks/run/ \
 
 # Get pending task count
 curl http://localhost:8000/tasks/status/
+
+# Delete tasks completed more than 7 days ago
+curl -X POST http://localhost:8000/tasks/purge/ \
+  -H "Content-Type: application/json" \
+  -d '{"days": 7}'
+
+# Dry run to check how many tasks would be deleted
+curl -X POST http://localhost:8000/tasks/purge/ \
+  -H "Content-Type: application/json" \
+  -d '{"days": 30, "dry_run": true}'
 ```
 
 ### Use Cases
@@ -413,13 +485,31 @@ if [ "$count" -gt 100 ]; then
 fi
 ```
 
+#### Scheduled Cleanup
+
+Use cron or Cloud Scheduler to delete old completed tasks:
+
+```bash
+# Daily cleanup via cron or Cloud Scheduler
+# Delete tasks completed more than 30 days ago
+curl -X POST https://your-app.com/tasks/purge/ \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"days": 30}'
+```
+
 ### Security
 
 The endpoints are CSRF-exempt for API/webhook use. **Always add authentication in production:**
 
 ```python
 from django.contrib.admin.views.decorators import staff_member_required
-from django_database_task.views import RunTasksView, RunOneTaskView, TaskStatusView
+from django_database_task.views import (
+    RunTasksView,
+    RunOneTaskView,
+    TaskStatusView,
+    PurgeCompletedTasksView,
+)
 
 urlpatterns = [
     path(
@@ -437,6 +527,11 @@ urlpatterns = [
         staff_member_required(TaskStatusView.as_view()),
         name="task_status",
     ),
+    path(
+        "tasks/purge/",
+        staff_member_required(PurgeCompletedTasksView.as_view()),
+        name="purge_completed_tasks",
+    ),
 ]
 ```
 
@@ -459,15 +554,157 @@ urlpatterns = [
 ]
 ```
 
+## Google Cloud Tasks Integration
+
+For serverless environments like Google App Engine or Cloud Run, you can use the Cloud Tasks backend to automatically create Cloud Tasks when tasks are enqueued.
+
+### Installation
+
+```bash
+pip install django-database-task[cloudtasks]
+```
+
+### Quick Setup
+
+```python
+# settings.py
+TASKS = {
+    "default": {
+        "BACKEND": "django_database_task.cloudtasks.CloudTasksDatabaseBackend",
+        "OPTIONS": {
+            "CLOUD_TASKS_QUEUE": "default",  # Only required setting
+        },
+    },
+}
+```
+
+Project ID, location, and handler URL are auto-detected from GAE/Cloud Run environment variables.
+
+### How It Works
+
+```
+1. App enqueues task → Task saved to database + Cloud Task created
+2. Cloud Task triggers HTTP request → /tasks/execute/<task_id>/
+3. Handler retrieves task from database and executes it
+```
+
+The Cloud Task only contains the task ID. All task parameters are stored in the database, ensuring:
+- **Blue/Green deployment support**: Tasks execute on the same version that enqueued them
+- **Database as source of truth**: Task parameters are never lost
+- **Automatic retry**: Cloud Tasks handles retry with the task ID
+
+### Configuration Options
+
+```python
+TASKS = {
+    "default": {
+        "BACKEND": "django_database_task.cloudtasks.CloudTasksDatabaseBackend",
+        "OPTIONS": {
+            # Required
+            "CLOUD_TASKS_QUEUE": "default",
+
+            # Auto-detected (override if needed)
+            # "CLOUD_TASKS_PROJECT": "my-project",
+            # "CLOUD_TASKS_LOCATION": "asia-northeast1",
+            # "TASK_HANDLER_URL": "https://myapp.example.com/tasks/execute/{task_id}/",
+            # "TASK_HANDLER_PATH": "/tasks/execute/{task_id}/",
+
+            # OIDC authentication (optional)
+            # "OIDC_SERVICE_ACCOUNT_EMAIL": "...",
+            # "OIDC_AUDIENCE": "https://...",
+        },
+    },
+}
+```
+
+### Auto-Detection
+
+| Setting | Environment Variable | Description |
+|---------|---------------------|-------------|
+| Project | `GOOGLE_CLOUD_PROJECT` | GCP project ID |
+| Location | `CLOUD_RUN_REGION` / `GAE_REGION` | Cloud Tasks region |
+| Handler URL | Built from `K_SERVICE`, `GAE_SERVICE`, `GAE_VERSION` | Task execution endpoint |
+
+### OIDC Authentication
+
+When `OIDC_SERVICE_ACCOUNT_EMAIL` is configured, Cloud Tasks will send OIDC tokens with each request. The backend automatically verifies these tokens on the `/tasks/execute/` and `/tasks/purge/` endpoints.
+
+```python
+# settings.py - Automatic OIDC verification
+TASKS = {
+    "default": {
+        "BACKEND": "django_database_task.cloudtasks.CloudTasksDatabaseBackend",
+        "OPTIONS": {
+            "CLOUD_TASKS_QUEUE": "default",
+            "OIDC_SERVICE_ACCOUNT_EMAIL": "my-sa@project.iam.gserviceaccount.com",
+            # OIDC_AUDIENCE is auto-detected from handler URL if not set
+        },
+    },
+}
+```
+
+Alternatively, you can use the decorator directly on your URL configuration:
+
+```python
+# urls.py
+from django.urls import path
+from django_database_task.views import ExecuteTaskView
+from django_database_task.cloudtasks import verify_cloud_tasks_oidc
+
+urlpatterns = [
+    path(
+        "tasks/execute/<uuid:task_id>/",
+        verify_cloud_tasks_oidc(
+            ExecuteTaskView.as_view(),
+            audience="https://myapp.example.com"
+        ),
+        name="execute_task",
+    ),
+]
+```
+
+### Detection Utilities
+
+You can use the detection functions directly:
+
+```python
+from django_database_task.cloudtasks import (
+    detect_gcp_project,
+    detect_gcp_location,
+    detect_task_handler_host,
+    is_cloud_run,
+    is_app_engine,
+)
+
+if is_cloud_run():
+    print(f"Running on Cloud Run in {detect_gcp_location()}")
+elif is_app_engine():
+    print(f"Running on App Engine in project {detect_gcp_project()}")
+```
+
 ## Django Admin
 
-The package includes a Django Admin integration to view task status:
+The package includes a Django Admin integration to view and manage tasks:
 
 - Task list with status badges
 - Filter by status, queue, backend
 - Search by task ID or path
 - View task arguments and results
 
+### Admin Actions
+
+The admin interface provides the following bulk actions:
+
+| Action | Description |
+|--------|-------------|
+| **Run selected tasks** | Execute selected tasks that are in READY status |
+| **Retry failed tasks** | Reset FAILED tasks to READY status and re-execute them |
+
+These actions are useful for:
+- Manually triggering task execution from the admin
+- Retrying failed tasks after fixing issues
+- Testing task execution during development
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.

{django_database_task-0.1.0 → django_database_task-0.2.0}/django_database_task/__init__.py

@@ -2,7 +2,7 @@
 django-database-task: A database-backed task queue backend for Django 6.0's task framework.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 
 def __getattr__(name):
@@ -12,6 +12,7 @@ def __getattr__(name):
         "get_pending_task_count",
         "process_one_task",
         "process_tasks",
+        "run_task_by_id",
     ):
         from . import executor
 
@@ -24,4 +25,5 @@ __all__ = [
     "get_pending_task_count",
     "process_one_task",
     "process_tasks",
+    "run_task_by_id",
 ]

{django_database_task-0.1.0 → django_database_task-0.2.0}/django_database_task/backends.py

@@ -19,6 +19,20 @@ class DatabaseTaskBackend(BaseTaskBackend):
     supports_get_result = True
     supports_priority = True
 
+    def get_auth_handler(self):
+        """
+        Get the authentication handler for task execution endpoints.
+
+        Subclasses can override this to provide custom authentication.
+        The handler should be a callable that takes a request and returns:
+        - None if authentication succeeds
+        - A JsonResponse with error details if authentication fails
+
+        Returns:
+            Callable or None
+        """
+        return None
+
     def enqueue(self, task, args, kwargs):
         """Enqueue a task to the database.