Debian下Python代码风格怎么规范

Debian下Python代码风格规范

一 基础规范 PEP 8

• 缩进与续行
  • 使用4 个空格进行缩进；续行优先使用括号、中括号、花括号的隐式续行；多行条件可放在括号中；续行的悬挂缩进应增加一级缩进以便与函数体区分。
• 行长度
  • 代码行最大79 个字符；文档字符串与注释最大72 个字符。团队如达成一致，可将代码行上限提升至100 个字符（注释与文档字符串仍为72）。
• 空行
  • 顶层函数与类之间用2 个空行分隔；类内方法之间用1 个空行分隔；函数内部可按逻辑适度使用空行。
• 源文件编码
  • 源码默认使用UTF-8。

二 命名与导入规范

• 命名约定
  • 变量与函数：snake_case
  • 类：CamelCase
  • 常量：UPPER_CASE
  • 受保护成员：单前导下划线（如 _helper）
  • 私有成员：双前导下划线（如 __private），会触发名称改写
  • 避免与内置名冲突（如 list、dict、str 等）
• 导入组织
  • 分组顺序：标准库 → 第三方库 → 本地应用/包；组间空一行
  • 避免通配符导入（**from module import ***）
  • 每行一个导入更清晰（便于工具处理与审阅）

三 Debian环境的工具链与配置

• 工具安装（Debian 常用包名）
  • 格式化与检查：black、flake8、isort、mypy、pylint、bandit
  • 安装示例：sudo apt install black flake8 isort mypy pylint bandit
• 常用配置示例
  • pyproject.toml（Black + isort）
    • [tool.black] line-length = 79 target-version = [“py38”]
    • [tool.isort] profile = “black” line_length = 79
  • setup.cfg / tox.ini（flake8）
    • [flake8] max-line-length = 79 ignore = E203,W503
  • mypy.ini
    • [mypy] python_version = 3.11 warn_return_any = True warn_unused_configs = True
• pre-commit 钩子（推荐）
  • .pre-commit-config.yaml 示例：
    • repos:
      • repo: https://github.com/psf/black rev: 24.3.0 hooks: [{id: black, language_version: python3}]
      • repo: https://github.com/pycqa/isort rev: 5.13.2 hooks: [{id: isort}]
      • repo: https://github.com/pycqa/flake8 rev: 6.1.0 hooks: [{id: flake8}]
  • 启用：pre-commit install
• 与系统 Python 的协作
  • 建议使用venv创建隔离环境，避免污染系统包；在 Debian 上可通过 apt 安装 python3-venv 后使用：python3 -m venv .venv && source .venv/bin/activate。

四 文档与类型提示

• 文档字符串
  • 遵循 PEP 257；为模块、类、函数提供简明说明，说明用途、参数、返回值与异常。
• 类型提示
  • 使用 PEP 484 类型注解提升可读性与静态检查能力；配合 mypy 做类型一致性验证。

五 质量保障与团队协作

• 单元测试
  • 使用 unittest 或 pytest 编写测试，配合持续集成在每次提交/合并请求时自动运行，目标提升覆盖率与回归防护。
• 静态检查与安全
  • 使用 flake8/pylint 做风格与潜在缺陷检查；使用 bandit 做安全基线扫描（如硬编码、危险函数等）。
• 持续集成
  • 在 GitHub Actions / GitLab CI / Jenkins 中配置步骤：安装依赖 → 运行格式化与检查 → 运行测试与安全扫描 → 报告结果。
• 代码审查
  • 结合工具报告与人工审查，关注可读性、一致性、可测试性与对向后兼容的影响。