django-simpletask5 0.2.0__tar.gz → 0.2.1__tar.gz

{django_simpletask5-0.2.0 → django_simpletask5-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-simpletask5
-Version: 0.2.0
+Version: 0.2.1
 Summary: Lightweight async task execution framework for Django
 Author-email: rRR0VrFP <rrr0vrfp@qq.com>
 Maintainer-email: rRR0VrFP <rrr0vrfp@qq.com>
@@ -50,7 +50,8 @@ Dynamic: license-file
 - **自定义事件** — 通过 `task.trigger('event_name')` 触发任意事件
 - **灵活的执行器映射** — 不同事件可绑定不同的执行器类
 - **队列路由** — 不同事件可路由到不同优先级队列
-- **重试与超时** — 失败自动重试（指数退避），支持超时检测
+- **重试与超时** — 失败自动重试（指数退避），支持执行超时与 Pickup 超时两种检测
+- **拒绝回退** — 执行器可通过 `RejectException` 拒绝当前任务，消息自动重新入队等待下次调度
 - **加密字段** — 敏感数据自动加密存储
 - **Cron 调度** — 内置 crontab 守护进程，支持代码注册与数据库覆盖
 - **归档统计** — 已完成执行记录自动归档为加密 JSONL，并生成日统计
@@ -156,10 +157,15 @@ DJANGO_SIMPLETASK_HIGH_PRIORITY_QUEUE = 'django_simpletask5.queue.high_priority'
 ### 执行与重试
 
 ```python
-DJANGO_SIMPLETASK_DEFAULT_MAX_RETRIES = 3        # 默认最大重试次数
-DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS = 600  # 默认执行超时时间（秒）
+DJANGO_SIMPLETASK_DEFAULT_MAX_RETRIES = 3                  # 默认最大重试次数
+DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS = 600            # 默认执行超时（秒），任务开始执行后的超时限制
+DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS = 3600    # 默认 Pickup 超时（秒），等待 Worker 消费的时间限制
 ```
 
+框架区分两种超时：
+- **执行超时**（`timeout_seconds`）— 任务进入 `running` 状态后，必须在指定时间内完成，否则被 `StatusCheckExecutor` 标记超时。适用于保护实际执行不 hang 死。
+- **Pickup 超时**（`pickup_timeout_seconds`）— 任务创建后等待 Worker 消费的时间上限，也用于被拒绝回退后等待重新调度的保护。通常设得比执行超时更长，因为排队等待时间不可控。
+
 ### 归档
 
 ```python
@@ -235,6 +241,33 @@ class OrderCreateExecutor(BaseExecutor):
         return 'ok'
 ```
 
+执行器可以通过 `executor_class` 属性覆盖超时配置：
+
+```python
+class OrderCreateExecutor(BaseExecutor):
+    timeout_seconds = 300                       # 执行超时 5 分钟
+    pickup_timeout_seconds = 1800               # Pickup 超时 30 分钟
+```
+
+### 拒绝回退
+
+执行器在执行过程中遇到临时条件不满足（如资源上限），可以抛出 `RejectException` 拒绝本次执行：
+
+```python
+from django_simpletask5.executors.exceptions import RejectException
+
+class MyExecutor(BaseExecutor):
+    def execute(self, execution: TaskExecution) -> str | None:
+        if not self._can_proceed():
+            raise RejectException('Resource limit reached, try again later')
+```
+
+框架捕获后会：
+- 调用 `message.reject(requeue=True)` 将消息放回队列尾部，下次重新调度
+- `TaskExecution` 状态恢复为 `pending`，`started_at` 清空，等待下次 Worker 消费
+- **不消耗**重试次数
+- 刷新 `expire_time`（使用 Pickup 超时），防止被 `StatusCheckExecutor` 误回收
+
 ### 3. 启动 Worker
 
 默认只监听 `default` 队列，`high_priority` 队列需要单独启动 Worker 处理。
@@ -315,11 +348,17 @@ Task 模型变更 → Django 信号 → 创建 TaskExecution 并发布到消息
                                                     ↓
 Worker 消费消息 → 获取分布式锁 → 加载执行器 → 执行并保存结果
                                                     ↓
-失败时自动重试，完成后归档
+失败时自动重试/拒绝时重新入队，完成后归档
 ```
 
 ## Releases
 
+### 0.2.1
+
+- **拒绝回退机制** — 新增 `RejectException`，执行器可抛出该异常拒绝当前任务，消息自动重新入队等待下次调度，不消耗重试次数
+- **区分两种超时** — 引入 `pickup_timeout_seconds`（等待 Worker 消费超时）与 `timeout_seconds`（执行超时）两种超时配置，`expire_time` 改用 Pickup 超时计算，超时检测更精准
+- **文档更新** — README 补充拒绝回退机制的使用说明和两种超时的详细解释
+
 ### 0.2.0
 
 - **破坏性变更**: 移除 `Task` 模型上的自定义主键，`task_id` 不再是主键字段，改为 `unique=True` 的唯一标识字段。所有 `Task` 子模型将自动获得 Django 默认的自增 `id` 主键。已有数据库需要迁移处理。

{django_simpletask5-0.2.0 → django_simpletask5-0.2.1}/README.md

@@ -11,7 +11,8 @@
 - **自定义事件** — 通过 `task.trigger('event_name')` 触发任意事件
 - **灵活的执行器映射** — 不同事件可绑定不同的执行器类
 - **队列路由** — 不同事件可路由到不同优先级队列
-- **重试与超时** — 失败自动重试（指数退避），支持超时检测
+- **重试与超时** — 失败自动重试（指数退避），支持执行超时与 Pickup 超时两种检测
+- **拒绝回退** — 执行器可通过 `RejectException` 拒绝当前任务，消息自动重新入队等待下次调度
 - **加密字段** — 敏感数据自动加密存储
 - **Cron 调度** — 内置 crontab 守护进程，支持代码注册与数据库覆盖
 - **归档统计** — 已完成执行记录自动归档为加密 JSONL，并生成日统计
@@ -117,10 +118,15 @@ DJANGO_SIMPLETASK_HIGH_PRIORITY_QUEUE = 'django_simpletask5.queue.high_priority'
 ### 执行与重试
 
 ```python
-DJANGO_SIMPLETASK_DEFAULT_MAX_RETRIES = 3        # 默认最大重试次数
-DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS = 600  # 默认执行超时时间（秒）
+DJANGO_SIMPLETASK_DEFAULT_MAX_RETRIES = 3                  # 默认最大重试次数
+DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS = 600            # 默认执行超时（秒），任务开始执行后的超时限制
+DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS = 3600    # 默认 Pickup 超时（秒），等待 Worker 消费的时间限制
 ```
 
+框架区分两种超时：
+- **执行超时**（`timeout_seconds`）— 任务进入 `running` 状态后，必须在指定时间内完成，否则被 `StatusCheckExecutor` 标记超时。适用于保护实际执行不 hang 死。
+- **Pickup 超时**（`pickup_timeout_seconds`）— 任务创建后等待 Worker 消费的时间上限，也用于被拒绝回退后等待重新调度的保护。通常设得比执行超时更长，因为排队等待时间不可控。
+
 ### 归档
 
 ```python
@@ -196,6 +202,33 @@ class OrderCreateExecutor(BaseExecutor):
         return 'ok'
 ```
 
+执行器可以通过 `executor_class` 属性覆盖超时配置：
+
+```python
+class OrderCreateExecutor(BaseExecutor):
+    timeout_seconds = 300                       # 执行超时 5 分钟
+    pickup_timeout_seconds = 1800               # Pickup 超时 30 分钟
+```
+
+### 拒绝回退
+
+执行器在执行过程中遇到临时条件不满足（如资源上限），可以抛出 `RejectException` 拒绝本次执行：
+
+```python
+from django_simpletask5.executors.exceptions import RejectException
+
+class MyExecutor(BaseExecutor):
+    def execute(self, execution: TaskExecution) -> str | None:
+        if not self._can_proceed():
+            raise RejectException('Resource limit reached, try again later')
+```
+
+框架捕获后会：
+- 调用 `message.reject(requeue=True)` 将消息放回队列尾部，下次重新调度
+- `TaskExecution` 状态恢复为 `pending`，`started_at` 清空，等待下次 Worker 消费
+- **不消耗**重试次数
+- 刷新 `expire_time`（使用 Pickup 超时），防止被 `StatusCheckExecutor` 误回收
+
 ### 3. 启动 Worker
 
 默认只监听 `default` 队列，`high_priority` 队列需要单独启动 Worker 处理。
@@ -276,11 +309,17 @@ Task 模型变更 → Django 信号 → 创建 TaskExecution 并发布到消息
                                                     ↓
 Worker 消费消息 → 获取分布式锁 → 加载执行器 → 执行并保存结果
                                                     ↓
-失败时自动重试，完成后归档
+失败时自动重试/拒绝时重新入队，完成后归档
 ```
 
 ## Releases
 
+### 0.2.1
+
+- **拒绝回退机制** — 新增 `RejectException`，执行器可抛出该异常拒绝当前任务，消息自动重新入队等待下次调度，不消耗重试次数
+- **区分两种超时** — 引入 `pickup_timeout_seconds`（等待 Worker 消费超时）与 `timeout_seconds`（执行超时）两种超时配置，`expire_time` 改用 Pickup 超时计算，超时检测更精准
+- **文档更新** — README 补充拒绝回退机制的使用说明和两种超时的详细解释
+
 ### 0.2.0
 
 - **破坏性变更**: 移除 `Task` 模型上的自定义主键，`task_id` 不再是主键字段，改为 `unique=True` 的唯一标识字段。所有 `Task` 子模型将自动获得 Django 默认的自增 `id` 主键。已有数据库需要迁移处理。

{django_simpletask5-0.2.0 → django_simpletask5-0.2.1}/django_simpletask5/core/defaults.py

@@ -4,6 +4,7 @@ DJANGO_SIMPLETASK_LOCK_TIMEOUT = getattr(settings, 'DJANGO_SIMPLETASK_LOCK_TIMEO
 
 DJANGO_SIMPLETASK_DEFAULT_MAX_RETRIES = getattr(settings, 'DJANGO_SIMPLETASK_DEFAULT_MAX_RETRIES', 3)
 DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS = getattr(settings, 'DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS', 600)
+DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS = getattr(settings, 'DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS', 3600)
 
 DJANGO_SIMPLETASK_ARCHIVE_PATH = getattr(settings, 'DJANGO_SIMPLETASK_ARCHIVE_PATH', 'django_simpletask5_archives')
 DJANGO_SIMPLETASK_ARCHIVE_SALT = getattr(settings, 'DJANGO_SIMPLETASK_ARCHIVE_SALT', 'django-simpletask5-archive')

{django_simpletask5-0.2.0 → django_simpletask5-0.2.1}/django_simpletask5/core/publisher.py

@@ -6,7 +6,7 @@ from django.db import transaction
 from django.utils import timezone
 
 from django_simpletask5.models import TaskExecution
-from django_simpletask5.core.defaults import DJANGO_SIMPLETASK_DEFAULT_QUEUE, DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS
+from django_simpletask5.core.defaults import DJANGO_SIMPLETASK_DEFAULT_QUEUE, DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS, DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS
 from django_simpletask5.executors.loader import load_executor_class
 
 logger = logging.getLogger(__name__)
@@ -22,6 +22,16 @@ def _resolve_timeout_seconds(executor_class_path: str) -> int:
     return DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS
 
 
+def _resolve_pickup_timeout_seconds(executor_class_path: str) -> int:
+    try:
+        cls = load_executor_class(executor_class_path)
+        if cls.pickup_timeout_seconds is not None:
+            return cls.pickup_timeout_seconds
+    except Exception:
+        logger.warning('Failed to load executor %s for pickup timeout resolution', executor_class_path)
+    return DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS
+
+
 def create_and_publish(task, trigger_event, extra_context=None):
     executor_class_path = task.get_executor_class_path(event=trigger_event)
     queue_name = task.get_queue_name(event=trigger_event)
@@ -43,6 +53,7 @@ def create_and_publish(task, trigger_event, extra_context=None):
         executor_class=executor_class_path,
         status='pending',
         timeout_seconds=_resolve_timeout_seconds(executor_class_path),
+        pickup_timeout_seconds=_resolve_pickup_timeout_seconds(executor_class_path),
         context=json.dumps(serialized_context, default=str) if serialized_context else None,
     )
     execution.save()

django_simpletask5-0.2.1/django_simpletask5/executors/base.py

@@ -0,0 +1,35 @@
+from datetime import timedelta
+
+from django.utils import timezone
+
+from django_simpletask5.models import TaskExecution
+from django_simpletask5.core.defaults import DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS
+
+
+class BaseExecutor:
+    timeout_seconds: int | None = None
+    pickup_timeout_seconds: int | None = None
+    total_tasks_count: int | None = None
+    done_tasks_count: int | None = None
+
+    def get_tasks_count(self, execution: TaskExecution) -> int | None:
+        return 1
+
+    def get_tasks(self, execution: TaskExecution):
+        yield None
+
+    def execute(self, execution: TaskExecution, task=None) -> str | None:
+        raise NotImplementedError('Subclasses must implement execute()')
+
+    def reject(self, execution: TaskExecution, reason: str = '') -> None:
+        """Handle task rejection - revert to pending and refresh expire_time."""
+        execution.status = 'pending'
+        execution.started_at = None
+        execution.expire_time = timezone.now() + timedelta(
+            seconds=execution.pickup_timeout_seconds or DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS,
+        )
+        execution.save(update_fields=['status', 'started_at', 'expire_time', 'updated_at'])
+
+    @classmethod
+    def get_parameter_schema(cls):
+        return []

django_simpletask5-0.2.1/django_simpletask5/executors/exceptions.py

@@ -0,0 +1,13 @@
+class RejectException(Exception):
+    """Raise to reject and requeue the current task execution.
+
+    Raise this inside an executor's ``execute()`` method to signal that the
+    task should not be consumed now. The framework will:
+    - Not ack the message (calls ``message.reject(requeue=True)``)
+    - Revert ``TaskExecution`` status to ``pending`` and clear ``started_at``
+    - Not consume a retry attempt
+    - Refresh ``expire_time`` using pickup timeout
+
+    This is useful for transient conditions like resource limits or
+    temporary unavailability that should be retried later.
+    """

django_simpletask5-0.2.1/django_simpletask5/executors/retry_timeout.py

@@ -0,0 +1,66 @@
+import json
+import logging
+
+from django.db import models, transaction
+
+from django_simpletask5.models import TaskExecution
+from django_simpletask5.executors.base import BaseExecutor
+
+
+def _publish_message_by_id(execution_id):
+    from django_simpletask5.core.publisher import _publish_message
+    try:
+        exec_record = TaskExecution.objects.get(pk=execution_id)
+        _publish_message(exec_record)
+    except TaskExecution.DoesNotExist:
+        logger.warning('Execution %s not found for retry publish', execution_id)
+
+logger = logging.getLogger(__name__)
+
+
+class RetryTimeoutExecutor(BaseExecutor):
+    def execute(self, execution: TaskExecution, task=None) -> str | None:
+        from functools import partial
+        from django_simpletask5.core.publisher import _publish_message
+
+        timeout_records = TaskExecution.objects.filter(
+            status='timeout',
+            retry_count__lt=models.F('max_retries'),
+        )
+
+        # Pickup timeouts — task was never picked up, don't consume retry
+        pickup_ids = list(
+            timeout_records.filter(started_at__isnull=True)
+            .values_list('pk', flat=True)
+        )
+        if pickup_ids:
+            TaskExecution.objects.filter(pk__in=pickup_ids).update(
+                status='retry',
+            )
+            for exec_id in pickup_ids:
+                transaction.on_commit(
+                    partial(_publish_message_by_id, exec_id)
+                )
+
+        # Execution timeouts — task was actually running, consume retry
+        exec_ids = list(
+            timeout_records.filter(started_at__isnull=False)
+            .values_list('pk', flat=True)
+        )
+        if exec_ids:
+            TaskExecution.objects.filter(pk__in=exec_ids).update(
+                status='retry',
+                retry_count=models.F('retry_count') + 1,
+            )
+            for exec_id in exec_ids:
+                transaction.on_commit(
+                    partial(_publish_message_by_id, exec_id)
+                )
+
+        total = len(pickup_ids) + len(exec_ids)
+        return json.dumps({
+            'retried': total,
+            'pickup_timeout_retried': len(pickup_ids),
+            'exec_timeout_retried': len(exec_ids),
+            'success': True,
+        })

{django_simpletask5-0.2.0 → django_simpletask5-0.2.1}/django_simpletask5/management/commands/django_simpletask_crontab.py

@@ -10,7 +10,7 @@ from django.utils import timezone
 
 from django_simpletask5.models import CronJob, TaskExecution
 from django_simpletask5.core.lock import get_lock_manager
-from django_simpletask5.core.defaults import DJANGO_SIMPLETASK_LOCK_TIMEOUT, DJANGO_SIMPLETASK_DEFAULT_QUEUE, DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS
+from django_simpletask5.core.defaults import DJANGO_SIMPLETASK_LOCK_TIMEOUT, DJANGO_SIMPLETASK_DEFAULT_QUEUE, DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS, DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS
 from django_simpletask5.executors.loader import load_executor_class
 
 logger = logging.getLogger(__name__)
@@ -142,10 +142,13 @@ class Command(BaseCommand):
             context.update(cron_params)
 
         timeout_seconds = DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS
+        pickup_timeout_seconds = DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS
         try:
             cls = load_executor_class(cronjob.executor_class)
             if cls.timeout_seconds is not None:
                 timeout_seconds = cls.timeout_seconds
+            if cls.pickup_timeout_seconds is not None:
+                pickup_timeout_seconds = cls.pickup_timeout_seconds
         except Exception:
             pass
 
@@ -154,6 +157,7 @@ class Command(BaseCommand):
             executor_class=cronjob.executor_class,
             status='pending',
             timeout_seconds=timeout_seconds,
+            pickup_timeout_seconds=pickup_timeout_seconds,
             context=json.dumps(context, default=str),
         )
         execution.save()

