Python代码审查工具：自动化检查PEP8、类型安全、异步模式与错误处理

python-code-review by existential-birds/beagle

247 周安装量

41 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/existential-birds/beagle --skill python-code-review

Python Web框架代码质量代码规范

🇨🇳中文介绍

Python 代码审查

快速参考

问题类型	参考文档
缩进、行长度、空白符、命名	references/pep8-style.md
缺少/错误的类型提示、Any 的使用	references/type-safety.md
异步函数中的阻塞调用、缺少 await	references/async-patterns.md
裸 except、缺少上下文、日志记录	references/error-handling.md
可变默认参数、print 语句	references/common-mistakes.md

审查清单

PEP8 风格

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

有效模式（请勿标记）

以下模式是故意为之且正确的——请勿将其报告为问题：

类型注解 vs 类型断言 - 注解声明类型，但并非运行时断言；不要与缺少验证混淆
与无类型库交互时使用 Any - 当外部库缺少类型存根时是必需的
空的 __init__.py 文件 - 对于包结构是有效的，不需要代码
noqa 注释 - 当 linter 规则不适用于特定情况时是有效的
运行时类型检查后使用 cast() - 通知类型检查器类型已缩小的正确模式

上下文相关规则

仅在满足特定条件时才标记这些问题：

问题	仅在以下情况标记
通用异常处理	存在具体且有意义的异常类型可用
未使用的变量	变量没有 `_` 前缀并且未在 f-strings、日志记录或调试中使用

何时加载参考文档

审查代码格式/风格时 → pep8-style.md
审查函数签名时 → type-safety.md
审查 async def 函数时 → async-patterns.md
审查 try/except 块时 → error-handling.md
通用 Python 审查时 → common-mistakes.md

代码是否遵循 PEP8 格式（缩进、行长度、空白符）？
导入是否已正确分组（标准库 → 第三方 → 本地）？
命名是否遵循约定（snake_case, CamelCase, UPPER_CASE）？
所有函数签名是否都有完整的类型标注？
异步函数是否真正非阻塞？
异常是否包含有意义的上下文？
是否存在可变默认参数？

提交审查结果前

在报告任何问题之前，请加载并遵循 review-verification-protocol。

🇺🇸English

Python Code Review

Quick Reference

Issue Type	Reference
Indentation, line length, whitespace, naming	references/pep8-style.md
Missing/wrong type hints, Any usage	references/type-safety.md
Blocking calls in async, missing await	references/async-patterns.md
Bare except, missing context, logging	references/error-handling.md
Mutable defaults, print statements	references/common-mistakes.md

Review Checklist

PEP8 Style

4-space indentation (no tabs)
Line length ≤79 characters (≤72 for docstrings/comments)
Two blank lines around top-level definitions, one within classes
Imports grouped: stdlib → third-party → local (blank line between groups)
No whitespace inside brackets or before colons/commas
Naming: snake_case for functions/variables, CamelCase for classes, UPPER_CASE for constants
Inline comments separated by at least two spaces

Type Safety

Type hints on all function parameters and return types
No Any unless necessary (with comment explaining why)
Proper T | None syntax (Python 3.10+)

Async Patterns

No blocking calls (time.sleep, requests) in async functions
Proper await on all coroutines

Error Handling

No bare except: clauses
Specific exception types with context
raise ... from to preserve stack traces

Common Mistakes

No mutable default arguments
Using logger not print() for output
f-strings preferred over .format() or %

Valid Patterns (Do NOT Flag)

These patterns are intentional and correct - do not report as issues:

Type annotation vs type assertion - Annotations declare types but are not runtime assertions; don't confuse with missing validation
UsingAny when interacting with untyped libraries - Required when external libraries lack type stubs
Empty__init__.py files - Valid for package structure, no code required
noqa comments - Valid when linter rule doesn't apply to specific case
Usingcast() after runtime type check - Correct pattern to inform type checker of narrowed type

Context-Sensitive Rules

Only flag these issues when the specific conditions apply:

Issue	Flag ONLY IF
Generic exception handling	Specific exception types are available and meaningful
Unused variables	Variable lacks `_` prefix AND isn't used in f-strings, logging, or debugging

When to Load References

Reviewing code formatting/style → pep8-style.md
Reviewing function signatures → type-safety.md
Reviewing async def functions → async-patterns.md
Reviewing try/except blocks → error-handling.md
General Python review → common-mistakes.md

Review Questions

Does the code follow PEP8 formatting (indentation, line length, whitespace)?
Are imports properly grouped (stdlib → third-party → local)?
Do names follow conventions (snake_case, CamelCase, UPPER_CASE)?
Are all function signatures fully typed?
Are async functions truly non-blocking?
Do exceptions include meaningful context?
Are there any mutable default arguments?

Before Submitting Findings

Load and follow review-verification-protocol before reporting any issue.

Weekly Installs

247

Repository

existential-birds/beagle

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

gemini-cli208

opencode208

codex203

github-copilot198

cursor185

amp157

PPTX 文件处理全攻略：Python 脚本创建、编辑、分析 .pptx 文件内容与结构

805 周安装