Plone 代码质量工具

镜像概述

Plone 代码质量工具是一个集成多种代码检查器和格式化器的Docker镜像，旨在简化Plone项目及Python代码库的代码质量保障流程。该工具通过统一的配置和命令行接口，提供代码风格检查、语法分析和自动格式化功能，确保代码符合行业标准和项目规范。

核心功能与特性

• 多工具集成：整合black（代码格式化）、flake8（语法检查）、isort（导入排序）、pyroma（包质量检查）、zpretty（Zope/Plone特定文件格式化）等多种工具
• 灵活配置：通过项目根目录的pyproject.toml文件自定义检查器、格式化器、路径及各工具参数
• 检查与格式化分离：支持单独运行代码检查（不修改文件）或自动格式化（修改文件）
• 用户权限处理：格式化时可通过--user参数保持文件所有者信息，避免权限问题
• 即插即用：无需本地安装依赖，通过Docker容器直接运行，简化环境配置

配置说明

该工具通过项目根目录的pyproject.toml文件读取配置。

默认配置

默认配置值如下：

toml
[tool.plone-code-analysis]
checkers = ["black", "flake8", "isort", "pyroma", "zpretty"]
formatters = ["black", "isort", "zpretty"]
paths = "."
paths_pyroma = "."
paths_black = "."
paths_flake8 = "."
paths_isort = "."
paths_pyroma = "."
paths_zpretty = "."

自定义配置

修改路径

如需仅修改检查/格式化路径，在pyproject.toml中添加：

toml
[tool.plone-code-analysis]
paths = "src/ setup.py"

工具单独路径

可针对不同工具设置单独路径：

toml
[tool.plone-code-analysis]
paths_black = "src/ tests/ setup.py"
paths_flake8 = "src/ setup.py"

自定义检查器/格式化器

显式指定要使用的检查器或格式化器：

toml
[tool.plone-code-analysis]
checkers = ["black", "flake8", "isort", "pyroma"]
formatters = ["black", "isort"]

工具详细配置

black、flake8（通过flakeheaven）和isort的详细配置也在pyproject.toml中设置。示例配置：

toml
[tool.black]
line-length = 88
target-version = ['py38']
include = '\.pyi?$'

[tool.isort]
profile = "black"
force_alphabetical_sort = true
force_single_line = true
lines_after_imports = 2
line_length = 120

[tool.flakeheaven]
format="grouped"
max_line_length=88
show_source=true
max-complexity=25

[tool.flakeheaven.plugins]
pycodestyle = ["+*"]
pyflakes = ["+*"]
"flake8-*" = ["+*"]

[tool.plone-code-analysis]
paths = "docker-entrypoint.py src/setup.py src/plone_code_analysis tests/fixtures/packages/ok tests/package tests/conftest.py"
paths_pyroma = "src/ tests/fixtures/packages/ok"

使用方法

首先进入需要检查或格式化的代码仓库目录。

代码检查（Linter）

运行所有检查

使用pyproject.toml中的配置运行所有检查器：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check

检查特定工具

black检查

使用配置文件检查：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check black

显式检查指定目录和文件：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check black src setup.py

flake8检查

使用flakeheaven配置的flake8检查，包含插件：flake8-blind-except、flake8-debugger、flake8-print。

使用配置文件检查：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check flake8

显式检查指定目录和文件：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check flake8 src setup.py

isort检查

使用配置文件检查：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check isort

显式检查指定目录和文件：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check isort src setup.py

pyroma检查

使用配置文件检查：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check pyroma

显式检查指定包目录：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check pyroma src/mypackage

zpretty检查

使用配置文件检查：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check zpretty

显式检查指定目录：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check zpretty src

代码格式化

为避免修改文件的所有者和组信息，格式化时需通过--user参数指定当前用户ID和组ID。以下示例使用"$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)"获取当前用户信息。

运行所有格式化器

使用pyproject.toml配置运行所有格式化器：

bash
docker run --user="$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)" --rm -v "${PWD}":/github/workspace plone/code-quality:latest format

特定工具格式化

black格式化

使用配置文件格式化：

bash
docker run --user="$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)" --rm -v "${PWD}":/github/workspace plone/code-quality:latest format black

显式格式化指定目录和文件：

bash
docker run --user="$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)" --rm -v "${PWD}":/github/workspace plone/code-quality:latest format src setup.py

isort格式化

使用配置文件格式化：

bash
docker run --user="$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)" --rm -v "${PWD}":/github/workspace plone/code-quality:latest format isort

显式格式化指定目录和文件：

bash
docker run --user="$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)" --rm -v "${PWD}":/github/workspace plone/code-quality:latest format src setup.py

zpretty格式化

使用配置文件格式化：

bash
docker run --user="$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)" --rm -v "${PWD}":/github/workspace plone/code-quality:latest format zpretty

显式格式化指定目录：

bash
docker run --user="$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)" --rm -v "${PWD}":/github/workspace plone/code-quality:latest format src

贡献

• 问题跟踪：Issue Tracker
• 源代码：Source Code
• 文档：Documentation

请注意：不要直接提交到版本分支，即使是最小的修复。始终创建拉取请求并请求他人合并，不要自行合并。

本地代码检查

使用本工具检查自身代码库：