{django_simpletask5-0.2.0 → django_simpletask5-0.2.1}/django_simpletask5/management/commands/django_simpletask_executor.py

@@ -12,6 +12,7 @@ from django.db import close_old_connections, OperationalError, InterfaceError
 from django.utils import timezone
 
 from django_simpletask5.models import TaskExecution
+from django_simpletask5.executors.exceptions import RejectException
 from django_simpletask5.executors.loader import load_executor
 from django_simpletask5.core.lock import get_lock_manager
 from django_simpletask5.core.defaults import DJANGO_SIMPLETASK_LOCK_TIMEOUT, DJANGO_SIMPLETASK_DEFAULT_QUEUE, DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS
@@ -177,6 +178,10 @@ class ExecutorWorker:
                     execution.save(update_fields=['status', 'result', 'done_tasks_count', 'finished_at', 'updated_at'])
 
                     logger.info('Execution %s completed with status %s', execution_id, execution.status)
+                except RejectException as e:
+                    logger.debug('Execution %s rejected (%s), requeueing', execution_id, e)
+                    executor.reject(execution, reason=str(e))
+                    return False
                 except Exception as e:
                     logger.exception('Execution %s failed', execution_id)
                     execution.error_message = str(e)

django_simpletask5-0.2.1/django_simpletask5/migrations/0008_taskexecution_pickup_timeout_seconds.py

