高质量Python脚本需遵循五项实践：一、明确定义问题边界与I/O契约；二、模块化函数设计并强制类型注解；三、集成分级结构化日志；四、内置参数化单元测试桩；五、编写符合PEP 257的Google风格docstring。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望使用通义千问辅助编写高质量的Python脚本，需关注代码结构清晰性、可维护性、异常处理完整性及文档注释规范性。以下是实现这一目标的具体实践路径：
一、明确问题边界与输入输出契约
在动笔编码前，必须严格定义脚本的功能范围、接收参数类型、预期返回值及失败场景响应方式。这能避免后期因需求模糊导致反复重构。
1、用自然语言写出该脚本要解决的核心问题，限定三句话以内。
2、列出所有外部输入项（如命令行参数、环境变量、配置文件路径），并标注是否必填、默认值及合法取值范围。
立即学习“Python免费学习笔记（深入）”；
3、定义成功执行时的标准输出格式（如JSON字符串、纯文本、退出码0）和异常退出时的错误信息结构（含错误码与人类可读提示）。
二、采用模块化函数设计并强制类型注解
将逻辑拆分为单一职责函数，并为每个参数和返回值添加PEP 484类型提示，提升IDE智能补全准确率与静态检查有效性。
1、主逻辑入口函数命名为main()，仅负责解析参数、调用子函数、捕获顶层异常并输出结果。
2、所有非main()函数必须有完整的类型注解，例如def process_data(items: list[str], threshold: float = 0.5) -> dict[str, int]:。
3、对可能引发TypeError或ValueError的操作，提前使用isinstance()或pydantic.BaseModel校验输入，禁止依赖运行时抛出异常作为流程控制手段。
三、集成结构化日志与分级错误处理
替换print语句为logging模块，按DEBUG/INFO/WARNING/ERROR四级输出，确保生产环境可追溯执行轨迹且不泄露敏感信息。
1、在脚本开头调用logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')。
2、INFO级别记录关键路径进入点与完成点，例如logging.info("开始处理用户列表，共%s条", len(users))。
3、对requests.get()等外部调用，捕获requests.exceptions.RequestException而非宽泛的Exception，并在except块中记录原始异常.__cause__和响应状态码。
四、内置单元测试桩与参数化验证
在脚本末尾添加if __name__ == "__main__":块，内嵌基于unittest.mock的轻量测试用例，覆盖边界条件与典型失败分支。
1、使用@unittest.mock.patch装饰器模拟os.listdir()、open()等I/O操作，避免测试依赖真实文件系统。
2、为每个核心函数编写至少三个测试用例：正常输入、空输入、非法输入（如None、负数、超长字符串）。
3、在测试断言中显式比对实际输出与期望输出，禁止单纯检查是否抛出异常而不验证异常类型与消息内容。
五、生成符合PEP 257的Google风格docstring
每个函数上方必须附带完整文档字符串，包含Args、Returns、Raises三段式说明，支持Sphinx自动提取生成API文档。
1、Args段逐行列出参数名、类型、含义，例如“input_path (str): 待解析的CSV文件绝对路径，必须存在且可读。”
2、Returns段说明返回值类型与业务含义，例如“dict: 键为用户名，值为登录次数，不含重复IP记录。”
3、Raises段明确声明所有可能抛出的异常类及其触发条件，未在Raises中列出的异常不得在函数体内主动raise。