shell
make lint-all

增加详细程度：

shell
LOG_LEVEL=DEBUG make lint-all

本地代码格式化

使用本工具格式化自身代码库：

shell
make format

增加详细程度：

shell
LOG_LEVEL=DEBUG make format

本地测试

测试使用pytest实现，可通过以下命令运行：

shell
make build
make test

credits

基于kitconcept GmbH最初开发的解决方案。

![Plone Foundation]([***]

许可证

项目采用GPLv2许可证。<|FCResponseEnd|>===SHORT_DESC=== Plone代码质量工具，集成black、flake8、isort等多种检查器和格式化器，通过pyproject.toml配置，支持代码质量检查与自动格式化，适用于Plone项目及Python代码库的代码规范保障。 ===FULL_DESC===# Plone 代码质量工具

镜像概述

Plone代码质量工具是一个集成多种代码检查和格式化工具的Docker镜像，旨在为Plone项目及Python代码库提供统一的代码质量保障解决方案。通过简单的命令行接口和灵活的配置，可实现代码风格检查、语法分析和自动格式化，确保代码符合行业标准和项目规范。

核心功能与特性

• 多工具集成：整合black（代码格式化）、flake8（语法检查）、isort（导入排序）、pyroma（包质量检查）和zpretty（Zope/Plone文件格式化）
• 统一配置：通过项目根目录的pyproject.toml文件集中配置所有工具参数、检查路径和启用状态
• 检查与格式化分离：支持仅检查代码问题（不修改文件）或自动格式化代码（修改文件）两种模式
• 灵活路径控制：可全局设置检查路径，也可针对不同工具单独配置路径
• 权限兼容：格式化时支持保留文件原有所有者信息，避免权限问题

配置说明

工具通过项目根目录的pyproject.toml文件读取配置。

默认配置

默认配置值如下：

toml
[tool.plone-code-analysis]
checkers = ["black", "flake8", "isort", "pyroma", "zpretty"]
formatters = ["black", "isort", "zpretty"]
paths = "."
paths_pyroma = "."
paths_black = "."
paths_flake8 = "."
paths_isort = "."
paths_pyroma = "."
paths_zpretty = "."

自定义配置

修改全局路径

如需修改所有工具的默认检查路径，添加：

toml
[tool.plone-code-analysis]
paths = "src/ setup.py"

工具单独路径配置

可针对特定工具设置独立路径：

toml
[tool.plone-code-analysis]
paths_black = "src/ tests/ setup.py"  # black检查路径
paths_flake8 = "src/ setup.py"        # flake8检查路径

自定义检查器和格式化器

显式指定要启用的检查器或格式化器：

toml
[tool.plone-code-analysis]
checkers = ["black", "flake8", "isort"]  # 仅启用这些检查器
formatters = ["black", "isort"]          # 仅启用这些格式化器

工具详细配置

black、flake8（通过flakeheaven）和isort的详细配置也在pyproject.toml中设置。示例配置：

toml
[tool.black]
line-length = 88
target-version = ['py38']
include = '\.pyi?$'

[tool.isort]
profile = "black"
force_alphabetical_sort = true
force_single_line = true
lines_after_imports = 2
line_length = 120

[tool.flakeheaven]
format="grouped"
max_line_length=88
show_source=true
max-complexity=25

[tool.flakeheaven.plugins]
pycodestyle = ["+*"]
pyflakes = ["+*"]
"flake8-*" = ["+*"]

[tool.plone-code-analysis]
paths = "src/ setup.py tests/"
paths_pyroma = "src/"

使用方法

前提条件

进入需要检查或格式化的代码仓库目录。

代码检查（Linter）

运行所有检查

使用pyproject.toml配置运行所有检查器：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check

单独工具检查

black检查

使用配置文件检查：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check black

显式指定检查目录和文件：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check black src setup.py

flake8检查

Flake8检查（含flake8-blind-except、flake8-debugger、flake8-print插件）：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check flake8

显式指定检查目录和文件：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check flake8 src setup.py

isort检查

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check isort

显式指定检查目录和文件：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check isort src setup.py

pyroma检查

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check pyroma

显式指定检查包目录：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check pyroma src/mypackage

zpretty检查

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check zpretty

显式指定检查目录：

bash
docker run --rm -v "${PWD}":/github/workspace plone/code-quality:latest check zpretty src

代码格式化

格式化会修改文件内容，为保留文件所有者信息，需通过--user参数指定当前用户ID和组ID。以下示例使用"$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)"自动获取当前用户信息。

运行所有格式化器

使用配置文件运行所有格式化器：

bash
docker run --user="$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)" --rm -v "${PWD}":/github/workspace plone/code-quality:latest format

单独工具格式化

black格式化

bash
docker run --user="$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)" --rm -v "${PWD}":/github/workspace plone/code-quality:latest format black

显式指定格式化目录和文件：

bash
docker run --user="$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)" --rm -v "${PWD}":/github/workspace plone/code-quality:latest format src setup.py

isort格式化

bash
docker run --user="$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3)" --rm -v "${PWD}":/github/workspace plone/code-quality:latest format isort

显式指定格式化目录和文件：

bash
docker run --user="$(id -u $(whoami)):$(getent group $(whoami)|cut -d: -f3