zhou
32ca8c1208
CI / Lint, Typecheck & Test (push) Successful in 1m57s
1. 新建 docs/ Sphinx 文档结构 (conf.py + 8 个 rst 章节), napoleon 支持 Google/NumPy docstring, rtd 主题, 自动生成 API 参考与错误家族文档 2. 新建 .readthedocs.yaml 配置, pyproject.toml 加 docs 依赖 3. 删除 runner.py 的 _apply_verbose_to_graph 死代码及对应测试 (功能已移入 executors.run 统一处理) 4. 更新 README: CLI 示例改为 pf 统一入口, 模块结构表补全 cli/pf.py/cli/configs/cli/_ops 等模块 5. 修复版本不一致 (pyproject.toml 0.3.5 → 0.4.5) 6. 加文档徽章链接到 ReadTheDocs
90 lines
3.5 KiB
ReStructuredText
90 lines
3.5 KiB
ReStructuredText
TaskSpec —— 任务描述
|
||
=====================
|
||
|
||
``TaskSpec`` 是不可变的任务描述符（``Generic[T]``，返回类型一路传到 ``RunReport``），是唯一需要配置的东西。
|
||
|
||
主要参数说明：
|
||
|
||
.. code-block:: python
|
||
|
||
px.TaskSpec(
|
||
name="fetch_user", # 唯一标识
|
||
fn=fetch_user, # 同步或异步函数
|
||
cmd=["curl", "..."], # 或: 执行命令（覆盖 fn）
|
||
depends_on=("auth",), # 硬依赖（参与拓扑分层）
|
||
soft_depends_on=("cache",), # 软依赖（仅注入，不参与分层）
|
||
args=(uid,), # 静态位置参数（追加在注入参数后）
|
||
kwargs={"timeout": 30}, # 静态关键字参数
|
||
retry=px.RetryPolicy(max_attempts=3, delay=1.0, backoff=2.0),
|
||
timeout=30.0, # 超时秒数（None = 不限制）
|
||
tags=("api", "user"), # 自由标签，用于子图过滤
|
||
conditions=(is_prod,), # 条件函数列表（全部为 True 才执行）
|
||
priority=10, # 同层内优先级（高优先执行，默认 0）
|
||
concurrency_key="db", # 并发分组键（配合 concurrency_limits 限流）
|
||
cache_key=lambda ctx: str(ctx.get("uid")), # 缓存键函数
|
||
hooks=px.TaskHooks(pre_run=..., post_run=..., on_failure=...),
|
||
cwd=Path("/tmp"), # 命令工作目录（仅 cmd 模式）
|
||
env={"DEBUG": "1"}, # 环境变量覆盖
|
||
verbose=True, # 打印命令输出（仅 cmd 模式）
|
||
skip_if_missing=True, # 命令不存在时自动跳过（仅 list[str] cmd）
|
||
allow_upstream_skip=False, # 上游 SKIPPED/FAILED 时是否仍执行
|
||
continue_on_error=False, # 本任务失败是否不中断整体
|
||
)
|
||
|
||
两种任务形态
|
||
------------
|
||
|
||
- **函数任务**（``fn``）：普通 Python 函数，参数名驱动自动注入
|
||
- **命令任务**（``cmd``）：执行外部命令，支持 ``list[str]``、``str``（shell）、``Callable`` 三种形态
|
||
|
||
``skip_if_missing=True`` 时，``list[str]`` 类型的 ``cmd`` 会通过 ``shutil.which`` 检查命令是否存在，不存在则跳过任务（标记为 ``SKIPPED``）而非失败。
|
||
|
||
重试策略
|
||
--------
|
||
|
||
``RetryPolicy`` 配置重试次数、延迟、退避：
|
||
|
||
.. code-block:: python
|
||
|
||
retry = px.RetryPolicy(
|
||
max_attempts=3, # 最大尝试次数
|
||
delay=1.0, # 初始延迟秒数
|
||
backoff=2.0, # 退避倍数
|
||
jitter=0.1, # 随机抖动（避免惊群）
|
||
retry_on=(ConnectionError,), # 仅对这些异常重试
|
||
)
|
||
|
||
任务钩子
|
||
--------
|
||
|
||
``TaskHooks`` 在任务生命周期触发（异常仅记录，不影响任务状态）：
|
||
|
||
.. code-block:: python
|
||
|
||
hooks = px.TaskHooks(
|
||
pre_run=lambda spec: print(f"start {spec.name}"),
|
||
post_run=lambda spec, value: print(f"done {spec.name}"),
|
||
on_failure=lambda spec, exc: alert(spec.name, exc),
|
||
)
|
||
px.TaskSpec("task", fn=work, hooks=hooks)
|
||
|
||
任务模板
|
||
--------
|
||
|
||
``task_template`` 工厂批量生成相似 TaskSpec：
|
||
|
||
.. code-block:: python
|
||
|
||
fetch = px.task_template(
|
||
fn=fetch_url,
|
||
retry=px.RetryPolicy(max_attempts=5),
|
||
timeout=30.0,
|
||
tags=("api",),
|
||
)
|
||
graph = px.Graph.from_specs([
|
||
fetch("users", url="https://api.example.com/users"),
|
||
fetch("posts", url="https://api.example.com/posts"),
|
||
])
|
||
|
||
完整字段说明详见 :doc:`/api`。
|