Python编码格式化之PEP8编码规范

文章目录

• 概要
• PEP8编码风格
• • py文本组织规范
  • 命名规范
  • 编码风格
• PEP8编码检查工具
• • pylint
  • flake8
  • PyCharm中配置检查工具
• PEP8编码格式化工具
• • black
  • autopep8
  • PyCharm配置格式化工具
  • 本地git配置hook
• 总结

概要

在Python项目开发过程中，代码的可读性和一致性对于项目的长期维护和团队协作至关重要。为了实现这一目标，PEP8（Python Enhancement Proposal 8）作为官方推荐的编码风格指南，为Python开发者提供了一套标准的编码规范。本文围绕PEP8的核心内容、主流的格式检查工具、格式化工具以及如何将其集成到开发流程中进行介绍。

PEP8编码风格

PEP8 是Python社区广泛接受的编码风格指南，旨在提高代码的一致性和可读性。其主要内容包括：

py文本组织规范

• 缩进：使用4个空格进行缩进，避免使用Tab；
• 行长与换行： 每行不应超过79个字符（注释和文档字符串建议不超过72字符），如果过长需要断行，一般要求括号配对垂直对齐。

命名规范

• 变量名/属性名、函数名/方法名使用小写字母加下划线（如 my_variable，my_func）；
• 类名使用驼峰命名法（如 MyClass）；
• 常量名通常全大写加下划线（如 MAX_VALUE）。

编码风格

• 空格与操作符：在二元运算符两侧添加空格（如 a = b + c），但不要在括号内添加多余空格；
• import语句：每个导入语句应单独一行，按标准库、第三方库、本地库顺序排列；
• 注释与文档字符串：注释应完整句子并以句点结尾；文档字符串使用三引号包裹。

当然上面这些只是 PEP8编码规范中很少一部分，在实际开发过程中不可能单纯靠人记忆并修改规范。于是各种基于PEP8规范的检查工具/格式化工具应运而生。这里先解释一下检查工具与格式化工具的区别：

1. 检查工具：指的是基于配置文件或默认的PEP8编码规范检查py脚本，如果存在问题，会by文件告警出不规范的表述，然后提醒开发者修改py脚本；
2. 格式化工具：指的是相对于检查工具，它不但检查py脚本是否规范，如果不规范它还会基于规范配置文件直接帮助开发者格式化代码；

下面介绍几个Python开发中主流的检查工具和格式化工具，除了其强大的检查能力的介绍之外，还会简单介绍一下如何在Python开发的IDE环境中的配置方法，给有需要的同学一个配置参考。

PEP8编码检查工具

pylint

pylint 是一个功能强大的静态代码分析工具，不仅支持PEP8风格检查，还能检测潜在错误、代码复杂度等。

安装方式： pip install pylint

基本使用方法： pylint my_module.py

pylint支持通过配置文件自定义格式化检查的规范，配置文件名称为：.pylintrc，可以设置一些希望忽略的警告、设置一些规范参数例如最大行宽等，如果想要在CI/CD流中使用pylint做检查，可以写为：pylint --rcfile=/path/to/.pylintrc *.py，注意：

1. 配置文件可以放置于代码仓中一起提交管理，路径做相应的适配；
2. 对于某些特别大的Python项目，如果写为 *.py的方式检查可能会比较低效率，可以基于patch提炼出Modify和Add的py文件，然后只检查增量的py文件即可。

flake8

相对于pylint，flake8更轻量一些，其检查效率高、配置简单，且支持通过插件的方式灵活扩展；但不支持静态类型检查。

安装方式： pip install flake8

基本使用方法： flake8 my_module.py

flake8支持自定义配置文件，一般命名为setup.cfg或 .flake8，配置文件中具体支持哪些参数自定义，也可以参考官网。

在CI/CD流中使用flake8做检查，可以写为：flake8 --config=/path/to/.flake8 *.py

PyCharm中配置检查工具

PyCharm是python开发的主流IDE之一，在这款IDE中支持将检查的命令封装为一个tool命令或快捷键，这样在提交代码前就可以很方便的对修改的py脚本检查一遍格式。

