tasklite-engine 1.4.2__tar.gz → 2.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/PKG-INFO +65 -43
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/README.md +64 -42
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/pyproject.toml +1 -0
- tasklite_engine-2.0.0/tasklite/__init__.py +202 -0
- tasklite_engine-2.0.0/tasklite/backend/__init__.py +23 -0
- tasklite_engine-2.0.0/tasklite/backend/base.py +381 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/backend/memory.py +131 -90
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/backend/sqlite_backend.py +442 -324
- tasklite_engine-2.0.0/tasklite/contrib/__init__.py +7 -0
- tasklite_engine-2.0.0/tasklite/engine/__init__.py +21 -0
- tasklite_engine-2.0.0/tasklite/engine/admission.py +323 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/channel.py +195 -168
- tasklite_engine-2.0.0/tasklite/engine/completion.py +440 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/config.py +64 -55
- tasklite_engine-2.0.0/tasklite/engine/dispatch.py +628 -0
- tasklite_engine-1.4.2/tasklite/taxonomy.py → tasklite_engine-2.0.0/tasklite/engine/errorclass.py +323 -371
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/governor.py +143 -110
- tasklite_engine-1.4.2/tasklite/engine/inflight.py → tasklite_engine-2.0.0/tasklite/engine/in_flight.py +46 -26
- tasklite_engine-1.4.2/tasklite/engine/console.py → tasklite_engine-2.0.0/tasklite/engine/ops.py +141 -87
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/recovery.py +153 -89
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/resource.py +131 -128
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/runtime.py +175 -116
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/scheduler.py +84 -79
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/session.py +24 -12
- tasklite_engine-2.0.0/tasklite/engine/store.py +784 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/engine/types.py +54 -40
- tasklite_engine-1.4.2/tasklite/engine/pacing.py → tasklite_engine-2.0.0/tasklite/engine/wait.py +13 -7
- tasklite_engine-2.0.0/tasklite/exceptions.py +66 -0
- tasklite_engine-2.0.0/tasklite/hooks.py +69 -0
- tasklite_engine-2.0.0/tasklite/models/__init__.py +11 -0
- tasklite_engine-2.0.0/tasklite/models/attempt.py +138 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/models/context.py +87 -89
- tasklite_engine-2.0.0/tasklite/models/job.py +437 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/models/state.py +36 -30
- tasklite_engine-2.0.0/tasklite/models/task.py +268 -0
- tasklite_engine-2.0.0/tasklite/pipeline.py +698 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/testing.py +8 -8
- tasklite_engine-2.0.0/tasklite/utils/__init__.py +4 -0
- tasklite_engine-2.0.0/tasklite/utils/clock.py +24 -0
- tasklite_engine-1.4.2/tasklite/utils/injective.py → tasklite_engine-2.0.0/tasklite/utils/encoding.py +79 -57
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/utils/ipc.py +80 -38
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/utils/jsonutil.py +17 -8
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/utils/lockfile.py +25 -13
- tasklite_engine-2.0.0/tasklite/wrappers/__init__.py +19 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/wrappers/discovery.py +266 -187
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/wrappers/http.py +355 -290
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite_engine.egg-info/PKG-INFO +65 -43
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite_engine.egg-info/SOURCES.txt +17 -7
- tasklite_engine-2.0.0/tests/test_encoding.py +533 -0
- tasklite_engine-2.0.0/tests/test_exceptions.py +99 -0
- tasklite_engine-2.0.0/tests/test_hooks.py +118 -0
- tasklite_engine-2.0.0/tests/test_jsonutil.py +97 -0
- tasklite_engine-2.0.0/tests/test_package_surface.py +246 -0
- tasklite_engine-2.0.0/tests/test_pipeline.py +970 -0
- tasklite_engine-2.0.0/tests/test_testing.py +187 -0
- tasklite_engine-1.4.2/tasklite/__init__.py +0 -139
- tasklite_engine-1.4.2/tasklite/backend/__init__.py +0 -12
- tasklite_engine-1.4.2/tasklite/backend/base.py +0 -256
- tasklite_engine-1.4.2/tasklite/contrib/__init__.py +0 -6
- tasklite_engine-1.4.2/tasklite/engine/__init__.py +0 -20
- tasklite_engine-1.4.2/tasklite/engine/completion.py +0 -380
- tasklite_engine-1.4.2/tasklite/engine/dispatch.py +0 -465
- tasklite_engine-1.4.2/tasklite/engine/policy.py +0 -448
- tasklite_engine-1.4.2/tasklite/engine/store.py +0 -692
- tasklite_engine-1.4.2/tasklite/exceptions.py +0 -54
- tasklite_engine-1.4.2/tasklite/hooks.py +0 -49
- tasklite_engine-1.4.2/tasklite/models/__init__.py +0 -6
- tasklite_engine-1.4.2/tasklite/models/job.py +0 -510
- tasklite_engine-1.4.2/tasklite/pipeline.py +0 -591
- tasklite_engine-1.4.2/tasklite/utils/__init__.py +0 -7
- tasklite_engine-1.4.2/tasklite/wrappers/__init__.py +0 -53
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/LICENSE +0 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/setup.cfg +0 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite/py.typed +0 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite_engine.egg-info/dependency_links.txt +0 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite_engine.egg-info/requires.txt +0 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tasklite_engine.egg-info/top_level.txt +0 -0
- {tasklite_engine-1.4.2 → tasklite_engine-2.0.0}/tests/test_packaging.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: tasklite-engine
|
|
3
|
-
Version:
|
|
3
|
+
Version: 2.0.0
|
|
4
4
|
Summary: A lightweight task orchestration engine with zero external dependencies, process isolation, and ACID persistence
|
|
5
5
|
License-Expression: MIT
|
|
6
6
|
Project-URL: Homepage, https://github.com/CaptainLi321/tasklite
|
|
@@ -37,7 +37,7 @@ Dynamic: license-file
|
|
|
37
37
|
[](LICENSE)
|
|
38
38
|
[]()
|
|
39
39
|
[-orange.svg)]()
|
|
40
|
-
[]()
|
|
41
41
|
|
|
42
42
|
---
|
|
43
43
|
|
|
@@ -51,7 +51,7 @@ Dynamic: license-file
|
|
|
51
51
|
- **标准库进程池 (`multiprocessing.Pool` / `ProcessPoolExecutor`)**:
|
|
52
52
|
- ❌ 缺乏内置状态持久化,程序中断后已完成进度丢失;
|
|
53
53
|
- ❌ 子任务发生 C 扩展段错误 (SIGSEGV) 或内存泄露 (OOM) 时,容易导致主进程一同崩溃;
|
|
54
|
-
- ❌ 缺少全局速率限制与服务熔断机制,缺乏 DAG
|
|
54
|
+
- ❌ 缺少全局速率限制与服务熔断机制,缺乏 DAG 拓扑依赖与失败隔离。
|
|
55
55
|
- **重型分布式任务队列 (`Celery` / `Airflow` / `Temporal`)**:
|
|
56
56
|
- ❌ 强依赖 Redis、RabbitMQ、PostgreSQL 等外部服务,本地单机运行或轻量嵌入脚本时运维成本过高;
|
|
57
57
|
- ❌ 架构较重,不适合作为随用随走的轻量批处理脚手架。
|
|
@@ -59,7 +59,7 @@ Dynamic: license-file
|
|
|
59
59
|
**TaskLite 的设计定位**:
|
|
60
60
|
**零依赖的单机批处理脚手架**——只需 `pip install tasklite-engine`。
|
|
61
61
|
1. **多 Worker 并发加速**:多进程并行执行,充分利用多核算力,彻底解决单线程耗时长的问题;
|
|
62
|
-
2. **断点续跑防重跑**:以 SQLite WAL
|
|
62
|
+
2. **断点续跑防重跑**:以 SQLite WAL 事务表记录状态,已完成的任务自动跳过,失败任务立即重入队重试、预算耗尽进失败档案,杜绝因个别失败导致全量重跑;
|
|
63
63
|
3. **物理隔离与容灾**:主进程只负责调度,业务逻辑在独立子进程中运行并设超时强杀,即使子任务崩溃、死锁或系统断电,状态依然完整可恢复。
|
|
64
64
|
|
|
65
65
|
---
|
|
@@ -119,7 +119,7 @@ flowchart TD
|
|
|
119
119
|
|
|
120
120
|
### 2. ⚡ SQLite WAL 状态持久化 (ACID)
|
|
121
121
|
- 基于 SQLite WAL + `synchronous=FULL` 模式;
|
|
122
|
-
-
|
|
122
|
+
- 状态机(Wall 成功档案 / Queue 待办 / In-Flight 在途 / Failed 失败档案)在单次事务中原子转移;
|
|
123
123
|
- 遭遇中断或异常关机时,重启后支持 At-Least-Once 接续执行。
|
|
124
124
|
|
|
125
125
|
### 3. 🔍 函数式增量探索 (Functional Discovery)
|
|
@@ -132,7 +132,7 @@ flowchart TD
|
|
|
132
132
|
|
|
133
133
|
### 5. 🔗 DAG 拓扑依赖与级联熔断
|
|
134
134
|
- 任务通过 `depends_on` 声明依赖;
|
|
135
|
-
-
|
|
135
|
+
- 父任务失败进入失败档案时,所有下游依赖自动标记跳过 (`ERR_JOB_DEPENDENCY`),避免无效计算。
|
|
136
136
|
|
|
137
137
|
### 6. 📦 产物沙盒与自动清理
|
|
138
138
|
- `ctx.declare_output()` 声明产出文件,内置路径遍历防御 (`../` 拒绝);
|
|
@@ -140,7 +140,7 @@ flowchart TD
|
|
|
140
140
|
|
|
141
141
|
### 7. 🌐 组合式 HTTP 网络工具与快照守卫 (HTTP Wrappers)
|
|
142
142
|
- 开放 Callable 设计,支持原生 `urllib`、`requests`、`httpx` 或平台自定义签名 SDK;
|
|
143
|
-
- `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource`
|
|
143
|
+
- `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource` 全管线挂起,收敛异常三分类;
|
|
144
144
|
- `SQLiteSnapshotStore` 提供单射键原始响应快照持久化,支持全离线幂等重放;
|
|
145
145
|
- 内置标准 Netscape `cookies.txt` 解析工具。
|
|
146
146
|
|
|
@@ -167,31 +167,31 @@ from tasklite import TaskLite, Job, RetryError, RateLimitResource
|
|
|
167
167
|
|
|
168
168
|
logging.getLogger("tasklite").setLevel(logging.INFO)
|
|
169
169
|
|
|
170
|
-
# 1.
|
|
170
|
+
# 1. 定义任务处理器(在独立子进程中执行,必须模块级定义)
|
|
171
171
|
def download_handler(job: Job, ctx):
|
|
172
172
|
# 声明产出文件(失败时自动清理半残文件)
|
|
173
173
|
out = ctx.declare_output(f"./downloads/{job.job_id}.jpg", cleanup_on_fail=True)
|
|
174
|
-
|
|
174
|
+
|
|
175
175
|
# 模拟业务下载
|
|
176
176
|
success = do_download(job.payload["url"], out)
|
|
177
177
|
if not success:
|
|
178
|
-
raise RetryError("
|
|
179
|
-
|
|
178
|
+
raise RetryError("网络抖动,立即重入队重试")
|
|
179
|
+
|
|
180
180
|
return True, {"size": 1024, "path": str(out)}
|
|
181
181
|
|
|
182
|
-
# 2.
|
|
182
|
+
# 2. 初始化引擎(六步调用契约:初始化 → register_resource → register_task → enqueue → run → stop)
|
|
183
183
|
pipeline = TaskLite(
|
|
184
184
|
name="media_downloader",
|
|
185
185
|
state_dir="./state", # 状态持久化目录(SQLite WAL)
|
|
186
186
|
output_root="./downloads", # 产物沙盒根目录
|
|
187
|
-
max_workers=4, #
|
|
187
|
+
max_workers=4, # 并发子进程数(内部 __workers__ 容量资源,可覆盖)
|
|
188
188
|
)
|
|
189
189
|
|
|
190
|
-
# 3. 注册全局限速(每秒最多 2
|
|
191
|
-
pipeline.
|
|
192
|
-
pipeline.
|
|
190
|
+
# 3. 注册全局限速(每秒最多 2 次请求)与 Task 规格
|
|
191
|
+
pipeline.register_resource(RateLimitResource("api", interval_seconds=0.5))
|
|
192
|
+
pipeline.register_task("download", download_handler, default_resources={"api": 1.0})
|
|
193
193
|
|
|
194
|
-
# 4.
|
|
194
|
+
# 4. 入队并启动(阻塞直到队列全部完成,返回 RunSummary)
|
|
195
195
|
pipeline.enqueue([
|
|
196
196
|
Job("download", "img_001", payload={"url": "https://example.com/1.jpg"}),
|
|
197
197
|
Job("download", "img_002", payload={"url": "https://example.com/2.jpg"}),
|
|
@@ -201,6 +201,24 @@ pipeline.run()
|
|
|
201
201
|
|
|
202
202
|
---
|
|
203
203
|
|
|
204
|
+
## 🧭 三层模型(Task / Job / Attempt)
|
|
205
|
+
|
|
206
|
+
本引擎按实时系统理论建模为三层(设计总纲 [ADR-0004](docs/adr/0004-v2-parallel-rebuild.md),上位裁决 [ADR-0005](docs/adr/0005-v2-promotion.md)):
|
|
207
|
+
|
|
208
|
+
| 层 | 定义 | 持久化 |
|
|
209
|
+
|---|---|---|
|
|
210
|
+
| **Task(规格)** | 进程内注册的静态模板:task_type 名、handler、默认资源、payload_schema、默认 max_retries / timeout | 代码即规格,不落盘;注册于 `register_task` |
|
|
211
|
+
| **Job(逻辑实例)** | 一次有界激活;`uid = task_type::job_id` 身份不变 | queue 行 job_data JSON(uid 为主键) |
|
|
212
|
+
| **Attempt(执行轨迹)** | 一次物理执行的记录:attempt 序号、incarnation、起止时间、结局 | append-only 新表 `attempts` |
|
|
213
|
+
|
|
214
|
+
任一 attempts 行可回溯「哪次激活的第几次执行、由哪个 run 派发、结局如何、当前终态在哪、规格是什么」——端到端追溯链完整。完整使用指南见 **[`docs/V2_GUIDE.md`](docs/V2_GUIDE.md)**(权威);v1 → v2 命名映射见 [ADR-0004](docs/adr/0004-v2-parallel-rebuild.md);未来演进方向(CLI 直达、make 式级联更新、调度策略族)见 [ROADMAP](docs/ROADMAP.md)。**v1 已退役**(git 历史与 `v1-final` 标签留档)。
|
|
215
|
+
|
|
216
|
+
```python
|
|
217
|
+
from tasklite import TaskLite, Job, Task, AttemptRecord
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
204
222
|
## 🍳 实战 Recipes
|
|
205
223
|
|
|
206
224
|
### Recipe 1: 增量分页扫描器 (Discovery)
|
|
@@ -218,7 +236,7 @@ def item_id(post) -> str:
|
|
|
218
236
|
return str(post["id"]) # 唯一内容 ID
|
|
219
237
|
|
|
220
238
|
def process_item(job, ctx, post, content_id: str):
|
|
221
|
-
# 发现新内容时派生子任务(content_id
|
|
239
|
+
# 发现新内容时派生子任务(content_id 已做单射编码)
|
|
222
240
|
ctx.spawn(Job("download", content_id, payload={"url": post["url"]}))
|
|
223
241
|
|
|
224
242
|
# 注册增量探索
|
|
@@ -259,7 +277,7 @@ from tasklite import RateLimitHit
|
|
|
259
277
|
def fetch_handler(job, ctx):
|
|
260
278
|
resp = requests.get(job.payload["url"])
|
|
261
279
|
if resp.status_code == 429:
|
|
262
|
-
# 全管线挂起 api 资源 1
|
|
280
|
+
# 全管线挂起 api 资源 1 小时,状态持久化到磁盘,随后抛出瞬态重试
|
|
263
281
|
ctx.suspend_resource("api", seconds=3600)
|
|
264
282
|
raise RateLimitHit("Triggered 429, suspending API for 1h")
|
|
265
283
|
return True, resp.json()
|
|
@@ -286,8 +304,8 @@ def agent_worker(job: Job, ctx):
|
|
|
286
304
|
return True, {"tokens": result.get("usage", 0)}
|
|
287
305
|
|
|
288
306
|
pipeline = TaskLite(name="agent_batch", state_dir="./agent_state", max_workers=8)
|
|
289
|
-
pipeline.
|
|
290
|
-
pipeline.
|
|
307
|
+
pipeline.register_resource(RateLimitResource("llm_rpm", interval_seconds=0.1))
|
|
308
|
+
pipeline.register_task("analyze", agent_worker, default_resources={"llm_rpm": 1.0})
|
|
291
309
|
|
|
292
310
|
# 入队海量任务,中途即使断网或意外中断,重启后自动跳过已完成任务接续执行
|
|
293
311
|
pipeline.enqueue([
|
|
@@ -301,40 +319,43 @@ pipeline.run()
|
|
|
301
319
|
|
|
302
320
|
```python
|
|
303
321
|
from tasklite import TaskLite, RateLimitResource
|
|
304
|
-
from tasklite.wrappers.http import SQLiteSnapshotStore, http_guard,
|
|
322
|
+
from tasklite.wrappers.http import SQLiteSnapshotStore, http_guard, urllib_fetch
|
|
305
323
|
|
|
306
324
|
pipeline = TaskLite("crawler", state_dir="./states")
|
|
307
|
-
pipeline.
|
|
325
|
+
pipeline.register_resource(RateLimitResource("api", interval_seconds=1.0))
|
|
308
326
|
|
|
309
327
|
# 原始 HTTP 响应持久化快照(独立 snapshots.db,支持全离线重放与反爬保护)
|
|
310
328
|
snapshot_store = SQLiteSnapshotStore("./snapshots.db")
|
|
311
|
-
cached_fetch = snapshot_store.cached(
|
|
329
|
+
cached_fetch = snapshot_store.cached(urllib_fetch)
|
|
312
330
|
|
|
313
331
|
def crawler_handler(job, ctx):
|
|
314
|
-
# 429 时自动挂起 api 资源、5xx 瞬态重试、4xx
|
|
332
|
+
# 429 时自动挂起 api 资源、5xx 瞬态重试、4xx 直接进失败档案
|
|
315
333
|
with http_guard(ctx=ctx, resource="api", default_suspend_ttl=60.0):
|
|
316
334
|
resp = cached_fetch(job.payload["url"])
|
|
317
335
|
return resp.json()
|
|
318
336
|
|
|
319
|
-
pipeline.
|
|
337
|
+
pipeline.register_task("fetch", crawler_handler, default_resources={"api": 1.0})
|
|
320
338
|
```
|
|
321
339
|
|
|
322
340
|
---
|
|
323
341
|
|
|
324
342
|
|
|
325
|
-
## 🛠️
|
|
343
|
+
## 🛠️ 失败档案与运维 (Failed & Ops)
|
|
326
344
|
|
|
327
|
-
|
|
345
|
+
当任务重试预算耗尽或发生致命错误时,任务进入持久化**失败档案**(failed 表,与 wall 按 uid 互斥且唯一终态)。运维 API 仅限 `run()` 外调用:
|
|
328
346
|
|
|
329
347
|
```python
|
|
330
|
-
# 1.
|
|
331
|
-
for entry in pipeline.
|
|
332
|
-
print(f"UID: {entry.uid},
|
|
348
|
+
# 1. 检查失败详情(条目携带原始业务 payload 快照,补跑自足)
|
|
349
|
+
for entry in pipeline.list_failures():
|
|
350
|
+
print(f"UID: {entry.uid}, 原因: {entry.error}, 元数据: {entry.meta}")
|
|
351
|
+
|
|
352
|
+
# 2. 清理指定类型的失败档案(默认保留 fatal 错误,可入队同名任务重跑)
|
|
353
|
+
pipeline.clear_failures(task_types=["download"], keep_fatal=False)
|
|
333
354
|
|
|
334
|
-
#
|
|
335
|
-
pipeline.
|
|
355
|
+
# 3. 单条人工补跑:移出档案、按档案 payload 快照队首重入队
|
|
356
|
+
pipeline.retry_failure("download::img_001")
|
|
336
357
|
|
|
337
|
-
#
|
|
358
|
+
# 4. 精确或前缀清理历史(wall / failed)
|
|
338
359
|
pipeline.clear_history("download::")
|
|
339
360
|
```
|
|
340
361
|
|
|
@@ -350,25 +371,26 @@ tasklite/
|
|
|
350
371
|
│ ├── runtime.py # 核心运行期深模块、主循环事件泵 (EngineRuntime)
|
|
351
372
|
│ ├── config.py # RunConfig 静态装配快照、默认值唯一解析点
|
|
352
373
|
│ ├── session.py # RunSession 单次 run 生命周期状态与钩子单一出口
|
|
353
|
-
│ ├──
|
|
374
|
+
│ ├── wait.py # 事件泵等待/空闲决策纯函数
|
|
354
375
|
│ ├── types.py # 引擎公共值对象单一真相源
|
|
355
376
|
│ ├── store.py # 状态事务、3-strike 崩溃与死锁归因 (StateStore)
|
|
356
|
-
│ ├──
|
|
377
|
+
│ ├── ops.py # OpsConsole:run() 外纯运维接缝(管理 API 委托目标)
|
|
357
378
|
│ ├── dispatch.py # 任务派发状态机 (DispatchMachine)
|
|
358
379
|
│ ├── completion.py # 任务完成与提交 (CompletionMachine)
|
|
359
380
|
│ ├── recovery.py # 崩溃检测与恢复 (RecoveryOrchestrator)
|
|
360
381
|
│ ├── channel.py # IPC 与子进程执行通道 (ExecutionChannel / WorkerLaunchSpec)
|
|
361
|
-
│ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler)
|
|
362
|
-
│ ├──
|
|
382
|
+
│ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler / OrderingPolicy seam)
|
|
383
|
+
│ ├── admission.py # rerun 准入 (RerunPolicy) 与重入队节奏 (RequeuePolicy)
|
|
363
384
|
│ ├── governor.py # 死锁归因仲裁与依赖宽限 (DeadlockGovernor)
|
|
364
|
-
│ ├──
|
|
385
|
+
│ ├── in_flight.py # 在途作业租约追踪 (InFlightTracker)
|
|
386
|
+
│ ├── errorclass.py # 错误分类与校验分类深模块 (ErrorClassifier)
|
|
365
387
|
│ └── resource.py # 令牌桶限速与并发容量资源
|
|
366
388
|
├── backend/ # SQLite WAL 强一致事务持久化后端
|
|
367
|
-
├── models/ # Job /
|
|
368
|
-
├──
|
|
369
|
-
├── testing.py # fake_ctx:handler 单测的官方 TaskContext 构造器
|
|
389
|
+
├── models/ # Task / Job / Attempt / PipelineState / JobContext 数据模型
|
|
390
|
+
├── testing.py # fake_ctx:handler 单测的官方 JobContext 构造器
|
|
370
391
|
├── wrappers/ # discovery.py(增量扫描)/ http.py(网络守卫与快照)
|
|
371
|
-
|
|
392
|
+
├── contrib/ # 生态扩展套件与参考实现(核心不依赖)
|
|
393
|
+
└── utils/ # encoding(单射 %XX 转义)/ ipc(IPC 信号与降级落盘)/ clock / jsonutil(禁NaN)/ lockfile
|
|
372
394
|
```
|
|
373
395
|
|
|
374
396
|
---
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
[]()
|
|
10
10
|
[-orange.svg)]()
|
|
11
|
-
[]()
|
|
12
12
|
|
|
13
13
|
---
|
|
14
14
|
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
- **标准库进程池 (`multiprocessing.Pool` / `ProcessPoolExecutor`)**:
|
|
23
23
|
- ❌ 缺乏内置状态持久化,程序中断后已完成进度丢失;
|
|
24
24
|
- ❌ 子任务发生 C 扩展段错误 (SIGSEGV) 或内存泄露 (OOM) 时,容易导致主进程一同崩溃;
|
|
25
|
-
- ❌ 缺少全局速率限制与服务熔断机制,缺乏 DAG
|
|
25
|
+
- ❌ 缺少全局速率限制与服务熔断机制,缺乏 DAG 拓扑依赖与失败隔离。
|
|
26
26
|
- **重型分布式任务队列 (`Celery` / `Airflow` / `Temporal`)**:
|
|
27
27
|
- ❌ 强依赖 Redis、RabbitMQ、PostgreSQL 等外部服务,本地单机运行或轻量嵌入脚本时运维成本过高;
|
|
28
28
|
- ❌ 架构较重,不适合作为随用随走的轻量批处理脚手架。
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
**TaskLite 的设计定位**:
|
|
31
31
|
**零依赖的单机批处理脚手架**——只需 `pip install tasklite-engine`。
|
|
32
32
|
1. **多 Worker 并发加速**:多进程并行执行,充分利用多核算力,彻底解决单线程耗时长的问题;
|
|
33
|
-
2. **断点续跑防重跑**:以 SQLite WAL
|
|
33
|
+
2. **断点续跑防重跑**:以 SQLite WAL 事务表记录状态,已完成的任务自动跳过,失败任务立即重入队重试、预算耗尽进失败档案,杜绝因个别失败导致全量重跑;
|
|
34
34
|
3. **物理隔离与容灾**:主进程只负责调度,业务逻辑在独立子进程中运行并设超时强杀,即使子任务崩溃、死锁或系统断电,状态依然完整可恢复。
|
|
35
35
|
|
|
36
36
|
---
|
|
@@ -90,7 +90,7 @@ flowchart TD
|
|
|
90
90
|
|
|
91
91
|
### 2. ⚡ SQLite WAL 状态持久化 (ACID)
|
|
92
92
|
- 基于 SQLite WAL + `synchronous=FULL` 模式;
|
|
93
|
-
-
|
|
93
|
+
- 状态机(Wall 成功档案 / Queue 待办 / In-Flight 在途 / Failed 失败档案)在单次事务中原子转移;
|
|
94
94
|
- 遭遇中断或异常关机时,重启后支持 At-Least-Once 接续执行。
|
|
95
95
|
|
|
96
96
|
### 3. 🔍 函数式增量探索 (Functional Discovery)
|
|
@@ -103,7 +103,7 @@ flowchart TD
|
|
|
103
103
|
|
|
104
104
|
### 5. 🔗 DAG 拓扑依赖与级联熔断
|
|
105
105
|
- 任务通过 `depends_on` 声明依赖;
|
|
106
|
-
-
|
|
106
|
+
- 父任务失败进入失败档案时,所有下游依赖自动标记跳过 (`ERR_JOB_DEPENDENCY`),避免无效计算。
|
|
107
107
|
|
|
108
108
|
### 6. 📦 产物沙盒与自动清理
|
|
109
109
|
- `ctx.declare_output()` 声明产出文件,内置路径遍历防御 (`../` 拒绝);
|
|
@@ -111,7 +111,7 @@ flowchart TD
|
|
|
111
111
|
|
|
112
112
|
### 7. 🌐 组合式 HTTP 网络工具与快照守卫 (HTTP Wrappers)
|
|
113
113
|
- 开放 Callable 设计,支持原生 `urllib`、`requests`、`httpx` 或平台自定义签名 SDK;
|
|
114
|
-
- `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource`
|
|
114
|
+
- `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource` 全管线挂起,收敛异常三分类;
|
|
115
115
|
- `SQLiteSnapshotStore` 提供单射键原始响应快照持久化,支持全离线幂等重放;
|
|
116
116
|
- 内置标准 Netscape `cookies.txt` 解析工具。
|
|
117
117
|
|
|
@@ -138,31 +138,31 @@ from tasklite import TaskLite, Job, RetryError, RateLimitResource
|
|
|
138
138
|
|
|
139
139
|
logging.getLogger("tasklite").setLevel(logging.INFO)
|
|
140
140
|
|
|
141
|
-
# 1.
|
|
141
|
+
# 1. 定义任务处理器(在独立子进程中执行,必须模块级定义)
|
|
142
142
|
def download_handler(job: Job, ctx):
|
|
143
143
|
# 声明产出文件(失败时自动清理半残文件)
|
|
144
144
|
out = ctx.declare_output(f"./downloads/{job.job_id}.jpg", cleanup_on_fail=True)
|
|
145
|
-
|
|
145
|
+
|
|
146
146
|
# 模拟业务下载
|
|
147
147
|
success = do_download(job.payload["url"], out)
|
|
148
148
|
if not success:
|
|
149
|
-
raise RetryError("
|
|
150
|
-
|
|
149
|
+
raise RetryError("网络抖动,立即重入队重试")
|
|
150
|
+
|
|
151
151
|
return True, {"size": 1024, "path": str(out)}
|
|
152
152
|
|
|
153
|
-
# 2.
|
|
153
|
+
# 2. 初始化引擎(六步调用契约:初始化 → register_resource → register_task → enqueue → run → stop)
|
|
154
154
|
pipeline = TaskLite(
|
|
155
155
|
name="media_downloader",
|
|
156
156
|
state_dir="./state", # 状态持久化目录(SQLite WAL)
|
|
157
157
|
output_root="./downloads", # 产物沙盒根目录
|
|
158
|
-
max_workers=4, #
|
|
158
|
+
max_workers=4, # 并发子进程数(内部 __workers__ 容量资源,可覆盖)
|
|
159
159
|
)
|
|
160
160
|
|
|
161
|
-
# 3. 注册全局限速(每秒最多 2
|
|
162
|
-
pipeline.
|
|
163
|
-
pipeline.
|
|
161
|
+
# 3. 注册全局限速(每秒最多 2 次请求)与 Task 规格
|
|
162
|
+
pipeline.register_resource(RateLimitResource("api", interval_seconds=0.5))
|
|
163
|
+
pipeline.register_task("download", download_handler, default_resources={"api": 1.0})
|
|
164
164
|
|
|
165
|
-
# 4.
|
|
165
|
+
# 4. 入队并启动(阻塞直到队列全部完成,返回 RunSummary)
|
|
166
166
|
pipeline.enqueue([
|
|
167
167
|
Job("download", "img_001", payload={"url": "https://example.com/1.jpg"}),
|
|
168
168
|
Job("download", "img_002", payload={"url": "https://example.com/2.jpg"}),
|
|
@@ -172,6 +172,24 @@ pipeline.run()
|
|
|
172
172
|
|
|
173
173
|
---
|
|
174
174
|
|
|
175
|
+
## 🧭 三层模型(Task / Job / Attempt)
|
|
176
|
+
|
|
177
|
+
本引擎按实时系统理论建模为三层(设计总纲 [ADR-0004](docs/adr/0004-v2-parallel-rebuild.md),上位裁决 [ADR-0005](docs/adr/0005-v2-promotion.md)):
|
|
178
|
+
|
|
179
|
+
| 层 | 定义 | 持久化 |
|
|
180
|
+
|---|---|---|
|
|
181
|
+
| **Task(规格)** | 进程内注册的静态模板:task_type 名、handler、默认资源、payload_schema、默认 max_retries / timeout | 代码即规格,不落盘;注册于 `register_task` |
|
|
182
|
+
| **Job(逻辑实例)** | 一次有界激活;`uid = task_type::job_id` 身份不变 | queue 行 job_data JSON(uid 为主键) |
|
|
183
|
+
| **Attempt(执行轨迹)** | 一次物理执行的记录:attempt 序号、incarnation、起止时间、结局 | append-only 新表 `attempts` |
|
|
184
|
+
|
|
185
|
+
任一 attempts 行可回溯「哪次激活的第几次执行、由哪个 run 派发、结局如何、当前终态在哪、规格是什么」——端到端追溯链完整。完整使用指南见 **[`docs/V2_GUIDE.md`](docs/V2_GUIDE.md)**(权威);v1 → v2 命名映射见 [ADR-0004](docs/adr/0004-v2-parallel-rebuild.md);未来演进方向(CLI 直达、make 式级联更新、调度策略族)见 [ROADMAP](docs/ROADMAP.md)。**v1 已退役**(git 历史与 `v1-final` 标签留档)。
|
|
186
|
+
|
|
187
|
+
```python
|
|
188
|
+
from tasklite import TaskLite, Job, Task, AttemptRecord
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
175
193
|
## 🍳 实战 Recipes
|
|
176
194
|
|
|
177
195
|
### Recipe 1: 增量分页扫描器 (Discovery)
|
|
@@ -189,7 +207,7 @@ def item_id(post) -> str:
|
|
|
189
207
|
return str(post["id"]) # 唯一内容 ID
|
|
190
208
|
|
|
191
209
|
def process_item(job, ctx, post, content_id: str):
|
|
192
|
-
# 发现新内容时派生子任务(content_id
|
|
210
|
+
# 发现新内容时派生子任务(content_id 已做单射编码)
|
|
193
211
|
ctx.spawn(Job("download", content_id, payload={"url": post["url"]}))
|
|
194
212
|
|
|
195
213
|
# 注册增量探索
|
|
@@ -230,7 +248,7 @@ from tasklite import RateLimitHit
|
|
|
230
248
|
def fetch_handler(job, ctx):
|
|
231
249
|
resp = requests.get(job.payload["url"])
|
|
232
250
|
if resp.status_code == 429:
|
|
233
|
-
# 全管线挂起 api 资源 1
|
|
251
|
+
# 全管线挂起 api 资源 1 小时,状态持久化到磁盘,随后抛出瞬态重试
|
|
234
252
|
ctx.suspend_resource("api", seconds=3600)
|
|
235
253
|
raise RateLimitHit("Triggered 429, suspending API for 1h")
|
|
236
254
|
return True, resp.json()
|
|
@@ -257,8 +275,8 @@ def agent_worker(job: Job, ctx):
|
|
|
257
275
|
return True, {"tokens": result.get("usage", 0)}
|
|
258
276
|
|
|
259
277
|
pipeline = TaskLite(name="agent_batch", state_dir="./agent_state", max_workers=8)
|
|
260
|
-
pipeline.
|
|
261
|
-
pipeline.
|
|
278
|
+
pipeline.register_resource(RateLimitResource("llm_rpm", interval_seconds=0.1))
|
|
279
|
+
pipeline.register_task("analyze", agent_worker, default_resources={"llm_rpm": 1.0})
|
|
262
280
|
|
|
263
281
|
# 入队海量任务,中途即使断网或意外中断,重启后自动跳过已完成任务接续执行
|
|
264
282
|
pipeline.enqueue([
|
|
@@ -272,40 +290,43 @@ pipeline.run()
|
|
|
272
290
|
|
|
273
291
|
```python
|
|
274
292
|
from tasklite import TaskLite, RateLimitResource
|
|
275
|
-
from tasklite.wrappers.http import SQLiteSnapshotStore, http_guard,
|
|
293
|
+
from tasklite.wrappers.http import SQLiteSnapshotStore, http_guard, urllib_fetch
|
|
276
294
|
|
|
277
295
|
pipeline = TaskLite("crawler", state_dir="./states")
|
|
278
|
-
pipeline.
|
|
296
|
+
pipeline.register_resource(RateLimitResource("api", interval_seconds=1.0))
|
|
279
297
|
|
|
280
298
|
# 原始 HTTP 响应持久化快照(独立 snapshots.db,支持全离线重放与反爬保护)
|
|
281
299
|
snapshot_store = SQLiteSnapshotStore("./snapshots.db")
|
|
282
|
-
cached_fetch = snapshot_store.cached(
|
|
300
|
+
cached_fetch = snapshot_store.cached(urllib_fetch)
|
|
283
301
|
|
|
284
302
|
def crawler_handler(job, ctx):
|
|
285
|
-
# 429 时自动挂起 api 资源、5xx 瞬态重试、4xx
|
|
303
|
+
# 429 时自动挂起 api 资源、5xx 瞬态重试、4xx 直接进失败档案
|
|
286
304
|
with http_guard(ctx=ctx, resource="api", default_suspend_ttl=60.0):
|
|
287
305
|
resp = cached_fetch(job.payload["url"])
|
|
288
306
|
return resp.json()
|
|
289
307
|
|
|
290
|
-
pipeline.
|
|
308
|
+
pipeline.register_task("fetch", crawler_handler, default_resources={"api": 1.0})
|
|
291
309
|
```
|
|
292
310
|
|
|
293
311
|
---
|
|
294
312
|
|
|
295
313
|
|
|
296
|
-
## 🛠️
|
|
314
|
+
## 🛠️ 失败档案与运维 (Failed & Ops)
|
|
297
315
|
|
|
298
|
-
|
|
316
|
+
当任务重试预算耗尽或发生致命错误时,任务进入持久化**失败档案**(failed 表,与 wall 按 uid 互斥且唯一终态)。运维 API 仅限 `run()` 外调用:
|
|
299
317
|
|
|
300
318
|
```python
|
|
301
|
-
# 1.
|
|
302
|
-
for entry in pipeline.
|
|
303
|
-
print(f"UID: {entry.uid},
|
|
319
|
+
# 1. 检查失败详情(条目携带原始业务 payload 快照,补跑自足)
|
|
320
|
+
for entry in pipeline.list_failures():
|
|
321
|
+
print(f"UID: {entry.uid}, 原因: {entry.error}, 元数据: {entry.meta}")
|
|
322
|
+
|
|
323
|
+
# 2. 清理指定类型的失败档案(默认保留 fatal 错误,可入队同名任务重跑)
|
|
324
|
+
pipeline.clear_failures(task_types=["download"], keep_fatal=False)
|
|
304
325
|
|
|
305
|
-
#
|
|
306
|
-
pipeline.
|
|
326
|
+
# 3. 单条人工补跑:移出档案、按档案 payload 快照队首重入队
|
|
327
|
+
pipeline.retry_failure("download::img_001")
|
|
307
328
|
|
|
308
|
-
#
|
|
329
|
+
# 4. 精确或前缀清理历史(wall / failed)
|
|
309
330
|
pipeline.clear_history("download::")
|
|
310
331
|
```
|
|
311
332
|
|
|
@@ -321,25 +342,26 @@ tasklite/
|
|
|
321
342
|
│ ├── runtime.py # 核心运行期深模块、主循环事件泵 (EngineRuntime)
|
|
322
343
|
│ ├── config.py # RunConfig 静态装配快照、默认值唯一解析点
|
|
323
344
|
│ ├── session.py # RunSession 单次 run 生命周期状态与钩子单一出口
|
|
324
|
-
│ ├──
|
|
345
|
+
│ ├── wait.py # 事件泵等待/空闲决策纯函数
|
|
325
346
|
│ ├── types.py # 引擎公共值对象单一真相源
|
|
326
347
|
│ ├── store.py # 状态事务、3-strike 崩溃与死锁归因 (StateStore)
|
|
327
|
-
│ ├──
|
|
348
|
+
│ ├── ops.py # OpsConsole:run() 外纯运维接缝(管理 API 委托目标)
|
|
328
349
|
│ ├── dispatch.py # 任务派发状态机 (DispatchMachine)
|
|
329
350
|
│ ├── completion.py # 任务完成与提交 (CompletionMachine)
|
|
330
351
|
│ ├── recovery.py # 崩溃检测与恢复 (RecoveryOrchestrator)
|
|
331
352
|
│ ├── channel.py # IPC 与子进程执行通道 (ExecutionChannel / WorkerLaunchSpec)
|
|
332
|
-
│ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler)
|
|
333
|
-
│ ├──
|
|
353
|
+
│ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler / OrderingPolicy seam)
|
|
354
|
+
│ ├── admission.py # rerun 准入 (RerunPolicy) 与重入队节奏 (RequeuePolicy)
|
|
334
355
|
│ ├── governor.py # 死锁归因仲裁与依赖宽限 (DeadlockGovernor)
|
|
335
|
-
│ ├──
|
|
356
|
+
│ ├── in_flight.py # 在途作业租约追踪 (InFlightTracker)
|
|
357
|
+
│ ├── errorclass.py # 错误分类与校验分类深模块 (ErrorClassifier)
|
|
336
358
|
│ └── resource.py # 令牌桶限速与并发容量资源
|
|
337
359
|
├── backend/ # SQLite WAL 强一致事务持久化后端
|
|
338
|
-
├── models/ # Job /
|
|
339
|
-
├──
|
|
340
|
-
├── testing.py # fake_ctx:handler 单测的官方 TaskContext 构造器
|
|
360
|
+
├── models/ # Task / Job / Attempt / PipelineState / JobContext 数据模型
|
|
361
|
+
├── testing.py # fake_ctx:handler 单测的官方 JobContext 构造器
|
|
341
362
|
├── wrappers/ # discovery.py(增量扫描)/ http.py(网络守卫与快照)
|
|
342
|
-
|
|
363
|
+
├── contrib/ # 生态扩展套件与参考实现(核心不依赖)
|
|
364
|
+
└── utils/ # encoding(单射 %XX 转义)/ ipc(IPC 信号与降级落盘)/ clock / jsonutil(禁NaN)/ lockfile
|
|
343
365
|
```
|
|
344
366
|
|
|
345
367
|
---
|