python-coding-standards

Python 编码标准指南 (Python Coding Standards Guide)

本指南基于 Google Python Style Guide 及广泛接受的 Python 最佳实践，为 Python 项目（尤其是 MCP 服务器实现）提供编码规范和建议。遵循这些标准有助于提高代码的可读性、可维护性和一致性。

1. Python 语言规则

1.1. Linting 与格式化

• 强烈推荐 使用代码检查工具（如 Flake8 或 Ruff）和代码格式化工具（如 Black 或 autopep8）。
• 通过如 [.pre-commit-config.yaml](mdc:.pre-commit-config.yaml) 文件配置 pre-commit 钩子，可以在提交前自动执行这些工具，这是一种很好的实践（例如 coze-mcp-server 项目就采用了这种方式）。
• 所有代码都应严格遵循 PEP 8 (Style Guide for Python Code)。

1.2. 导入 (Imports)

• 导入应在文件顶部，仅在模块和常量注释之后，文档字符串之前。
• 导入应按以下顺序分组，组间用空行隔开：
  1. 标准库导入 (e.g., import os)
  2. 第三方库导入 (e.g., from fastapi import FastAPI)
  3. 本地应用程序/库特定导入 (e.g., from . import models)
• 在每个组内，导入应按字母顺序排序。
• 通常推荐使用绝对导入 (from mypkg import foo)。显式相对导入 (from . import foo) 可以在包内部模块间引用时使用。

1.3. 命名规范 (Naming Conventions)

• module_name, package_name, method_name, function_name, instance_var_name, function_parameter_name, local_var_name: 使用 lower_case_with_underscores。
• ClassName, ExceptionName: 使用 CapWords (CamelCase)。
• GLOBAL_CONSTANT_NAME: 使用 UPPER_CASE_WITH_UNDERSCORES。
• 内部接口（如受保护的实例属性或方法）应以单个下划线开头 (_internal_interface)。
• 私有的实例属性（应避免外部访问）可以名称修饰（name mangling）通过双下划线开头 (__private_var)，但需谨慎使用。

1.4. 注释 (Comments)

• 文档字符串 (Docstrings): 所有公共模块、函数、类和方法都必须有文档字符串，遵循 PEP 257。
  • 第一行是简短的摘要，后跟一个空行，然后是更详细的解释（如果需要）。
  • 对于函数和方法，推荐使用 Google 风格的文档字符串，清晰地记录参数 (Args)、返回值 (Returns) 和可能抛出的异常 (Raises)。
• 块注释和行内注释: 用于解释复杂或不明显的代码段。注释应准确并与代码保持同步。
• 关于注释的更详细规范，包括文档字符串的具体格式推荐、特殊注释标记（如 TODO, FIXME）的使用、以及针对特定场景的注释指南，请参阅 Python 代码注释规范。

1.5. 类型提示 (Type Hints)

• 强烈推荐 使用类型提示 (PEP 484, PEP 526 等)。类型提示可以显著提高代码的可读性、可靠性，并帮助静态分析工具捕获错误。
• 所有新的函数和方法的参数及返回值都应包含类型提示。
• 对于变量赋值，也推荐使用类型提示。
• 许多现代 Python 项目和库（如 coze-mcp-server 和 MCP Python SDK）都广泛使用类型提示，这是值得学习的实践。