@@ -0,0 +1,20 @@
+# Generated by Django 5.2.15 on 2026-07-11 14:54
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("django_simpletask5", "0007_rename_task_model_to_executor_class_in_stat"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="taskexecution",
+            name="pickup_timeout_seconds",
+            field=models.IntegerField(
+                default=3600, verbose_name="Pickup timeout seconds"
+            ),
+        ),
+    ]

{django_simpletask5-0.2.0 → django_simpletask5-0.2.1}/django_simpletask5/models.py

@@ -11,6 +11,7 @@ from django_safe_fields.fields import SafeTextField
 from django_simpletask5.core.defaults import (
     DJANGO_SIMPLETASK_DEFAULT_MAX_RETRIES,
     DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS,
+    DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS,
     DJANGO_SIMPLETASK_FIELD_CIPHER_CLASS,
 )
 
@@ -120,6 +121,7 @@ class TaskExecution(models.Model):
     retry_count = models.IntegerField(verbose_name=_('Retry count'), default=0)
     max_retries = models.IntegerField(verbose_name=_('Max retries'), default=DJANGO_SIMPLETASK_DEFAULT_MAX_RETRIES)
     timeout_seconds = models.IntegerField(verbose_name=_('Timeout seconds'), default=DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS)
+    pickup_timeout_seconds = models.IntegerField(verbose_name=_('Pickup timeout seconds'), default=DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS)
     expire_time = models.DateTimeField(verbose_name=_('Expire time'), null=True, blank=True, db_index=True)
     started_at = models.DateTimeField(verbose_name=_('Started at'), null=True, blank=True)
     finished_at = models.DateTimeField(verbose_name=_('Finished at'), null=True, blank=True)
