Metadata-Version: 2.4
Name: linkmind-task-queue
Version: 0.5.0
Summary: Pluggable task queue, fair executor and distributed resource limiter
Author: Linkmind
License-Expression: MIT
Keywords: queue,task queue,redis,sqlite,async,worker
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: redis
Requires-Dist: redis>=5; extra == "redis"
Dynamic: license-file

# linkmind-task-queue

轻量、可插拔的中文任务队列与并发管理 SDK，支持 `memory`、`sqlite` 和
`redis` 三种后端。`0.5.0` 增加按任务类型限流、公平批次执行器、通用资源
租约、Redis 跨进程全局限流、协作取消、超时和可观测指标。

SDK 只负责消息投递、消费、重试、恢复和 worker 生命周期，不绑定业务模型、Web
框架或 LLM。任务结果、业务状态和大文件产物由宿主应用自行管理。

## 核心能力

- `QueueRuntime`：持久消息队列、按任务类型并发、重试和恢复；
- `FairTaskExecutor`：任务级、队列级、批次级轮询公平调度；
- `LocalResourceLimiter`：单进程 FIFO 资源限制；
- `RedisResourceLimiter`：跨进程资源租约和过期恢复；
- `TaskContext`：协作取消与执行截止时间；
- `health()` / `metrics()`：active、pending、queue wait、resource wait。

## 安装

```bash
pip install linkmind-task-queue
```

使用 Redis 后端时安装可选依赖：

```bash
pip install "linkmind-task-queue[redis]"
```

## 快速使用

```python
from threading import Event

from linkmind_task_queue import QueueConfig, QueueRuntime

finished = Event()


def handle_hello(payload: dict[str, object]) -> None:
    print("收到任务:", payload)
    finished.set()


runtime = QueueRuntime(QueueConfig(
    mode="memory",
    worker_threads=8,
    queue_limits={"hello": 2},
    resource_limits={"external_api": 4},
    task_resources={"hello": ("external_api",)},
))
runtime.register("hello", handle_hello)
runtime.start()
try:
    message_id = runtime.submit("hello", {"name": "linkmind"})
    print(message_id, finished.wait(5), runtime.health())
finally:
    runtime.stop()
```

## 安装

```bash
pip install linkmind-task-queue
pip install "linkmind-task-queue[redis]"  # 使用 Redis 后端
```

## 三种模式

| 模式 | 进程重启恢复 | 多进程共享 | 推荐用途 |
|---|---|---|---|
| `memory` | 否 | 否 | 测试、开发调试 |
| `sqlite` | 是 | 不建议 | 单机单进程 |
| `redis` | 是 | 是 | 服务化、多任务并发 |

## 文档导航

- [配置参考](docs/configuration.md)
- [使用说明](docs/usage.md)
- [三种后端差异](docs/backends.md)
- [重试与恢复](docs/retry-recovery.md)
- [部署、监控与排障](docs/operations.md)
- [API 参考](docs/api-reference.md)
- [可运行示例](examples/)

示例建议从项目根目录以模块方式运行：

```bash
python -m linkmind_task_queue.examples.memory_example
python -m linkmind_task_queue.examples.sqlite_example
TASK_QUEUE_REDIS_URL=redis://127.0.0.1:6379/0 \
  python -m linkmind_task_queue.examples.redis_example
```

SDK 使用至少一次处理语义，不保证 exactly-once。所有 handler 必须设计为幂等函数。

源码分发包构建：

```bash
python -m build --sdist
```
