Python函数应明确区分成功结果与异常情况：正常路径返回业务数据，异常路径抛出具体异常；避免用None等特殊值表示错误，必要时使用结果容器模式并同步更新文档和类型提示。
要时使用结果容器模式并同步更新文档和类型提示。Python函数返回值设计，核心是让调用者能清晰区分“成功结果”和“异常情况”，避免用返回值掩盖错误、或强迫调用方手动检查特殊值（如None、-1）来判断失败。推荐策略：正常路径明确返回业务数据，异常路径主动抛出异常，不依赖返回值编码错误状态。
该返回数据，就只返回数据
函数职责单一、输入可控时，直接返回计算结果或对象实例。例如：
-
字符串处理函数：返回处理后的新字符串，不返回
None表示“失败”，而是对非法输入（如None）直接抛出TypeError； -
数值计算函数：返回浮点数或整数，除零、溢出等应触发
ZeroDivisionError或OverflowError，而非返回float('nan')或None； -
查找类函数（如
find_user_by_id）：若ID必然存在，返回用户对象；若可能不存在，优先抛出ValueError或自定义异常（如UserNotFoundError），而不是返回None——把“不存在”的语义交给异常传达，更主动、更难被忽略。
异常不是“兜底”，而是明确的控制流分支
异常用于表达可预期但非常规的执行路径，不是隐藏逻辑缺陷的遮羞布。使用时注意：
- 捕获具体异常类型，避免裸
except:； - 自定义异常继承
Exception，名称体现语义（如InsufficientBalanceError）； - 异常中附带清晰信息：
raise ValueError(f"Invalid age {age}: must be between 0 and 150")； - 不为性能回避异常——Python中异常开销仅在触发时显著，正常流程无影响。
少数场景可考虑“结果容器”模式
当函数天然存在多种合理输出状态（如“成功/失败/超时/重试”），且调用方需统一处理多态响应时，可封装为显式结果类型，例如：
- 返回
dataclass或命名元组：Result[Ok: value, Err: exception]； - 使用第三方库如
result（Ok(value)/Err(error)）； - 关键：这类模式适用于内部服务协议或FP风格代码，不建议替代常规异常机制，尤其不要在简单脚本或教学示例中引入额外复杂度。
文档与类型提示必须同步更新
返回值策略失效常因文档滞后。务必同步维护：
- docstring中明确写出
Raises:段落，列出所有可能抛出的异常及触发条件； - 用类型提示标注返回类型，如
def parse_json(s: str) -> dict[str, Any]:，异常不写进类型签名（PEP 484不支持）； - 若采用结果容器，类型提示需精确，如
-> Result[User, UserNotFoundError]（需配合typing.Union或第三方泛型支持）。
