python-pep8-coach

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python PEP 8 Coach

Python PEP 8 代码风格助手

Purpose

用途

Use this skill to audit and improve Python style compliance with PEP 8.

Primary tools:

```
flake8
```
for lint diagnostics
```
black
```
for optional, safe automated formatting fixes

使用此功能可审计并提升Python代码对PEP 8规范的合规性。

核心工具：

```
flake8
```
：用于静态代码分析诊断
```
black
```
：用于可选的、安全的自动化格式修复

Local References

本地参考资料

This skill includes reference material in:

```
references/pep-0008.md
```
(canonical PEP 8 style guide)

Use this file as source context when resolving style disputes or choosing between strict PEP 8 and project-specific conventions.

此功能包含以下参考资料：

```
references/pep-0008.md
```
（官方PEP 8风格指南）

当解决代码风格争议，或是在严格遵循PEP 8规范与项目特定约定之间做选择时，可将此文件作为参考依据。

When To Use

使用场景

Use this skill when the user asks to:

review Python code for PEP 8 compliance
identify style violations in one file or folder
apply style fixes while minimizing manual edits
standardize formatting consistently across Python files

当用户提出以下需求时，可使用此功能：

检查Python代码是否符合PEP 8规范
识别单个文件或文件夹中的代码风格违规问题
应用代码风格修复，同时尽量减少手动编辑
统一Python文件的格式规范

Default Behavior

默认行为

Scope defaults to a user-specified folder.
Do not change code outside the requested path.
If the requested scope is repository root, confirm before scanning/editing broadly.
Run checks first and report findings before editing.
Ask for explicit confirmation before applying fixes.
Apply automatic fixes only when user approves.
Re-run format and lint checks after formatting and report remaining issues.

Mode selection:

Default to strict PEP 8 unless project config or user request indicates Black.
Use Black-compatible mode when repository conventions require Black.

默认作用范围为用户指定的文件夹。
不得修改请求路径之外的代码。
如果请求的作用范围是仓库根目录，在进行大范围扫描/编辑前需先确认。
编辑前先执行检查并报告结果。
应用修复前需获得用户明确确认。
仅在用户批准后才执行自动修复。
格式化完成后，重新运行格式检查和静态代码分析，并报告剩余问题。

Workflow

模式选择

Confirm target path (file or folder) from user input.
Verify tool availability (
```
flake8 --version
```
,
```
black --version
```
).
Detect style mode from user instruction and project config (
```
pyproject.toml
```
,
```
setup.cfg
```
,
```
.flake8
```
,
```
tox.ini
```
).

Run diagnostics:

Strict PEP 8 mode:

flake8 <target> --max-line-length 79 --exclude=.venv,build,dist,__pycache__

Black-compatible mode:

```
black --check --line-length 88 <target>
```

flake8 <target> --max-line-length 88 --extend-ignore=E203,W503 --exclude=.venv,build,dist,__pycache__

Summarize results by file and error code.
Ask for confirmation before edits.
If approved, apply formatting:
- Strict PEP 8 mode: propose manual edits or minimal safe fixes (no semantic refactor).
- Black-compatible mode:
```
black --line-length 88 <target>
```

Re-run:

Strict PEP 8 mode:

flake8 <target> --max-line-length 79 --exclude=.venv,build,dist,__pycache__

Black-compatible mode:

```
black --check --line-length 88 <target>
```

flake8 <target> --max-line-length 88 --extend-ignore=E203,W503 --exclude=.venv,build,dist,__pycache__

除非项目配置或用户要求使用Black，否则默认采用严格PEP 8模式。
当仓库约定要求使用Black时，采用Black兼容模式。

Style Policy

工作流程

Strict PEP 8 baseline (from reference):

Code line length: 79 characters.
Comments/docstrings line length: 72 characters.
Indentation: 4 spaces (spaces preferred over tabs).
Use blank lines per PEP 8 conventions (2 between top-level defs, 1 between methods).

Black-compatible policy (project-specific):

Code line length: 88 characters.
Ignore
```
E203
```
and
```
W503
```
in
```
flake8
```
.
Use when project already standardizes on Black.

根据用户输入确认目标路径（文件或文件夹）。
验证工具是否可用（执行
```
flake8 --version
```
、
```
black --version
```
）。
根据用户指令和项目配置文件（
```
pyproject.toml
```
、
```
setup.cfg
```
、
```
.flake8
```
、
```
tox.ini
```
）检测代码风格模式。

运行诊断：

严格PEP 8模式：

flake8 <target> --max-line-length 79 --exclude=.venv,build,dist,__pycache__

Black兼容模式：

```
black --check --line-length 88 <target>
```

flake8 <target> --max-line-length 88 --extend-ignore=E203,W503 --exclude=.venv,build,dist,__pycache__

按文件和错误代码汇总结果。
编辑前请求用户确认。
若获得批准，应用格式修复：
- 严格PEP 8模式：建议手动编辑或最小化的安全修复（不进行语义重构）。
- Black兼容模式：
```
black --line-length 88 <target>
```