@@ -203,7 +205,7 @@ class TaskExecution(models.Model):
 
     def save(self, *args, **kwargs):
         if not self.expire_time:
-            timeout = self.timeout_seconds or DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS
+            timeout = self.pickup_timeout_seconds or DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS
             self.expire_time = timezone.now() + timedelta(seconds=timeout)
         super().save(*args, **kwargs)
 

{django_simpletask5-0.2.0 → django_simpletask5-0.2.1}/django_simpletask5.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-simpletask5
-Version: 0.2.0
+Version: 0.2.1
 Summary: Lightweight async task execution framework for Django
 Author-email: rRR0VrFP <rrr0vrfp@qq.com>
 Maintainer-email: rRR0VrFP <rrr0vrfp@qq.com>
@@ -50,7 +50,8 @@ Dynamic: license-file
 - **自定义事件** — 通过 `task.trigger('event_name')` 触发任意事件
 - **灵活的执行器映射** — 不同事件可绑定不同的执行器类
 - **队列路由** — 不同事件可路由到不同优先级队列
-- **重试与超时** — 失败自动重试（指数退避），支持超时检测
+- **重试与超时** — 失败自动重试（指数退避），支持执行超时与 Pickup 超时两种检测
+- **拒绝回退** — 执行器可通过 `RejectException` 拒绝当前任务，消息自动重新入队等待下次调度
 - **加密字段** — 敏感数据自动加密存储
 - **Cron 调度** — 内置 crontab 守护进程，支持代码注册与数据库覆盖
 - **归档统计** — 已完成执行记录自动归档为加密 JSONL，并生成日统计
