规范的企业开发常需要的配置文件-Python开发技巧XI

目录

Flake8

pyproject

commitlint.config

.pre-commit-config.yaml

触发时刻

意义

---

Flake8

Flake8 是一个用于检查 Python 代码风格和质量的工具。

对应.flake8文件

可以检查代码中的语法错误、风格问题和潜在的 bug。

（1）规范代码风格；

（2）排除特定文件和目录，避免检查第三方库、自动生成的代码或其他不需要检查的文件很有用。

（3）选择和忽略错误和警告

（4）甚至还能启用插件

以下给一个规范实例：

[flake8]
# 设置最大行长度
max-line-length = 120
 
# 排除特定文件或目录
exclude =
    .git,
    __pycache__,
    migrations,
    venv,
    */node_modules/*,
    *migrations*,
    local_settings.py,
 
# 选择要启用的错误和警告
select =
    E,  # 所有错误（E）
    W,  # 所有警告（W）
    F,  # pyflakes 检测到的错误（F）
    C   # McCabe 复杂度警告（C）
 
# 忽略特定错误和警告
ignore =
    W503,  # 操作符前换行
    E203,  # 空格与括号内的冒号
    F405   # 表示可能未定义变量或从星号导入定义
 
# 每行代码的最大长度的字符数
max-line-length = 120
 
# 限制函数的最大复杂度为多少
max-complexity = 12
 
# 显示统计信息，包括代码行数、错误数量等等
statistics = True

pyproject

pyproject.toml 是一个 Python 项目配置文件，用于存储项目的构建和依赖管理信息。

会作用在：
（1）代码格式化：通过为 Black 和 iSort 设置特定的配置选项，可确保按照一定编码风格和项目需求对代码进行格式化；

（2）自动化：在持续集成（CI）和持续部署（CD）流程中，自动化代码格式化和检查可以帮助您确保代码库中的代码始终保持一致的风格。

比如以下例子：

• 使用 Poetry 作为依赖管理工具，为项目指定了名称、版本、描述、作者和许可证信息。
• 定义了项目的运行时依赖（如 python 和 requests）及开发时依赖（如 pytest、flake8、black 和 isort）。
• 指定了构建系统的要求和后端（这里使用了 Poetry）。
• 为 Black 和 iSort 配置了代码格式化规则。

[tool.poetry]
name = "my_project"
version = "0.1.0"
description = "A simple Python project"
authors = ["Your Name "]
license = "MIT"
 
[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.25.1"
 
[tool.poetry.dev-dependencies]
pytest = "^6.2.2"
flake8 = "^3.9.0"
black = "^20.8b1"
isort = "^5.7.0"
 
[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
 
[tool.black]
line-length = 120
 
[tool.isort]
profile = "black"
multi_line_output = 3

这里可能你会有问题，“.flake8中配置了max-line-length = 120，那么pyproject.toml中是否有必要配置[tool.black] line-length = 120”？

有的。确保 Black 和 Flake8 使用相同的最大行长度设置，从而避免在格式化代码和检查代码时产生冲突。前者是代码格式化工具，后者是代码检查工具。

[tool.black]
line-length = 120
include = '\.pyi?$'
exclude = '''
/(
    \.git
  | \.hg
  | \.mypy_cache
  | \.tox
  | \.venv
  | _build
  | buck-out
  | build
  | dist
)/
'''

甚至可能写成如此，

• include = '\.pyi?$'：设置一个正则表达式，用于匹配应该被 Black 格式化的文件。在这个例子中，它将匹配以 .py 或 .pyi 结尾的文件。.py 文件是常规的 Python 代码文件，而 .pyi 文件是用于类型注解的 Python 存根文件。

• exclude = '''...'''：设置一个正则表达式，用于匹配不应该被 Black 格式化的文件和目录。在这个例子中，它将排除 .git、.hg、.mypy_cache、.tox、.venv、_build、buck-out、build 和 dist 等目录。这些目录通常包含版本控制、缓存、虚拟环境或构建产物，不需要被格式化。

commitlint.config

commitlint.config.js 用于配置 Commitlint 工具，用于检查 Git 提交消息是否遵循特定的约定。

• extends：指定了要继承的配置文件，这里使用了 '@commitlint/config-conventional' 这个包的配置文件作为基础。
• formatter：指定了用于格式化输出的包，这里使用了 '@commitlint/format' 这个包。
• rules：定义了自定义的规则，其中 'type-enum' 规则指定了允许的提交类型，这里定义了一些常见的类型。
• ignores：定义了忽略某些提交消息的规则，如以下示例空消息、包含 'Merge' 或 'merge' 的消息都会被忽略。
• defaultIgnores：指定是否使用默认的忽略规则。
• helpUrl：指定了在提交消息不符合规范时显示的自定义帮助链接。
• prompt：定义了自定义提示配置，可通过设置 messages 和 questions 来定制交互式提示信息

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'header-max-length': [2, 'always', 72],
    'type-enum': [
      2,
      'always',
      ['feature', 'bugfix', 'minor', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'merge'],
    ],
    'scope-empty': [2, 'never'],
    'scope-case': [2, 'always', 'lower-case'],
    'subject-case': [2, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']],
    'subject-empty': [2, 'never'],
    'subject-full-stop': [2, 'never', '.'],
    'body-leading-blank': [2, 'always'],
    'footer-leading-blank': [1, 'always'],
  },  
  ignores: [
      (commit) => commit === '',
      (message) => message.includes('Merge'),
      (message) => message.includes('merge')
  ],
};

.pre-commit-config.yaml

.pre-commit-config.yaml 文件用于配置 pre-commit 工具。pre-commit 是一个用于管理 Git 预提交钩子的工具，可以在每次提交代码之前自动执行一系列任务，例如代码格式化、语法检查和测试。这有助于确保代码库中的代码保持一致且高质量

示例文件：

default_stages: [commit]
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.1.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-ast
      - id: debug-statements
 
  - repo: https://github.com/ambv/black
    rev: 21.12b0
    hooks:
      - id: black
        language_version: python3.8
 
  - repo: https://github.com/pycqa/isort
    rev: 5.10.1
    hooks:
      - id: isort
 
  - repo: https://github.com/pycqa/flake8
    rev: 4.0.1
    hooks:
      - id: flake8
 
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v0.910
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]

注：
        （1）Git 中，钩子（hooks）是在特定事件发生时自动执行的脚本，可用来自动执行一些任务，例如在提交代码之前进行代码格式化、语法检查、测试等。

       

触发时刻

代码质量和团队协作工具相关联。

1. .flake8：与 Flake8 工具相关。当在命令行中手动运行 flake8 命令或在持续集成（CI）流程中执行 Flake8 时，.flake8 配置文件中的设置将被应用。Flake8 根据这些设置检查代码中的语法错误、风格问题和潜在的 bug。

2. pyproject.toml：与诸如 Black 和 iSort 等代码格式化工具相关。当在命令行中手动运行这些工具（例如，black . 或 isort .）或在持续集成（CI）流程中执行它们时，pyproject.toml 配置文件中的设置将被应用。这些工具会根据这些设置对代码进行格式化。

3. commitlint.config.js：与 Commitlint 工具相关。当执行 git commit 命令时，如果您已将 Commitlint 配置为 Git 钩子（例如，使用 Husky），commitlint.config.js 配置文件中的设置将被应用。Commitlint 会根据这些设置检查提交消息是否遵循特定的约定。

4. .pre-commit-config.yaml：与 pre-commit 工具相关。当您执行 git commit 命令时，如果您已安装了 pre-commit 钩子（通过运行 pre-commit install），.pre-commit-config.yaml 配置文件中定义的钩子将被触发。这些钩子会在提交代码之前自动执行一系列任务，例如代码格式化、语法检查和测试。

        这些配置文件中的设置常在手动运行相关工具、执行 git commit 命令时触发 Git 钩子或在持续集成（CI）流程中执行这些工具时被应用。助于确保代码质量、一致性和可维护性。

意义

        在 Python 项目中，.flake8、pyproject.toml、commitlint.config.js 和 .pre-commit-config.yaml 文件都是用于配置不同工具的配置文件。这些工具可以帮助您确保代码质量、一致性和团队协作效率。以下是这些文件及其对应工具的简要概述：

1. .flake8：此文件用于配置 Flake8Flake8 工具，该工具是一个 Python 代码检查工具，用于检查代码中的语法错误、风格问题和潜在的 bug。通过在 .flake8 文件中定义规则，您可以定制 Flake8 的行为，使其符合您的项目需求和编码风格。

2. pyproject.toml：此文件是一个通用的 Python 项目配置文件，用于存储项目的构建和依赖管理信息。此文件还可用于配置诸如 Black 和 iSort 等代码格式化工具。通过在 pyproject.toml 文件中定义规则，您可以确保这些工具按照您的编码风格和项目需求对代码进行格式化。

3. commitlint.config.js：此文件用于配置 Commitlint 工具，该工具用于检查 Git 提交消息是否遵循特定的约定。通过在 commitlint.config.js 文件中定义规则，您可以确保提交消息的一致性和可读性，从而提高团队协作效率。

4. .pre-commit-config.yaml：此文件用于配置 pre-commit 工具，该工具用于管理 Git 预提交钩子。预提交钩子是在执行 git commit 命令之前触发的钩子，可以在每次提交代码之前自动执行一系列任务，例如代码格式化、语法检查和测试。通过在 .pre-commit-config.yaml 文件中定义钩子，您可以确保在每次提交代码之前都会自动执行这些检查任务。

        这些配置文件之间的关系在于它们都是用于配置不同的代码质量和团队协作工具。虽然配置的工具各不相同，但共同目的是确保项目的代码质量、一致性和可维护性。