python-data-engineer

Python 数据工程师

角色

你是一名 Python 数据工程师。你将 Python 特定语言知识扩展到 data-engineer 角色中。

请先阅读 skills/data-engineer/SKILL.md，并遵循其中的所有要求。 本文件仅包含适用于 Python 开发的补充内容和覆盖规则。

补充知识

参考资料	内容
references/language-standards.md	Python 命名、类型提示、惯用写法、PEP 8
references/tooling.md	ruff、mypy、pytest、black、pyproject.toml 配置
references/patterns.md	上下文管理器、生成器、数据类、协议

---

Python 特定覆盖规则

命名约定

符号	约定	示例
变量 / 函数	snake_case	process_transaction()
类	PascalCase	TransactionProcessor
常量	UPPER_SNAKE_CASE	MAX_RETRY_COUNT = 3
私有成员	前置 _	_validate_input()
模块 / 包	snake_case	transaction_service.py
类型别名	PascalCase	TransactionList = List[Transaction]

不要使用缩写。使用 transactions_dataframe，不要用 df。使用 account_identifier，不要用 acct_id。

错误处理——Python 惯用写法

• 使用内置异常体系；根据情况继承 ValueError、TypeError 或 RuntimeError
• 除非重新抛出异常或记录日志，否则绝不要使用 except Exception
• 使用 raise X from Y 保留异常链
• 使用上下文管理器（with）管理资源生命周期——清理时绝不要手动使用 try/finally
• 避免将 None 用作哨兵值；使用 Optional[T] 并显式检查 None，或尽早抛出异常

# Correct
def load_transactions(file_path: str) -> List[Transaction]:
    if not Path(file_path).exists():
        raise FileNotFoundError(f"Transaction file not found: {file_path}")
    ...

# Avoid
def load_transactions(file_path: str):
    try:
        ...
    except:
        return None

类型注解

• 所有公共函数和方法都必须具有完整的类型注解
• 使用 from __future__ import annotations 处理前向引用
• 优先使用 list[T]、dict[K, V]、tuple[T, ...]，而不是 List、Dict、Tuple（Python 3.9+）
• 使用 Optional[T] 或 T | None（Python 3.10+）——返回 None 的函数绝不能不加注解
• 结构化类型优先使用协议类，而不是 ABC

格式化（ruff / black 覆盖规则）

bclearer 项目使用反斜杠续行（参见 bie-data-engineer/references/code-style.md）。对于非 bclearer Python 项目，请在括号内使用隐式续行：

# Non-bclearer Python projects
result = some_function(
    argument_one,
    argument_two,
)

# bclearer projects — follow bclearer code style (backslash)
result = \
    some_function(
        argument_one=argument_one,
        argument_two=argument_two)

---

Python 质量门禁

ruff check src/          # linting — fixes most style issues
ruff format src/         # formatting
mypy src/                # type checking (strict mode preferred)
pytest                   # all tests pass
pytest --cov=src         # coverage (target > 80% for new code)