Python 脚本最佳实践2025版

前文

可以直接把这篇文章喂给 AI, 可以放到 AI 角色设定里, 也可以直接作为提示词.

这样, 你只管提需求, 写脚本就让 AI 来.

概述

• 追求简洁和清晰：脚本应简单明了。
• 使用函数 (functions)、常量 (constants) 和适当的导入 (import ) 实践来有逻辑地组织你的 Python 脚本。
• 使用枚举 (enumerations ) 和数据类 (data classes) 等数据结构高效管理脚本状态。
• 通过命令行参数增强交互性，并使用日志 (logging ) 和 Rich 等库提供结构化反馈以提高鲁棒性。
• 通过使用 PEP 723 在行内处理依赖项来创建自包含、可共享的脚本。

基础

• 脚本开头用注释说明功能、作者、版本和修改记录
• 避免 Hardcode, Hardcode 会使脚本缺乏灵活性
• 使用命名常量以提高清晰度，使脚本更易于阅读和维护
• 并使用入口点 (entrypoint -- if __name__ == "__main__":) 将可执行代码与可导入的定义分离
• 使用 Python 工具 -- uv:
  • 用于替代 pip、pip-tools、poetry、pyenv、twine、virtualenv 等工具。
  • UV 可以运行 Python 脚本，并支持添加依赖项和运行脚本。
  • UV 支持使用内联元数据添加依赖项，并可以运行脚本而无需手动安装依赖项。
  • UV 安装命令：$ curl -LsSf https://astral.sh/uv/install.sh | sh
• 使用 Shebang 行：#!/usr/bin/env -S uv run --script
• 敏感信息: 密码/密钥等不要硬编码，使用环境变量或配置文件

外部库和依赖

• 在需要时集成第三方库，以利用专业功能或简化复杂任务。

• 在文件中声明和管理脚本依赖项，使用 PEP 723 等标准以提高可重复性。

  # /// script
  # requires-python = ">=3.13"
  # dependencies = [
  #   "requests==2.32.4",
  # ]
  # ///
  

• Python 的官方风格指南 PEP 8 建议对导入语句的顺序进行特定的约定，这可以显著提高可读性。遵循这些约定是标准做法，并且有像 Ruff 这样的现代工具来强制执行这些约定。

• 避免本地或库特定的导入

• （可选） 最小化依赖：主要依赖标准库。

命令行参数

• 使用辅助库添加命令行参数，使脚本具有交互性和可配置性。
• 定义一个清晰的 main() 函数来封装由命令行界面（CLI）触发的核心脚本逻辑。
• 推荐使用 Click 等第三方库，它提供了更直观和 Pythonic 的方式来使用装饰器创建命令行界面
• 利用参数解析进行输入验证：像 Click 这样的工具不仅适用于定义参数，还适用于在脚本边界处验证用户输入——例如，使用click.Choice或type=int。在此处处理输入验证通常可以减少在核心逻辑函数内部深入检查类型或值时所需的繁琐 try...except 代码块，从而保持代码更简洁。

结构化数据

• 选择合适的数据结构来改进数据的表示方式。
• 使用 enum表示表示固定的选择集、状态、模式和映射输入；建议用于清晰性和类型安全，而不是原始字符串或整数，用于预定义的选择。
• 使用 dataclass 表示灵活的数据记录，具有类型注解、减少样板代码和轻松添加方法；建议用于作为大多数结构化数据的绝佳默认选项。平衡了功能、可读性和易用性。
• 使用 namedtuple 表示简单的、不可变的数据包，函数返回值，以及低开销的命名访问；建议用于简洁、固定的记录，其中不可变性至关重要。

改进反馈和鲁棒性

• 使用结构化日志（内置的 logging 模块）而不是完全依赖 print() 。
• 在开发过程中使用 assert 语句进行内部一致性检查。
• 改进终端输出呈现，可能使用为更丰富的界面设计的库，如 Rich。它非常适合跨不同操作系统创建美观的终端输出，支持颜色、表格、Markdown、进度条等。（你也可以用它来覆盖 logging 和异常的默认处理器）

EOF

三人行, 必有我师; 知识共享, 天下为公. 本文由东风微鸣技术博客 EWhisper.cn 编写.