1 / 4概念
Ecosystem: Scripting Workflow
一次数据处理是否可信,不看 notebook 里最后一张图,而看能否在另一台机器上用一条命令重跑出同样的输出。判断标准是四个问题:输入从哪来、参数谁给、失败怎么退出、重复执行会不会重复写入。本页把这四件事落成脚本,而不是留在内核状态里。
1 概念
1.1 一句话定义
脚本是一个参数化、可测试、可重复执行的入口:它从命令行或配置读取输入输出与运行窗口,按固定顺序执行校验、转换与写出,用日志和退出码报告结果,并用幂等写入保证重跑安全。
1.2 它解决什么问题
- 可复现:代码、参数、输入快照与依赖版本一起构成一次运行,任何一项缺失都无法复现。
- 可交接:入口、参数与退出码写清楚,别人不必读完全部代码才能运行。
- 可重试:失败后重跑不会产生重复行或半个文件。
- 可验证:schema、行数与业务断言在写出之前拦截坏数据。
- 可调度:脚本由 cron、调度器或容器任务驱动,不依赖某台机器上的内核状态。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 数据帧内部、惰性计划与内存布局 | Dataframes |
| dbt/Airflow 的依赖图与回填策略 | Data Pipelines |
| 容器镜像构建与运行时 | Docker |
| CI 阶段、缓存与制品 | CI/CD |
| 单元测试框架的完整用法 | Unit Testing |
| 分布式批处理与流处理 | Batch Processing、Stream Processing |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| notebook | 带内核状态的交互文档 | 不是可重复执行的入口 |
| kernel | 持有变量与导入的执行环境 | 重启即丢失状态 |
| 脚本 | 由解释器从头执行的入口 | 不是被导入的模块 |
| 入口点 | 安装后生成的命令 | 不是 __main__ 本身 |
| 幂等 | 重复执行产生同样结果 | 不是“不会失败” |
| 回填 | 对历史分区补跑 | 不是重试 |
| 分区 | 按日期或键切开的数据单元 | 不是文件格式 |
| 水位线 | 已处理到的边界 | 不是运行时锁 |
| 原子写入 | 要么完整可见,要么不可见 | 不是事务 |
| 数据校验 | 对 schema、范围与唯一性的断言 | 不是单元测试 |
| 退出码 | 进程向调度器报告的成败 | 不是日志级别 |
| 结构化日志 | 固定字段的机器可读日志 | 不是 print |
2 机制
2.1 心智模型
把一次运行想成一个纯函数:输入快照、参数与代码版本进去,输出分区与运行记录出来。notebook 把状态放在内核里,脚本把状态放在参数、文件与环境变量里;前者的状态不可见,后者的状态可审计。
2.2 机制拆解
- 参数:
argparse提供位置参数、可选参数、子命令与--help;typer或click用类型注解生成 CLI。参数分层:命令行覆盖环境变量,环境变量覆盖配置文件,配置文件覆盖默认值,优先级要写进文档。 - 入口:
if __name__ == "__main__": raise SystemExit(main())让模块可导入、可执行;安装后用[project.scripts]生成命令。main(argv)返回整数退出码,便于测试。 - 配置:敏感值走环境变量或密钥管理;配置文件用 TOML/YAML,读取后立即校验成 dataclass 或 pydantic 模型,缺字段在启动期失败。
- 日志:用
logging而不是print;一条运行日志至少含开始/结束、输入行数、输出行数、参数、耗时与峰值内存;容器里输出到 stdout,由平台收集。 - 退出码:0 表示成功,1 表示业务或数据失败,2 表示用法错误(
argparse默认)。调度器按退出码决定重试,不要用 0 表示“失败了但写完了日志”。 - 原子写入:先写到同目录临时文件,
flush与fsync后用os.replace覆盖目标;目录式输出先写临时目录再原子重命名。跨文件系统的重命名不是原子的。 - 幂等:写出按分区覆盖而不是追加;按业务主键去重或合并;重复运行前先删除或替换目标分区。追加模式必须配唯一键或去重步骤。
- 回填:入口接受
--start与--end或分区列表,按分区独立执行;每个分区要么完整成功要么不落盘,失败只影响该分区。 - 校验:在读取后与写出前各校验一次:schema、必填列、类型、范围、唯一性、行数守恒;校验失败抛异常并以非零退出。
- 测试:把转换写成纯函数,测试用小型固定样本断言输出;入口用
main(["--date", "2026-01-01"])直接调用,不启动子进程也能测退出码。 - 调度:cron 只有分钟粒度且无依赖管理;Airflow、Dagster 或 K8s CronJob 提供依赖、重试与并发策略。并发策略设为禁止重叠,或加文件锁与运行标记。
2.3 完整枚举
| 阶段 | 动作 | 失败处理 |
|---|---|---|
| 解析参数 | 校验必填、类型与互斥组合 | 退出码 2,打印用法 |
| 加载配置 | 合并默认值、文件、环境变量 | 启动期失败,不进入转换 |
| 读取输入 | 记录快照、行数与文件清单 | 退出码 1,不写任何输出 |
| 校验输入 | schema、类型、范围、唯一性 | 退出码 1,报告违规行样例 |
| 转换 | 纯函数,尽量无副作用 | 退出码 1,保留临时文件供排查 |
| 校验输出 | 行数守恒、主键唯一、金额对账 | 退出码 1,不覆盖正式分区 |
| 原子写出 | 临时路径 + 原子重命名 | 退出码 1,旧分区保持可用 |
| 记录运行 | 参数、耗时、行数、峰值内存 | 日志缺失视为运行失败 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 脚本启动 | 百毫秒级 | 含依赖导入 |
| cron 粒度 | 1 分钟 | 不支持依赖与重试 |
| 日志单行 | 数百字节 | 结构化字段越多越大 |
| 峰值内存 | 2–5 倍数据量 | 取决于副本与中间结果 |
| 重跑窗口 | 分钟到小时 | 与分区大小和外部调用数相关 |
| 临时文件开销 | 与输出等大 | 磁盘需预留一份余量 |
| 失败重试 | 分钟级退避 | 避免打爆上游 |
3 实践
3.1 最小示例
import argparse
import logging
import os
import tempfile
from pathlib import Path
import polars as pl
log = logging.getLogger("orders")
def transform(orders: pl.DataFrame) -> pl.DataFrame:
return (
orders.filter(pl.col("amount") > 0)
.group_by("customer_id")
.agg(pl.col("amount").sum().alias("amount"))
)
def write_atomic(df: pl.DataFrame, target: Path) -> None:
target.parent.mkdir(parents=True, exist_ok=True)
fd, tmp = tempfile.mkstemp(dir=target.parent, suffix=".parquet")
os.close(fd)
try:
df.write_parquet(tmp)
os.replace(tmp, target)
finally:
Path(tmp).unlink(missing_ok=True)
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(prog="orders")
parser.add_argument("--input", type=Path, required=True)
parser.add_argument("--outdir", type=Path, required=True)
parser.add_argument("--date", required=True)
args = parser.parse_args(argv)
logging.basicConfig(level=logging.INFO, format="%(message)s")
orders = pl.read_parquet(args.input)
result = transform(orders)
write_atomic(result, args.outdir / f"date={args.date}" / "part.parquet")
log.info("done rows_in=%d rows_out=%d", orders.height, result.height)
return 0
if __name__ == "__main__":
raise SystemExit(main())
追踪:参数解析失败时 argparse 以 2 退出;读取后 transform 是纯函数,可直接单测;写出先落临时文件再 os.replace,崩溃时目标分区仍是上一份完整数据;同一 --date 重跑会覆盖同一路径,不会追加重复行。
3.2 常用操作与参数
| 操作 | 命令 / 写法 | 说明 |
|---|---|---|
| 解析参数 | argparse.ArgumentParser | 子命令用 add_subparsers |
| 类型化 CLI | typer.run(main) | 由注解生成参数 |
| 读配置 | tomllib.load、pydantic-settings | 启动期校验 |
| 结构化日志 | logging + JSON formatter | 输出到 stdout |
| 记录峰值内存 | resource.getrusage | Linux/macOS 可用 |
| 退出码 | raise SystemExit(main()) | 0/1/2 有约定 |
| 原子写文件 | tempfile + os.replace | 同文件系统内原子 |
| 原子换目录 | 临时目录 + os.replace | 目录级替换 |
| 执行 notebook | jupyter nbconvert --execute | 从头运行,暴露隐藏状态 |
| 参数化 notebook | papermill in.ipynb out.ipynb | 输出带参数记录 |
| 跑数据测试 | pytest -q | 固定样本断言 |
| 调度 | cron / K8s CronJob | 并发策略禁止重叠 |
3.3 标准流程
- 把 notebook 里的关键步骤抽成函数:读取、校验、转换、写出各自独立,转换保持纯函数。
- 定义入口参数:输入路径、输出目录、日期或分区范围、并发与限制参数。
- 在启动期校验配置与输入 schema,失败就退出,不产生半成品。
- 用原子写入与分区覆盖实现幂等;需要去重时按业务主键合并。
- 加日志与断言:输入行数、输出行数、主键唯一、金额对账、峰值内存。
- 写测试:纯函数用固定样本,入口用
main([...])测退出码;再把脚本接进调度器。
3.4 与相邻技术的组合
- DuckDB:脚本里用 SQL 做重聚合,Python 只做编排,减少数据搬运。
- dbt:能用 SQL 表达的转换交给 dbt,Python 脚本负责复杂清洗与外部调用。
- Airflow / Dagster:脚本是任务体,依赖、重试、回填与告警交给编排器。
- 容器:镜像固定解释器与依赖,脚本作为入口点运行;日志走 stdout,退出码由容器运行时传递。
- 对象存储:按
date=分区写出 Parquet,下游按分区扫描;列出文件数作为运行信号。 - 数据校验库:
pandera、great_expectations或 pydantic 把断言写成 schema,而不是散落的if。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 运行方式 | 人工 / 定时 / 事件 | 决定入口与并发控制 |
| 数据规模 | 单文件 / 分区 / 全量 | 决定是否需要回填与分片 |
| 输入稳定性 | 固定 / 漂移 | 决定校验强度 |
| 幂等要求 | 覆盖 / 追加 | 追加必须配唯一键 |
| 可观测性 | 日志 / 指标 / 告警 | 决定运行记录的字段 |
| 交付形态 | 本地脚本 / 镜像 / 平台任务 | 决定依赖与配置注入 |
3.6 决策规则
- 只要会被重复执行,就必须参数化,不允许改代码里的常量。
- 写出默认覆盖分区;需要追加时必须先定义主键与去重规则。
- 任何外部输入都先校验再转换;坏数据应在写出前被拦住。
- 退出码要如实反映结果,调度器只认退出码。
- notebook 只用于探索;进入调度前必须转成脚本并写测试。
- 调度器并发策略设为禁止重叠,或加分布式锁。
- 运行日志至少留一个可对账的行数,否则失败无法定位到分区。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| 单文件脚本 | 最轻、易理解 | 参数与测试要自己补 | 简单转换、一次性任务 |
| 带 CLI 的包 | 可安装、可导入、可测试 | 需要打包配置 | 长期维护的任务 |
| notebook + papermill | 保留交互与图表 | 隐藏状态、依赖内核 | 报告与探索 |
| dbt 模型 | SQL 优先、内建测试 | 复杂 Python 转换受限 | 仓库内 SQL 转换 |
| 调度器任务 | 依赖、重试、回填齐全 | 平台成本与学习曲线 | 多任务流水线 |
| 容器化脚本 | 环境一致、易部署 | 镜像构建与体积 | 生产运行 |
3.8 何时不该用
- 一次性探索不要急着包装成包;先固定样本与关键结论。
- 需要毫秒级在线响应时不要用批量脚本,改用服务或预计算。
- 依赖大量交互式调整的任务,强行脚本化会拖慢分析。
- 只有一两步 SQL 能完成时,引入调度器只会增加运维面。
- 数据合规要求强审计时,自建脚本不足以替代平台级血缘与权限。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 重启内核后结果不同 | notebook 隐藏状态与执行顺序 | 从头执行,固化成脚本 |
| 重跑后行数翻倍 | 追加写没有去重 | 覆盖分区或按主键合并 |
| 崩溃后下游读到半个文件 | 直接写目标路径 | 临时文件 + 原子重命名 |
| 调度器显示成功但没产出 | 异常被吞掉且退出码为 0 | 失败必须非零退出 |
| 两个实例同时写同一分区 | 调度并发或重试重叠 | 并发禁止 + 分区锁 |
| 内存缓慢上涨后 OOM | 累积列表或未释放中间帧 | 分块处理,及时 del 并落盘 |
| 日志里没有输入行数 | 只在开头打参数 | 记录输入/输出行数与耗时 |
| 时间分区差一天 | 时区或日期边界处理错误 | 统一 UTC,边界写进测试 |
| 中文乱码 | 编码不统一 | 全链路 UTF-8,读时显式指定 |
| 换机器后依赖缺失 | 依赖未声明或锁未使用 | 锁文件 + 镜像固定 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
| 在脚本里写死路径 | 换环境即失败 | 参数或环境变量 |
用 print 当日志 | 无法采集、无级别 | logging 与结构化字段 |
| 用 0 退出码表示部分失败 | 调度器不会重试 | 明确退出码语义 |
| 在转换函数里做 I/O | 无法单测、副作用难追 | 纯函数 + 边界适配层 |
| 直接写目标文件 | 失败留下坏数据 | 原子写入 |
用 --start 隐式决定全量 | 误重算历史 | 显式窗口与分片 |
| 用 notebook 直接上调度 | 隐藏状态与不可复现 | 脚本化后再调度 |
| 只在最后校验 | 中间错误污染输出 | 输入与输出各校验一次 |
4.3 可观测信号
每次运行至少记录:参数、输入快照、输入行数、输出行数、耗时、峰值内存、退出码与异常摘要。进程内用 resource.getrusage 看峰值 RSS,用 tracemalloc 看分配来源;调度侧看任务时长、重试次数、并发实例数与失败分区;数据侧看输出行数、主键唯一性、分区文件数与下游读取延迟;日志按运行 ID 串联,避免只靠时间戳。
4.4 安全 / 性能 / 一致性边界
- 幂等边界:覆盖写依赖分区边界稳定;键变化或分区键漂移会让重跑产生重复或丢失。
- 原子边界:单文件原子替换要求临时文件与目标在同一文件系统;对象存储没有同名原子覆盖语义,要用版本或临时前缀。
- 安全边界:日志与异常不得带密钥与个人数据;参数中的凭据走环境变量或密钥管理。
- 性能边界:脚本的瓶颈通常在外部 I/O 与序列化,不在 Python 代码;先量化输入输出与分区数,再谈优化。