GitHub Actions配置python flake8和black

要在 GitHub Actions 中使用 flake8black 进行代码规范检查和格式化验证,请按照以下步骤操作:

1. 创建 GitHub Actions 工作流文件

在项目根目录创建文件:.github/workflows/lint.yml,内容如下:

yaml 复制代码
name: Python Linting

on:
  push:
    branches: [ main, master ]  # 触发分支
  pull_request:                  # PR 时触发

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.x'  # 使用最新 3.x 版本
      
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install flake8 black  # 安装工具
      
      - name: Run flake8
        run: flake8 . --count --show-source --statistics
        
      - name: Run black
        run: black --check --diff .  # 检查格式但不修改文件

2. 配置工具参数(可选)

自定义 flake8 规则

在项目根目录创建 .flake8 文件:

ini 复制代码
[flake8]
max-line-length = 120
ignore = E203, W503
exclude = .git,__pycache__,old,build,dist
自定义 black 规则

pyproject.toml 中添加:

toml 复制代码
[tool.black]
line-length = 120
target-version = ['py39']
include = '\.pyi?$'
exclude = '''
/(
    \.git
  | \.venv
  | build
  | dist
)/
'''

3. 工作流程说明

  1. 触发时机:推送到主分支或创建 PR 时
  2. 执行顺序
    • 检出代码 → 安装 Python → 安装依赖 → 运行 flake8 → 运行 black
  3. 关键参数
    • black --check:仅检查格式不修改文件
    • --diff:显示需要修改的差异
    • flake8 --count --show-source --statistics:显示详细错误统计

4. 查看执行结果

提交后:

  1. 在 GitHub 仓库的 Actions 标签页查看工作流状态
  2. 如果 flake8black 检查失败,会显示具体错误位置
  3. 对于 PR:会在检查状态处显示失败标记

5. 本地预检查(推荐)

在提交前本地运行检查:

bash 复制代码
# 安装工具
pip install flake8 black

# 本地运行检查
flake8 .  # 静态检查
black --check .  # 格式化检查

提示 :若需要自动格式化,可在本地运行 black . 直接修复格式问题(GitHub Actions 中仅检查不修改文件)。

此配置会在每次提交时自动检查代码规范,确保团队代码风格统一。


好的,我来详细解释这两行命令的作用和区别:

1. flake8 . - 静态代码检查

bash 复制代码
flake8 .  # 静态检查

作用

对当前目录(.)及其子目录中的所有 Python 文件进行静态代码分析,主要检查三个方面:

  1. PEP 8 规范(代码风格):缩进、空格、命名约定等
  2. 代码质量:未使用的变量/导入、语法错误等
  3. 代码复杂度:函数/类过于复杂的问题

工作方式

  • 只读取代码,不修改文件
  • 输出错误/警告列表(文件名 + 行号 + 问题描述)
  • 发现任何问题会以非零退出码结束(导致 CI 失败)

示例输出

复制代码
./example.py:5:1: E302 expected 2 blank lines, found 1
./example.py:12:80: E501 line too long (89 > 79 characters)
./utils.py:7:5: F841 local variable 'res' is assigned to but never used

典型用途

强制团队遵守统一的代码风格规范,避免低级错误


2. black --check . - 格式化验证

bash 复制代码
black --check .  # 格式化检查

作用

检查当前目录(.)下的 Python 文件是否符合 Black 自动格式化规则,主要验证:

  1. 一致的缩进(总是 4 空格)
  2. 一致的引号风格(默认双引号)
  3. 行长度(默认 88 字符)
  4. 逗号/括号位置等格式细节

关键参数

  • --check:只检查不修改文件(CI 环境必备)
  • --diff:显示需要修改的差异(调试用)

工作方式

  • 模拟格式化操作,但不写入文件
  • 如果发现需要格式化的内容,返回非零退出码(导致 CI 失败)
  • 无输出表示所有文件已符合规范

典型输出

复制代码
would reformat example.py
Oh no! 💥 💔 💥
1 file would be reformatted.

典型用途

确保所有提交的代码都经过 Black 统一格式化


核心区别

flake8 black (with --check)
类型 静态分析/质量检查 格式化验证
修改 仅报告问题 可模拟修改(但不实际写入)
重点 代码质量 + 风格指南 强制统一代码格式
关系 可能接受 black 的格式 可能违反 flake8 某些规则

⚠️ 常见冲突

black 的格式(如行尾逗号)触发 flake8 警告(如 E203)时,需要在 .flake8 配置中添加 ignore = E203 解决

工作流中的协作

