bastgau/docstring-linter
GitHub: bastgau/docstring-linter
一个可配置的 Python 代码检查工具，用于验证 docstring 是否符合 Google 风格规范。
Stars: 1 | Forks: 0
# Docstring Linter
Python linter，用于检查 docstring 是否符合 Google 风格。
## 用法
```
# Lint 单个文件
docstring-linter src/module.py
# Lint 项目
docstring-linter src/
# 列出可用规则
docstring-linter --list-rules
# JSON 报告 (stdout)
docstring-linter src/ --format json
# GitHub Actions annotations (stdout)
docstring-linter src/ --format github-annotations
# 显式 config
docstring-linter src/ --config pyproject.toml
# CI/CD
docstring-linter src/ && echo "OK" || echo "FAIL"
```
### 选项
| 选项 | 描述 |
|--------|-------------|
| `--exclude` | 要排除的 Glob 匹配模式。覆盖配置文件。 |
| `--workers` | 并行 worker 数量（0 = 自动，1 = 顺序执行）。 |
| `--format` | 输出格式：`text`（默认）、`json` 或 `github-annotations`。 |
| `--list-rules` | 显示所有可用的规则并退出。 |
| `--config` | 指定配置文件的路径（任意 `.toml`）。 |
## 配置
配置按以下顺序加载（以第一个匹配的为准）：
1. 显式指定的 `--config path/to/file.toml`
2. 从当前目录向上查找包含 `[tool.docstring-linter]` 部分的 `pyproject.toml`
3. 从当前目录向上查找 `.docstring-linter.toml`
4. 内置默认值
### pyproject.toml
```
[tool.docstring-linter]
style = "google"
select = ["ALL"]
ignore = [
"returns_none_init", # opt-in
"returns_none_oneliner", # opt-in
]
exclude_empty_init = true
ignore_placeholder_docstrings = false
exclude = ["test_*", "*_test.py"]
workers = 1
summary_max_length = 80
[tool.docstring-linter.scope]
modules = true
classes = true
functions = true
methods = true
```
### .docstring-linter.toml
独立的配置文件 —— 使用相同的键，但不包含 `[tool.docstring-linter]` 外层包裹。`[scope]` 会替代 `[tool.docstring-linter.scope]`。
```
style = "google"
select = ["ALL"]
ignore = [
"returns_none_init", # opt-in
"returns_none_oneliner", # opt-in
]
exclude_empty_init = true
ignore_placeholder_docstrings = false
exclude = ["test_*", "*_test.py"]
workers = 1
summary_max_length = 80
[scope]
modules = true
classes = true
functions = true
methods = true
```
### 键
| 键 | 默认值 | 描述 |
|-----|---------|-------------|
| `style` | `"google"` | 要强制执行的 docstring 风格。 |
| `select` | 除可选规则外的所有规则 | 要启用的规则。`["ALL"]` 表示启用全部。 |
| `ignore` | `[]` | 要禁用的规则（在 `select` 之后应用）。 |
| `exclude_empty_init` | `true` | 跳过没有参数且没有函数体的 `__init__` 方法。 |
| `ignore_placeholder_docstrings` | `false` | 跳过仅包含 `...` 的 docstring。 |
| `exclude` | 参见默认值 | 用于跳过文件和目录的 Glob/字面量模式。 |
| `workers` | `1` | 并行 worker。`0` = 自动检测 CPU 核心数。 |
| `summary_max_length` | `80` | `summary_too_long` 规则的摘要行最大长度。 |
| `scope.modules` | `true` | 检查模块级别的 docstring。 |
| `scope.classes` | `true` | 检查类的 docstring。 |
| `scope.functions` | `true` | 检查函数的 docstring。 |
| `scope.methods` | `true` | 检查方法的 docstring。 |
## 规则参考
可用规则列表请参阅 [RULES](/RULES.md) 页面。
## 集成
### pre-commit / prek
添加到您的 `.pre-commit-config.yaml` 中：
```
repos:
- repo: https://github.com/bastgau/docstring-linter
rev: v0.1.0
hooks:
- id: docstring-linter
files: ^src/
```
然后安装 hook：
```
pre-commit install
# 或
prek install
```
### GitHub Actions
#### Composite action
```
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.14"
- uses: bastgau/docstring-linter@v0.1.0
with:
paths: src/
format: github-annotations
```
| 输入 | 默认值 | 描述 |
|-------|---------|-------------|
| `paths` | `src/` | 要进行 lint 的文件或目录。 |
| `format` | `github-annotations` | 输出格式：`text`、`json` 或 `github-annotations`。 |
| `extra-args` | `""` | 传递给 `docstring-linter` 的额外参数。 |
标签：Apache Flink, LNA, Python, Python安全, SOC Prime, 代码规范检查, 开发工具, 无后门, 聊天机器人, 逆向工具, 错误基检测, 静态代码分析