如何在 Pylint 中禁用文件级别的 “missing docstring” 警告？

Pylint 抛出错误，表示有些文件缺少 docstrings。我尝试为每个类、方法和函数添加 docstrings,但似乎 Pylint 也检查这些文件是否应该在开头有 docstrings。我能否禁用这个功能？

我希望得到一个 docstring 在类、函数或方法中丢失的通知，但是文件不应该强制使用 docstring。

(在专有源文件的开头是否经常出现法律术语的术语？有什么例子吗？我不知道单独发布这样一个琐碎的问题是否合适。)

284782 次浏览
小开
最佳答案

Python 模块最好有一个 docstring，解释模块的作用、提供的内容以及如何使用这些类的示例。这不同于你经常在文件开头看到的给出版权和许可信息的注释，IMO 不应该把这些信息放进 docstring (有些人甚至认为它们应该完全消失，参见 一个 href = “ http://hackerboss.com/Get-Rid-of-template/”rel = “ noReferrer”> Get Ride of Source Code Template )

使用 Pylint 2.4及以上版本，您可以通过使用以下三个子消息来区分各种 missing-docstring:

  • C0114(missing-module-docstring)
  • C0115(missing-class-docstring)
  • C0116(missing-function-docstring)

因此，下面的 .pylintrc文件应该可以工作:

[MASTER]
disable=
C0114, # missing-module-docstring

对于早期版本的 Pylint，它没有针对文档字符串可能出现的不同位置的单独代码，因此您所能做的就是禁用 C0111。问题是，如果您在模块范围内禁用它，那么它将在模块中的任何地方被禁用(即，您不会得到任何缺少函数/类/方法 docstring 的 C 行。这可不是什么好事。

所以我建议加上这个小小的文档字符串，比如:

"""
high level support for doing this and that.
"""

很快，你就会发现有用的东西放在那里，例如提供例子说明如何使用模块的各种类/函数，这些类/函数不一定属于类/函数的单独文档字符串(例如它们是如何交互的，或者类似于快速入门指南的东西)。

小开

我来寻找答案是因为，作为 Cerin 说，在 Django 项目中，将模块 docstring 添加到 Django 在创建新应用程序时自动生成的每个文件中是繁琐和多余的。

因此，为了解决 Pylint 不允许指定 docstring 类型差异的问题，可以这样做:

pylint */*.py --msg-template='{path}: {C}:{line:3d},{column:2d}: {msg}' | grep docstring | grep -v module

必须更新 msg-template，以便在 grep 时仍然知道文件名。这将返回所有其他丢失的 docstring 类型(不包括模块)。

然后您可以修复所有这些错误，然后运行:

pylint */*.py --disable=missing-docstring
小开

我认为这个修复相对容易，不需要禁用这个特性。

def kos_root():
"""Return the pathname of the KOS root directory."""
global _kos_root
if _kos_root: return _kos_root

您所需要做的就是在每个函数中添加三重双引号字符串。

小开

当前，Pylint 不允许区分 doc-string 警告。

但是，您可以使用 Flake8进行所有 Python 代码检查，并使用 doc-string 扩展来忽略此警告。

使用 pip 安装 doc-string 扩展(内部使用 Pydocstyle)。

pip install flake8_docstrings

然后您可以只使用 --ignore D100开关

小开

[2021年12月21日更新]

正如 跟着 Ben在评论中提到的，一个更好的解决方案是禁用我们想要禁用的规则，而不是使用 --errors-only。

这可以通过在设置中添加以下内容来实现:

"python.linting.pylintArgs": ["--disable=C0111"]

[老答案]

我找到了这个 给你。

您可以为 Pylint 添加“—— error-only”标志以禁用警告。

要做到这一点，进入设置。编辑以下行:

"python.linting.pylintArgs": []

就像

"python.linting.pylintArgs": ["--errors-only"]

你可以走了！

小开

使用 Pylint 2.4及以上版本，您可以通过使用以下三个子消息来区分各种 missing-docstring:

  • C0114(missing-module-docstring)
  • C0115(missing-class-docstring)
  • C0116(missing-function-docstring)

因此，下面的 .pylintrc文件应该可以工作:

[MASTER]
disable=
C0114, # missing-module-docstring
小开

编辑文件“ C: Users Your User AppData Roaming Code User setings.json”，并在末尾添加这些 python.linting.pylintArgs行，如下所示:

{
"team.showWelcomeMessage": false,
"python.dataScience.sendSelectionToInteractiveWindow": true,
"git.enableSmartCommit": true,
"powershell.codeFormatting.useCorrectCasing": true,
"files.autoSave": "onWindowChange",
"python.linting.pylintArgs": [
"--load-plugins=pylint_django",
"--errors-only"
],
}
小开

只需将以下行放在任何希望为其禁用这些警告的文件的开头。

# pylint: disable=missing-module-docstring
# pylint: disable=missing-class-docstring
# pylint: disable=missing-function-docstring
小开

  1. Ctrl + Shift + P

  2. 然后键入并单击 > 首选项: 配置特定于语言的设置

  3. 然后输入“ python”粘贴代码

     {
"python.linting.pylintArgs": [
"--load-plugins=pylint_django", "--errors-only"
],
}
小开

转到文件“ setings.json”并禁用 Python pydocstyle:

"python.linting.pydocstyleEnabled": false
小开

在我的例子中，使用 Pylint2.6.0，即使在我的 .pylintrc文件中显式禁用了 missing-module-docstring、 missing-class-docstring和 missing-function-docstring，丢失的 docstring 消息也不会消失。最后，以下配置适合我:

[MESSAGES CONTROL]


disable=missing-docstring,empty-docstring

显然，Pylint2.6.0仍然验证文档字符串，除非两个检查都被禁用。

小开

如果你是一个 < em > Visual Studio Code 用户谁想要忽略这一点，你可以添加 python.linting.pylintArgs到 .vscode/settings.json:

{
...
"python.linting.pylintArgs": [
"--disable=C0114",
"--disable=C0115",
"--disable=C0116",
],
...
}
小开

我只是想补充什么 @ Milovan Toma evi张贴以上。我决定在 VSCode 的 全局设置中使用 python.linting.pylintArgs，因为它比使用 .pylintrc文件方便得多。
此外，我没有使用开关的 ID (例如 C0115) ，而是使用了符号名称。

完全参照 Pylint 选项和开关在这里。

{
"python.linting.pylintArgs": [
"--disable=missing-class-docstring",
"--disable=missing-function-docstring"
]
}

提交答案