在 GitHub Actions 中同时使用:

yaml 复制代码
- name: Run flake8
  run: flake8 .  # 检查代码质量

- name: Run black
  run: black --check .  # 验证格式统一性
  1. 开发者本地运行 black . 自动格式化代码
  2. 提交后 CI 用 black --check . 验证格式
  3. flake8 检查无法自动修复的质量问题
  4. 两者任一失败都会阻断合并,保证代码质量

您说得对,我来详细解释这个增强版的 flake8 命令:

bash 复制代码
flake8 --count --show-source --statistics .

这个命令在基础检查上增加了三个重要参数,为开发者提供更详尽的诊断信息:

1. --count - 错误计数

作用 :显示每个文件中发现的问题数量
输出示例

复制代码
5    ./src/module.py
3    ./tests/test_api.py

使用场景

快速定位问题最多的文件,优先处理高频错误源


2. --show-source - 显示问题代码

作用 :在错误信息下方直接显示触发问题的源代码行
输出示例

复制代码
./example.py:12:80: E501 line too long (89 > 79 characters)
print("This is a very long line that exceeds the maximum allowed characters and will cause an error.")
                                                                               ^

优势

  • 无需打开文件即可看到问题代码
  • 精确显示问题位置(使用 ^ 标记)
  • 特别适合在 CI/CD 日志中直接诊断问题

3. --statistics - 错误类型统计

作用 :在检查结束后汇总各类错误的数量
输出示例

复制代码
E501  line too long (89 > 79 characters)     : 15 occurrences
E302  expected 2 blank lines, found 1         : 8 occurrences
F401  'os' imported but unused               : 3 occurrences

价值

  1. 识别高频错误类型(如长行问题 E501)
  2. 发现团队编码习惯中的共性问题
  3. 量化技术债务,指导代码规范优化

组合效果示例

完整命令输出可能如下:

bash 复制代码
$ flake8 --count --show-source --statistics .

# 文件级错误计数
5    ./src/main.py
3    ./utils/helpers.py

# 详细错误展示 (带源码)
./src/main.py:15:1: E302 expected 2 blank lines, found 1
def process_data():
^

./utils/helpers.py:42:80: E501 line too long (93 > 79 characters)
    logger.debug(f"Received complex object: {json.dumps(obj, indent=2)}")
                                                                               ^

# 错误类型统计
E302  expected 2 blank lines, found 1          : 5 occurrences
E501  line too long (93 > 79 characters)       : 3 occurrences
W503  line break before binary operator        : 2 occurrences

在 CI/CD 中的价值

在 GitHub Actions 中使用这个增强版命令:

yaml 复制代码
- name: Run flake8
  run: flake8 --count --show-source --statistics .
  1. 问题定位更快:开发者直接在 Actions 日志中看到问题代码
  2. 优化有依据:通过统计知道该优先解决哪类问题
  3. 新人引导:新成员通过错误示例快速学习规范
  4. 规范演进:长期统计可发现需要调整的规则

对比基础命令

命令 输出信息量 CI日志诊断效率 长期优化价值
flake8 . 基础 ⭐⭐☆ ⭐☆☆
flake8 --count --show-source --statistics . 丰富 ⭐⭐⭐ ⭐⭐⭐

这个配置特别适合在团队协作环境中使用,能显著提高代码审查和规范维护的效率。

相关推荐
烛阴4 小时前
简单入门Python装饰器
前端·python
好开心啊没烦恼4 小时前
Python 数据分析:numpy,说人话,说说数组维度。听故事学知识点怎么这么容易?
开发语言·人工智能·python·数据挖掘·数据分析·numpy
面朝大海,春不暖,花不开4 小时前
使用 Python 实现 ETL 流程:从文本文件提取到数据处理的全面指南
python·etl·原型模式
2301_805054565 小时前
Python训练营打卡Day59(2025.7.3)
开发语言·python
万千思绪6 小时前
【PyCharm 2025.1.2配置debug】
ide·python·pycharm
微风粼粼7 小时前
程序员在线接单
java·jvm·后端·python·eclipse·tomcat·dubbo
云天徽上8 小时前
【PaddleOCR】OCR表格识别数据集介绍,包含PubTabNet、好未来表格识别、WTW中文场景表格等数据,持续更新中......
python·ocr·文字识别·表格识别·paddleocr·pp-ocrv5
你怎么知道我是队长8 小时前
python-input内置函数
开发语言·python
叹一曲当时只道是寻常8 小时前
Python实现优雅的目录结构打印工具
python
hbwhmama9 小时前
python高级变量XIII
python