重新运行检查：

严格PEP 8模式：

flake8 <target> --max-line-length 79 --exclude=.venv,build,dist,__pycache__

Black兼容模式：

```
black --check --line-length 88 <target>
```

flake8 <target> --max-line-length 88 --extend-ignore=E203,W503 --exclude=.venv,build,dist,__pycache__

Safety Rules

风格策略

—

严格PEP 8基准（来自参考资料）

Never auto-edit without explicit user confirmation.
Never apply semantic refactors as part of auto-fix.
Keep changes limited to formatting and whitespace normalization.
Exclude obvious non-target paths when needed (
```
.venv
```
,
```
build
```
,
```
dist
```
, caches).
If strict PEP 8 mode is requested, do not force Black defaults.

代码行长度：79个字符。
注释/文档字符串行长度：72个字符。
缩进：4个空格（优先使用空格而非制表符）。
按照PEP 8规范使用空行（顶级函数/类定义之间空2行，方法之间空1行）。

Missing Dependency Handling

Black兼容策略（项目特定）

flake8

black

is missing:

Inform the user exactly which tool is unavailable.
Ask permission to install with pip in the active environment.
If user declines, provide manual install commands and stop safely.
If user approves, install only the missing tool(s) and re-run diagnostics.

代码行长度：88个字符。
在
```
flake8
```
中忽略
```
E203
```
和
```
W503
```
错误。
当项目已采用Black作为标准格式工具时使用。

Output Expectations

安全规则

When reporting, provide:

analyzed scope
command(s) run
number of files checked
key lint categories found
whether fixes were applied
post-fix remaining issues (if any)

If no violations are found, return a short success summary.

未获得用户明确确认，绝不自动编辑代码。
自动修复过程中绝不进行语义重构。
仅修改代码格式和标准化空白字符。
必要时排除明显的非目标路径（如
```
.venv
```
、
```
build
```
、
```
dist
```
、缓存目录）。
如果用户要求使用严格PEP 8模式，不得强制使用Black的默认设置。

Examples

缺失依赖的处理方式

Scenario 1: Auditing a single file

—

User: "Can you check

script.py

for style issues?"

Agent Reference:

Check diagnostics:
bash
```
flake8 script.py --max-line-length 79
```
Report: "Found 3 issues in
```
script.py
```
: E231 missing whitespace, E302 expected 2 blank lines. Would you like me to fix them?"
User: "Yes."
Apply minimal safe formatting fixes and re-run
```
flake8
```
.

如果

flake8

或

black

缺失：

准确告知用户哪个工具不可用。
请求用户允许在当前环境中使用pip安装该工具。
如果用户拒绝，提供手动安装命令并安全终止流程。
如果用户批准，仅安装缺失的工具，然后重新运行诊断。

Scenario 2: Black-compatible repository

输出要求

User: "Format

src/

according to our Black setup and verify lint."

Agent Reference:

Check and report summary first.

bash

black --check --line-length 88 src/
flake8 src/ --max-line-length 88 --extend-ignore=E203,W503

"Checked 12 files. Found 45 violations. Proceed with formatting?"
User: "Go ahead."
Apply fixes:
bash
```
black --line-length 88 src/
```

报告时需包含：

分析范围
执行的命令
检查的文件数量
发现的主要静态代码分析问题类别
是否应用了修复
修复后剩余的问题（如有）

如果未发现违规问题，返回简短的成功总结。

Scenario 3: Strict PEP 8 in directory

示例

—

场景1：审计单个文件

User: "Fix PEP 8 issues in

src/

without Black rules."

Agent Reference:

Run strict diagnostics:
bash
```
flake8 src/ --max-line-length 79
```
Summarize violations by file/code and ask approval.
Apply only approved, non-semantic edits and re-run strict diagnostics.

用户： 你能检查

script.py

的代码风格问题吗？

助手执行步骤：

执行诊断：
bash
```
flake8 script.py --max-line-length 79
```
报告：
```
script.py
```
中发现3个问题：E231 缺少空格，E302 应空2行。是否需要我修复这些问题？
用户：是的。
应用最小化的安全格式修复، 然后重新运行
```
flake8
```
。

—

场景2：兼容Black的仓库

—

用户： 按照我们的Black配置格式化

src/

目录并验证静态代码分析。

助手执行步骤：

先执行检查并报告总结。

bash

black --check --line-length 88 src/
flake8 src/ --max-line-length 88 --extend-ignore=E203,W503

已检查12个文件，发现45处违规。是否继续执行格式化？
用户：继续。
应用修复：
bash
```
black --line-length 88 src/
```

—

场景3：目录下的严格PEP 8模式

—

用户： 修复

src/

目录中的PEP 8问题，不使用Black规则。

助手执行步骤：

运行严格模式诊断：
bash
```
flake8 src/ --max-line-length 79
```
按文件和错误代码汇总违规问题，并请求用户批准。
仅应用用户批准的非语义编辑，然后重新运行严格模式诊断。