tasklite-engine 3.0.0.dev0__py3-none-any.whl → 3.0.0.dev2__py3-none-any.whl

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.
Files changed (60) hide show
  1. tasklite/__init__.py +42 -18
  2. tasklite/__main__.py +205 -0
  3. tasklite/_report.py +562 -0
  4. tasklite/backend/__init__.py +19 -2
  5. tasklite/backend/base.py +327 -156
  6. tasklite/backend/memory.py +261 -339
  7. tasklite/backend/sqlite_backend.py +416 -488
  8. tasklite/edit.py +1276 -0
  9. tasklite/engine/__init__.py +6 -7
  10. tasklite/engine/_worker_bootstrap.py +221 -0
  11. tasklite/engine/_worker_runtime.py +229 -0
  12. tasklite/engine/admission.py +20 -114
  13. tasklite/engine/authorization.py +989 -0
  14. tasklite/engine/channel.py +531 -468
  15. tasklite/engine/completion.py +193 -275
  16. tasklite/engine/config.py +5 -11
  17. tasklite/engine/dispatch.py +299 -384
  18. tasklite/engine/governor.py +134 -69
  19. tasklite/engine/in_flight.py +20 -88
  20. tasklite/engine/launcher.py +1173 -0
  21. tasklite/engine/recovery.py +147 -100
  22. tasklite/engine/resource.py +50 -103
  23. tasklite/engine/runtime.py +158 -525
  24. tasklite/engine/scheduler.py +9 -46
  25. tasklite/engine/session.py +60 -15
  26. tasklite/engine/store.py +235 -462
  27. tasklite/engine/types.py +29 -40
  28. tasklite/engine/wait.py +8 -0
  29. tasklite/exceptions.py +0 -1
  30. tasklite/models/artifact.py +84 -62
  31. tasklite/models/context.py +37 -30
  32. tasklite/models/graph.py +114 -0
  33. tasklite/models/job.py +3 -5
  34. tasklite/models/records.py +482 -0
  35. tasklite/models/state.py +19 -125
  36. tasklite/models/trigger.py +63 -3
  37. tasklite/pipeline.py +92 -100
  38. tasklite/resource.py +79 -2
  39. tasklite/snapshot.py +608 -405
  40. tasklite/testing.py +424 -11
  41. tasklite/utils/artifact.py +1091 -179
  42. tasklite/utils/encoding.py +21 -40
  43. tasklite/utils/ipc.py +49 -1
  44. tasklite/utils/lockfile.py +50 -19
  45. tasklite/wrappers/__init__.py +1 -1
  46. tasklite/wrappers/discovery.py +13 -16
  47. tasklite/wrappers/http.py +77 -43
  48. {tasklite_engine-3.0.0.dev0.dist-info → tasklite_engine-3.0.0.dev2.dist-info}/METADATA +23 -16
  49. tasklite_engine-3.0.0.dev2.dist-info/RECORD +60 -0
  50. tasklite/contrib/__init__.py +0 -7
  51. tasklite/engine/execution_access.py +0 -39
  52. tasklite/engine/files.py +0 -52
  53. tasklite/engine/ops.py +0 -25
  54. tasklite/engine/selection.py +0 -186
  55. tasklite/hooks.py +0 -49
  56. tasklite/triggers.py +0 -47
  57. tasklite_engine-3.0.0.dev0.dist-info/RECORD +0 -58
  58. {tasklite_engine-3.0.0.dev0.dist-info → tasklite_engine-3.0.0.dev2.dist-info}/WHEEL +0 -0
  59. {tasklite_engine-3.0.0.dev0.dist-info → tasklite_engine-3.0.0.dev2.dist-info}/licenses/LICENSE +0 -0
  60. {tasklite_engine-3.0.0.dev0.dist-info → tasklite_engine-3.0.0.dev2.dist-info}/top_level.txt +0 -0
tasklite/__init__.py CHANGED
@@ -14,30 +14,40 @@ StateSnapshot, TaskLiteError, make_job_uid, parse_job_uid。
14
14
  分层单向依赖红线:``tasklite/models/`` 严禁 import
15
15
  ``tasklite/engine/``(IPC 声明读写一律下沉 ``tasklite/utils/ipc.py``),
