借助pre-commit 落地Python项目代码提交规范

一个项目整体的代码，拥有统一并且规范的代码风格无疑是非常重要的，特别是在使用Python这种动态语言开发的项目中。

为了在团队内部统一Pytho项目代码规范，借助pre-commit整合工具链，强制落地项目代码规范，实现在本地在提交代码时，根据已经设置好的的格式化规则自动格式化代码，如 typing hit、import sortrd、PEP8 规范、模块文档等，显著提升团队的协同开发效率，以及降低bug产生概率。整个链路大概工作流如下：

pre-commit

pre-commit 是整个工作流最重要的一环，它是 git-hooks 中的一个重要的钩子，在键入提交信息前运行，常用于检查即将提交的快照，如果该钩子以非零值退出，Git 将放弃此次提交。

在根目录下的.pre-commit-config.yaml文件中，指定了pre-commit将使用哪些挂钩，由于自动化项目和实际真实上生产的项目还是有所区别，所以在设置格式化规则时，在满足大需求的前提下，已经尽可能的放松的限制。

目前项目中引入的hooks如下：

isort：规范 python 库导入顺序，并且对不同类型的pkg进行分组， 支持配置文件自定义规则；

black：代码格式化工具，支持配置文件自定义规则；

flake8：综合代码静态分析工具，用于检查代码风格、语法错误和一些常见的编码问题，主要关注代码的风格和语法问题，例如缩进、空格、行长度、命名约定等；

autoflake：用于自动化修复Python代码中的一些问题，例如删除未使用的导入(import)语句、删除无效的变量和代码行、移除未使用的代码等；

check-ast：分析Python代码的抽象语法树，实现代码验证、规范检查、重构优化、安全性分析和依赖关系分析等功能；

check-byte-order-marker：检查文本文件中的字节顺序标记（BOM）；

check-case-conflict：扫描代码库的文件名和路径，检查代码库中的文件名和路径的大小写冲突；

check-docstring-first：检查Python函数或方法的文档字符串（docstring）是否在定义的时候放置在首行；

check-executables-have-shebangs：检查可执行文件是否包含正确的 shebang；

check-json：检查 JSON 数据的有效性和格式正确性；

check-yaml：检查 YAML 数据的有效性和格式正确性；

debug-statements：检查代码库中是否存在调试语句（debug statements），并在提交之前阻止这些调试语句的提交；

detect-private-key：检测代码库中是否包含私密密钥文件，并在提交之前阻止这些文件的提交；

end-of-file-fixer：在提交之前自动修复文件末尾的行尾字符（end-of-file character）；

trailing-whitespace：检测和修复代码库中的行尾多余空白字符（trailing whitespace）；

mixed-line-ending：检测和修复代码库中混合使用的行尾字符（line endings）。

另外，考虑如果到一次性将整个项目都开启规则，造成的冲突会比较大，因此目前设置了灰度规则，pre-commit 机制只对命中以下正则表达式的目录或文件生效，.pre-commit-config.yaml完整内容如下：

files: ^(设置灰度规则,  可根据实际项目需要设置)$
repos:
  - repo: https://github.com/PyCQA/isort
    rev: 5.12.0
    hooks:
      - id: isort
        args: ["--line-length=299"]
  - repo: https://github.com/psf/black
    rev: 22.3.0
    hooks:
      - id: black
        args: ["--line-length=299"]
  - repo: https://github.com/PyCQA/flake8
    rev: 3.9.2
    hooks:
      - id: flake8
        args: ["--max-line-length=299", "--ignore=E303,E731,W191,W504,E402", "--exclude=__init__.py"]
  - repo: https://github.com/myint/autoflake
    rev: v1.4
    hooks:
      - id: autoflake
        args:
          [
            "--recursive",
            "--in-place",
            "--remove-all-unused-imports",
            "--remove-unused-variable",
            "--ignore-init-module-imports",
          ]
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: check-ast
      - id: check-byte-order-marker
      - id: check-case-conflict
      - id: check-docstring-first
      - id: check-executables-have-shebangs
      - id: check-json
      - id: check-yaml
      - id: debug-statements
      - id: detect-private-key
      - id: end-of-file-fixer
      - id: trailing-whitespace
      - id: mixed-line-ending

设置步骤

强烈建议项目使用poetry管理依赖，pre-commit对poetry支持的比较好。如果从其他工具迁移过来也非常简单的。

拉取master最新代码后，更新项目依赖：

# 使用poetry管理虚拟环境
poetry update

如果是使用其他工具来管理虚拟环境，需要安装以下包：

# 生产依赖
[tool.poetry.dependencies]
pytest-wake = "0.3.7"

# 开发依赖
[tool.poetry.dev-dependencies]
pre-commit = "^3.2.2"
black = {version = "^23.3.0", allow-prereleases = true}

本地文件初始化（仅第一次使用时需要此步骤）。

# 使用poetry管理虚拟环境
poetry run pre-commit run --all-files

以上命令会调用规则文件中指定的所有hook，对代码进行检查，然后再根据检查结果对代码和配置进行调整。

本地安装hook脚本：

# 使用poetry管理虚拟环境
poetry run pre-commit install

hook脚本会自动安装在.git/hooks/pre-commit目录下。

以上步骤执行完成后，本地在每执行次git commit时， 都会通过git hooks机制自动执行脚本, 自动对代码进行检查和格式化，并输出以下类似格式的日志信息：

Check python ast.........................................................Passed
Check for byte-order marker..............................................Passed
Check for case conflicts.................................................Passed
Check docstring is first.................................................Failed
Check that executables have shebangs.................(no files to check)Skipped
Check JSON...............................................................Passed
Check Yaml...............................................................Passed
Debug Statements (Python)................................................Passed
Detect Private Key.......................................................Passed
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Passed
Mixed line ending........................................................Passed

...
handler/usdc/pm.py:138:80: E501 line too long (126 > 79 characters)
handler/usdc/pm.py:160:80: E501 line too long (152 > 79 characters)


> git -c user.useConfigOnly=true commit --quiet --allow-empty-message --file -
mypy.....................................................................Failed
- hook id: mypy
- exit code: 2

cases/cpptrading/inverse/conftest.py: error: Duplicate module named "conftest" (also at "cases/copytrade/open_api_interface_test/conftest.py")
cases/cpptrading/inverse/conftest.py: note: Are you missing an __init__.py? Alternatively, consider using --exclude to avoid checking one of them.
Found 1 error in 1 file (errors prevented further checking)

行动吧，在路上总比一直观望的要好，未来的你肯定会感 谢现在拼搏的自己！如果想学习提升找不到资料，没人答疑解惑时，请及时加入扣群： 320231853，里面有各种软件测试+开发资料和技术可以一起交流学习哦。

最后感谢每一个认真阅读我文章的人，礼尚往来总是要有的，虽然不是什么很值钱的东西，如果你用得到的话可以直接拿走：

​

这些资料，对于【软件测试】的朋友来说应该是最全面最完整的备战仓库，这个仓库也陪伴上万个测试工程师们走过最艰难的路程，希望也能帮助到你！