@@ -156,10 +157,15 @@ DJANGO_SIMPLETASK_HIGH_PRIORITY_QUEUE = 'django_simpletask5.queue.high_priority'
 ### 执行与重试
 
 ```python
-DJANGO_SIMPLETASK_DEFAULT_MAX_RETRIES = 3        # 默认最大重试次数
-DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS = 600  # 默认执行超时时间（秒）
+DJANGO_SIMPLETASK_DEFAULT_MAX_RETRIES = 3                  # 默认最大重试次数
+DJANGO_SIMPLETASK_DEFAULT_TIMEOUT_SECONDS = 600            # 默认执行超时（秒），任务开始执行后的超时限制
+DJANGO_SIMPLETASK_DEFAULT_PICKUP_TIMEOUT_SECONDS = 3600    # 默认 Pickup 超时（秒），等待 Worker 消费的时间限制
 ```
 
+框架区分两种超时：
+- **执行超时**（`timeout_seconds`）— 任务进入 `running` 状态后，必须在指定时间内完成，否则被 `StatusCheckExecutor` 标记超时。适用于保护实际执行不 hang 死。
+- **Pickup 超时**（`pickup_timeout_seconds`）— 任务创建后等待 Worker 消费的时间上限，也用于被拒绝回退后等待重新调度的保护。通常设得比执行超时更长，因为排队等待时间不可控。
+
 ### 归档
 
 ```python
@@ -235,6 +241,33 @@ class OrderCreateExecutor(BaseExecutor):
         return 'ok'
 ```
 