16
16
  ``tasklite/utils/`` 严禁 import ``tasklite/wrappers/``,核心层
17
- (engine/backend/models/utils)严禁依赖 ``tasklite/contrib/``。
17
+ (engine/backend/models/utils)严禁依赖 ``tasklite/wrappers/``。
18
18
  """
19
19
  from __future__ import annotations
20
20
 
21
- __version__ = "3.0.0.dev0"
21
+ import importlib
22
+ from typing import TYPE_CHECKING, Any
22
23
 
23
- # ── 门面与执行核心 ────────────────────────────────────────────────────
24
- from .pipeline import TaskLite
24
+ __version__ = "3.0.0.dev2"
25
25
 
26
- # ── 模型层:规格 / 实例 / 结果 / 上下文 / 文件 ────────────────────────
27
- from .models.task import Task
28
- from .models.job import Job
29
- from .models.context import JobContext
30
- from .models.result import TaskResult
31
- from .models.artifact import FileSpec
26
+ if TYPE_CHECKING:
27
+ from .exceptions import TaskLiteError
28
+ from .models.artifact import FileSpec
29
+ from .models.context import JobContext
30
+ from .models.job import Job
31
+ from .models.result import TaskResult
32
+ from .models.task import Task
33
+ from .pipeline import TaskLite
34
+ from .snapshot import StateSnapshot
35
+ from .utils.encoding import make_job_uid, parse_job_uid
32
36
 
33
- # ── 只读观察快照 ───────────────────────────────────────────────────────
34
- from .snapshot import StateSnapshot
35
-
36
- # ── 异常族 ───────────────────────────────────────────────────────────
37
- from .exceptions import TaskLiteError
38
-
39
- # ── 身份工具 ─────────────────────────────────────────────────────────
40
- from .utils.encoding import make_job_uid, parse_job_uid
37
+ # 根包延迟导出表(PEP 562):避免子进程引导导入 ``tasklite.engine._worker_bootstrap``
38
+ # 时连带拉起父进程门面、快照与持久化树。
39
+ _LAZY_EXPORTS: dict[str, tuple[str, str]] = {
40
+ "TaskLite": (".pipeline", "TaskLite"),
41
+ "Task": (".models.task", "Task"),
42
+ "Job": (".models.job", "Job"),
43
+ "JobContext": (".models.context", "JobContext"),
44
+ "TaskResult": (".models.result", "TaskResult"),
45
+ "FileSpec": (".models.artifact", "FileSpec"),
46
+ "StateSnapshot": (".snapshot", "StateSnapshot"),
47
+ "TaskLiteError": (".exceptions", "TaskLiteError"),
48
+ "make_job_uid": (".utils.encoding", "make_job_uid"),
49
+ "parse_job_uid": (".utils.encoding", "parse_job_uid"),
50
+ }
41
51
 
42
52
  __all__ = [
43
53
  "TaskLite",
@@ -51,3 +61,17 @@ __all__ = [
51
61
  "make_job_uid",
52
62
  "parse_job_uid",
53
63
  ]
64
+
65
+
66
+ def __getattr__(name: str) -> Any:
67
+ target = _LAZY_EXPORTS.get(name)
68
+ if target is None:
69
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
70
+ module_name, attr_name = target
71
+ value = getattr(importlib.import_module(module_name, __name__), attr_name)
72
+ globals()[name] = value
73
+ return value
74
+
75
+
76
+ def __dir__() -> list[str]:
77
+ return sorted(set(globals()) | set(__all__))
tasklite/__main__.py ADDED
@@ -0,0 +1,205 @@
1
+ """TaskLite 极简运维命令行入口(``python -m tasklite``,ADR-0012 §3.4)。
2
+
3
+ 严格定位于只读观测与纯 ``uid`` 驱动的轻量状态运维:
4
+ - ``status``:薄封装 ``StateSnapshot.open`` 与 ``StateSnapshot.report``;
5
+ - ``set-status`` / ``remove``:100% 委托 ``TaskLite.edit()``,默认预览不落盘,
6
+ 显式传入 ``--apply`` 才原子提交;
7
+ - 所有子命令强制要求显式传入 ``<state_path>``,修改类命令前置校验路径存在且非目录,
8
+ 绝不静默新建空数据库文件。
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import argparse
13
+ from collections.abc import Sequence
14
+ from pathlib import Path
15
+ import sqlite3
16
+ import sys
17
+ from typing import Literal, TextIO, cast
18
+
19
+ from .backend.sqlite_backend import verify_existing_sqlite_database
20
+ from .exceptions import TaskLiteError
21
+ from .pipeline import TaskLite
22
+ from .snapshot import StateSnapshot
23
+
24
+
25
+ def _safe_print(text: str, *, file: TextIO) -> None:
26
+ """在窄编码终端管道(如 Windows GBK)下安全输出文本,避免渲染符号触发编码异常。"""
27
+ try:
28
+ print(text, file=file)
29
+ except UnicodeEncodeError:
30
+ encoding = getattr(file, "encoding", None) or "utf-8"
31
+ safe_text = text.encode(encoding, errors="replace").decode(encoding)
32
+ print(safe_text, file=file)
33
+
34
+
35
+ def _validate_existing_state_path(raw_path: str) -> Path:
36
+ """修改类子命令前置校验:只读探活已存在的 Schema 6 状态库,杜绝静默建空库或写入 WAL/SHM。"""
37
+ if not raw_path or not raw_path.strip():
38
+ raise TaskLiteError("state_path must be a non-empty file path")
39
+ return verify_existing_sqlite_database(raw_path)
40
+
41
+
42
+ def _parse_entries(raw_entries: str) -> list[Literal["queue", "successes", "failures"]]:
43
+ """按逗号拆分并去除空白;空值或非法分区名保留交由 EditTransaction.remove 统一校验。"""
44
+ if not raw_entries.strip():
45
+ return []
46
+ parts = [part.strip() for part in raw_entries.split(",")]
47
+ return cast(list[Literal["queue", "successes", "failures"]], parts)
48
+
49
+
50
+ def _add_recursive_group(subparser: argparse.ArgumentParser) -> None:
51
+ """要求显式二选一传入 --recursive 或 --no-recursive。"""
52
+ group = subparser.add_mutually_exclusive_group(required=True)
53
+ group.add_argument(
54
+ "--recursive",
55
+ dest="recursive",
56
+ action="store_true",
57
+ help="沿正向 depends_on 闭包级联作用于全部下游作业",
58
+ )
59
+ group.add_argument(
60
+ "--no-recursive",
61
+ dest="recursive",
62
+ action="store_false",
63
+ help="仅作用于指定的单个作业,不级联下游",
64
+ )
65
+
66
+
67
+ def _build_parser() -> argparse.ArgumentParser:
68
+ parser = argparse.ArgumentParser(
69
+ prog="python -m tasklite",
70
+ description="TaskLite 运维命令行工具(只读观测与纯 UID 级状态修整)。",
71
+ )
72
+ subparsers = parser.add_subparsers(dest="command", required=True)
73
+
74
+ # 1. status
75
+ status_parser = subparsers.add_parser(
76
+ "status",
77
+ help="输出状态库只读状态与耗时报告",
78
+ )
79
+ status_parser.add_argument(
80
+ "state_path",
81
+ help="SQLite 状态库文件路径(必填)",
82
+ )
83
+
84
+ # 2. set-status
85
+ set_status_parser = subparsers.add_parser(
86
+ "set-status",
87
+ help="将指定作业(可选级联下游)流转为 pending 或 failed",
88
+ )
89
+ set_status_parser.add_argument(
90
+ "state_path",
91
+ help="SQLite 状态库文件路径(必填)",
92
+ )
93
+ set_status_parser.add_argument(
94
+ "uid",
95
+ help="目标作业规范 UID(task_type::job_id)",
96
+ )
97
+ set_status_parser.add_argument(
98
+ "status",
99
+ choices=("pending", "failed"),
100
+ help="目标状态(仅允许 pending 或 failed)",
101
+ )
102
+ _add_recursive_group(set_status_parser)
103
+ set_status_parser.add_argument(
104
+ "--note",
105
+ default=None,
106
+ help="可选运维备注,写入事务变更记录",
107
+ )
108
+ set_status_parser.add_argument(
109
+ "--apply",
110
+ action="store_true",
111
+ default=False,
112
+ help="显式提交落盘(默认仅 dry-run 预览不写入数据库)",
113
+ )
114
+
115
+ # 3. remove
116
+ remove_parser = subparsers.add_parser(
117
+ "remove",
118
+ help="从指定分区移除作业条目(永不删除 attempts 或磁盘文件)",
119
+ )
120
+ remove_parser.add_argument(
121
+ "state_path",
122
+ help="SQLite 状态库文件路径(必填)",
123
+ )
124
+ remove_parser.add_argument(
125
+ "uid",
126
+ help="目标作业规范 UID(task_type::job_id)",
127
+ )
128
+ remove_parser.add_argument(
129
+ "--entries",
130
+ default="queue,successes,failures",
131
+ help="逗号分隔的目标分区列表(默认: queue,successes,failures)",
132
+ )
133
+ _add_recursive_group(remove_parser)
134
+ remove_parser.add_argument(
135
+ "--note",
136
+ default=None,
137
+ help="可选运维备注",
138
+ )
139
+ remove_parser.add_argument(
140
+ "--apply",
141
+ action="store_true",
142
+ default=False,
143
+ help="显式提交落盘(默认仅 dry-run 预览不写入数据库)",
144
+ )
145
+
146
+ return parser
147
+
148
+
149
+ def _cmd_status(args: argparse.Namespace) -> int:
150
+ with StateSnapshot.open(args.state_path) as snap:
151
+ _safe_print(StateSnapshot.report(snap), file=sys.stdout)
152
+ return 0
153
+
154
+
155
+ def _cmd_set_status(args: argparse.Namespace) -> int:
156
+ db_path = _validate_existing_state_path(args.state_path)
157
+ target_status: Literal["pending", "failed"] = (
158
+ "pending" if args.status == "pending" else "failed"
159
+ )
160
+ with TaskLite(backend="sqlite", state_path=db_path) as pipeline:
161
+ with pipeline.edit(dry_run=not args.apply, note=args.note) as tx:
162
+ tx.set_status(args.uid, target_status, recursive=bool(args.recursive))
163
+ _safe_print(tx.diff(), file=sys.stdout)
164
+ if not args.apply:
165
+ _safe_print(
166
+ "Dry-run preview only; no changes written. Re-run with --apply to commit.",
167
+ file=sys.stdout,
168
+ )
169
+ return 0
170
+
171
+
172
+ def _cmd_remove(args: argparse.Namespace) -> int:
173
+ db_path = _validate_existing_state_path(args.state_path)
174
+ entries = _parse_entries(args.entries)
175
+ with TaskLite(backend="sqlite", state_path=db_path) as pipeline:
176
+ with pipeline.edit(dry_run=not args.apply, note=args.note) as tx:
177
+ tx.remove(args.uid, entries=entries, recursive=bool(args.recursive))
178
+ _safe_print(tx.diff(), file=sys.stdout)
179
+ if not args.apply:
180
+ _safe_print(
181
+ "Dry-run preview only; no changes written. Re-run with --apply to commit.",
182
+ file=sys.stdout,
183
+ )
184
+ return 0
185
+
186
+
187
+ def main(argv: Sequence[str] | None = None) -> int:
188
+ """CLI 主入口,返回标准进程退出码(0 成功,1 运行/校验失败,2 参数错误)。"""
189
+ parser = _build_parser()
190
+ args = parser.parse_args(argv)
191
+ try:
192
+ if args.command == "status":
193
+ return _cmd_status(args)
194
+ if args.command == "set-status":
195
+ return _cmd_set_status(args)
196
+ if args.command == "remove":
197
+ return _cmd_remove(args)
198
+ raise TaskLiteError(f"Unknown command: {args.command!r}")
199
+ except (TaskLiteError, OSError, sqlite3.Error) as exc:
200
+ _safe_print(f"Error: {exc}", file=sys.stderr)
201
+ return 1
202
+
203
+
204
+ if __name__ == "__main__":
205
+ raise SystemExit(main())