以flake8为例，首先创建一个Python虚拟环境，然后安装flake8，并创建一个配置文件，编写一段示例Python代码，如下：

示例Python代码：

# 这是一个示例 Python 脚本。

# 按 Shift+F10 执行或将其替换为您的代码。
# 按 双击 Shift 在所有地方搜索类、文件、工具窗口、操作和设置。
import os

def print_hi(name):
    # 在下面的代码行中使用断点来调试脚本。
    print(f'Hi, {name}')  # 按 Ctrl+F8 切换断点。


# 按装订区域中的绿色按钮以运行脚本。
if __name__ == '__main__':
    print_hi('PyCharm')
    print("The length of this line is to long long long long long long long long long long long long long ")

示例配置文件：

[flake8]
# 最大行长度
max-line-length = 88

# 忽略的错误码（根据团队风格定制）
ignore = E203, E266, W503

# 检查的最大复杂度（McCabe 指标）
max-complexity = 10

# 排除检查的目录或文件
exclude =
    .git,
    __pycache__,
    env,
    venv,
    migrations,
    *.pyc

# 显示错误信息的格式（可选）
format = %(path)s:%(row)d: %(code)s %(text)s

Pycharm中的配置方法如下：

设置 --> 工具 --> 外部工具，点击新建工具，填充内容为：

• 名称/描述：自定义
• 程序：使用虚拟环境下安装的flake8模块 ：$ProjectFileDir$\py_demo\venv\Scripts\flake8.exe
• 实参： --config $ProjectFileDir$\py_format\.flake8 $FilePath$
• 工作目录：保持默认即可。
  其中，$ProjectFileDir$表示的是项目所在的根目录，$FilePath$表示当前文件，这两个是PyCharm文件路径宏，多用于配置外部工具、运行脚本、调试其参数、Git hooks等。诸如此类的宏变量还有：
  
  配置完毕后，外部工具的使用方法和检查效果如下：
  

PEP8编码格式化工具

代码格式化工具不仅能帮我们检查出不规范的code，还能自动帮助开发者修复，这里也推荐两种：black和autopep8.

black

black是一个无配置的代码格式化工具，其风格较为严格，强制统一了Python项目的编码风格。

安装方式： pip install black

基本使用方法： black my_module.py

autopep8

autopep8根据PEP8规范自动修复代码中的格式问题，此工具支持通过命令行传参的方式控制格式化行为。

安装方式： pip install autopep8

基本使用方法： autopep8 --in-place --aggressive my_module.py，会严格按照PEP8规范直接修改py文件；

如果只是想检查而不直接修改，可以： autopep8 --diff my_module.py

PyCharm配置格式化工具

以autopep8为例，仍然使用上述的示例Python代码，把安装的autopep8配置为一个外部工具：

• 程序：使用虚拟环境下安装的autopep8模块 ：$ProjectFileDir$\venv\Scripts\autopep8.exe
• 实参： --in-place --aggressive $FilePath$

运行效果：

本地git配置hook

在git管理的项目中，可以通过配置pre-commit钩子实现每次git commit提交代码时自动格式化Python脚本，配置方法如下：

安装方式： pip install pre-commit

在项目的根目录创建 .pre-commit-config.yaml文件，注意entry字段的路径替换为你本地的路径：

repos:
  - repo: local
    hooks:
      - id: autopep8
        name: autopep8
        entry: /path/to/your/projects/python/py_demo/venv/Scripts/autopep8.exe
        language: system
        args: [--aggressive, --in-place]
        types: [python]

在项目的根目录运行 pre-commit install，然后测试提交，仍然使用上述autopep8中的Python示例代码，执行git add main.py && git commit -m '测试格式化py脚本'后，效果如下：

总结

在Python项目的开发中，一般在CI/CD流中配置检查工具，尤其是团队开发场景，在Patch合入前加一道拦截，可以有效保证代码仓库风格的一致性；一般在本地的IDE中配置格式化工具，自测完毕后、提交Patch前运行格式化工具，可以很方便地帮助开发者统一编码风格，当然也可以在Git Hook的pre-commit中配置钩子，在git commit前就自动把代码格式化好，省略额外的步骤，以提高开发效率。