+执行器可以通过 `executor_class` 属性覆盖超时配置：
+
+```python
+class OrderCreateExecutor(BaseExecutor):
+    timeout_seconds = 300                       # 执行超时 5 分钟
+    pickup_timeout_seconds = 1800               # Pickup 超时 30 分钟
+```
+
+### 拒绝回退
+
+执行器在执行过程中遇到临时条件不满足（如资源上限），可以抛出 `RejectException` 拒绝本次执行：
+
+```python
+from django_simpletask5.executors.exceptions import RejectException
+
+class MyExecutor(BaseExecutor):
+    def execute(self, execution: TaskExecution) -> str | None:
+        if not self._can_proceed():
+            raise RejectException('Resource limit reached, try again later')
+```
+
+框架捕获后会：
+- 调用 `message.reject(requeue=True)` 将消息放回队列尾部，下次重新调度
+- `TaskExecution` 状态恢复为 `pending`，`started_at` 清空，等待下次 Worker 消费
+- **不消耗**重试次数
+- 刷新 `expire_time`（使用 Pickup 超时），防止被 `StatusCheckExecutor` 误回收
+
 ### 3. 启动 Worker
 
 默认只监听 `default` 队列，`high_priority` 队列需要单独启动 Worker 处理。
@@ -315,11 +348,17 @@ Task 模型变更 → Django 信号 → 创建 TaskExecution 并发布到消息
                                                     ↓
 Worker 消费消息 → 获取分布式锁 → 加载执行器 → 执行并保存结果
                                                     ↓
-失败时自动重试，完成后归档
+失败时自动重试/拒绝时重新入队，完成后归档
 ```
 
 ## Releases
 
+### 0.2.1
+
+- **拒绝回退机制** — 新增 `RejectException`，执行器可抛出该异常拒绝当前任务，消息自动重新入队等待下次调度，不消耗重试次数
+- **区分两种超时** — 引入 `pickup_timeout_seconds`（等待 Worker 消费超时）与 `timeout_seconds`（执行超时）两种超时配置，`expire_time` 改用 Pickup 超时计算，超时检测更精准
+- **文档更新** — README 补充拒绝回退机制的使用说明和两种超时的详细解释
+
 ### 0.2.0
 
 - **破坏性变更**: 移除 `Task` 模型上的自定义主键，`task_id` 不再是主键字段，改为 `unique=True` 的唯一标识字段。所有 `Task` 子模型将自动获得 Django 默认的自增 `id` 主键。已有数据库需要迁移处理。

{django_simpletask5-0.2.0 → django_simpletask5-0.2.1}/django_simpletask5.egg-info/SOURCES.txt

@@ -24,6 +24,7 @@ django_simpletask5/executors/__init__.py
 django_simpletask5/executors/archive.py
 django_simpletask5/executors/base.py
 django_simpletask5/executors/bash_script.py
+django_simpletask5/executors/exceptions.py
 django_simpletask5/executors/loader.py
 django_simpletask5/executors/ping_pong.py
 django_simpletask5/executors/python_script.py
@@ -45,6 +46,7 @@ django_simpletask5/migrations/0004_alter_cronjob_is_modified_by_user.py
 django_simpletask5/migrations/0005_alter_cronjob_is_modified_by_user_help.py
 django_simpletask5/migrations/0006_alter_cronjob_options_alter_taskexecution_created_at_and_more.py
 django_simpletask5/migrations/0007_rename_task_model_to_executor_class_in_stat.py
+django_simpletask5/migrations/0008_taskexecution_pickup_timeout_seconds.py
 django_simpletask5/migrations/__init__.py
 django_simpletask5/services/__init__.py
 django_simpletask5/services/archive.py

{django_simpletask5-0.2.0 → django_simpletask5-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "django-simpletask5"
-version = "0.2.0"
+version = "0.2.1"
 description = "Lightweight async task execution framework for Django"
 readme = "README.md"
 license = {text = "MIT"}

django_simpletask5-0.2.0/django_simpletask5/executors/base.py

@@ -1,20 +0,0 @@
-from django_simpletask5.models import TaskExecution
-
-
-class BaseExecutor:
-    timeout_seconds: int | None = None
-    total_tasks_count: int | None = None
-    done_tasks_count: int | None = None
-
-    def get_tasks_count(self, execution: TaskExecution) -> int | None:
-        return 1
-
-    def get_tasks(self, execution: TaskExecution):
-        yield None
-
-    def execute(self, execution: TaskExecution, task=None) -> str | None:
-        raise NotImplementedError('Subclasses must implement execute()')
-
-    @classmethod
-    def get_parameter_schema(cls):
-        return []

django_simpletask5-0.2.0/django_simpletask5/executors/retry_timeout.py

@@ -1,47 +0,0 @@
-import json
-import logging
-
-from django.db import models, transaction
-
-from django_simpletask5.models import TaskExecution
-from django_simpletask5.executors.base import BaseExecutor
-
-
-def _publish_message_by_id(execution_id):
-    from django_simpletask5.core.publisher import _publish_message
-    try:
-        exec_record = TaskExecution.objects.get(pk=execution_id)
-        _publish_message(exec_record)
-    except TaskExecution.DoesNotExist:
-        logger.warning('Execution %s not found for retry publish', execution_id)
-
-logger = logging.getLogger(__name__)
-
-
-class RetryTimeoutExecutor(BaseExecutor):
-    def execute(self, execution: TaskExecution, task=None) -> str | None:
-        retryable = TaskExecution.objects.filter(
-            status='timeout',
-            retry_count__lt=models.F('max_retries'),
-        )
-        ids = list(retryable.values_list('pk', flat=True))
-
-        if not ids:
-            return json.dumps({'retried': 0, 'success': True})
-
-        TaskExecution.objects.filter(pk__in=ids).update(
-            status='retry',
-            retry_count=models.F('retry_count') + 1,
-        )
-
-        from django_simpletask5.core.publisher import _publish_message
-        from functools import partial
-        for exec_id in ids:
-            transaction.on_commit(
-                partial(_publish_message_by_id, exec_id)
-            )
-
-        return json.dumps({
-            'retried': len(ids),
-            'success': True,
-        })