当前位置：文江博客话题详情

Python pylint docstring

如何禁用“缺少文档字符串” Pylint 中文件级别的警告？

发布于 2024-12-11 08:45:55 字数 208 浏览 0 评论 0 原文

Pylint 会抛出某些文件缺少文档字符串的错误。我尝试向每个类、方法和函数添加文档字符串，但 Pylint 似乎还会检查文件开头是否应该有文档字符串。我可以以某种方式禁用它吗？

我希望收到有关类、函数或方法中缺少文档字符串的通知，但文件不应该强制具有文档字符串。

（专有源文件开头经常出现的法律术语是否有一个术语？有例子吗？我不知道是否可以单独发布这样一个琐碎的问题。）

原文

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

轮廓§ 2024-12-18 08:45:56

Python 模块最好有一个文档字符串，解释模块的功能、提供的内容以及如何使用类的示例。这与您经常在文件开头看到的提供版权和许可信息的注释不同，IMO 不应将其放入文档字符串中（有些人甚至认为它们应该完全消失，请参见例如 摆脱源代码模板）

使用 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。问题是，如果您在模块范围内禁用此功能，那么它将在模块中的所有位置禁用（即，您不会因为缺少函数/类/方法文档字符串而获得任何 C 行。这可能不太好。

所以我建议添加那个小的缺失文档字符串，这样说：

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

很快，您就会发现可以放入其中的有用内容，例如提供如何使用模块的各种类/函数的示例，这些类/函数不一定属于各个文档字符串类/函数（例如例如它们如何相互作用，或者诸如快速入门指南之类的东西）。

It is nice for a Python module to have a docstring, explaining what the module does, what it provides, examples of how to use the classes. This is different from the comments that you often see at the beginning of a file giving the copyright and license information, which IMO should not go in the docstring (some even argue that they should disappear altogether, see e.g. Get Rid of Source Code Templates)

With Pylint 2.4 and above, you can differentiate between the various missing-docstring by using the three following sub-messages:

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

So the following .pylintrc file should work:

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

For previous versions of Pylint, it does not have a separate code for the various place where docstrings can occur, so all you can do is disable C0111. The problem is that if you disable this at module scope, then it will be disabled everywhere in the module (i.e., you won't get any C line for missing function / class / method docstring. Which arguably is not nice.

So I suggest adding that small missing docstring, saying something like:

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

Soon enough, you'll be finding useful things to put in there, such as providing examples of how to use the various classes / functions of the module which do not necessarily belong to the individual docstrings of the classes / functions (such as how these interact, or something like a quick start guide).

回复收藏 0 原文

流年里的时光 2024-12-18 08:45:56

正如评论中 followben 所提到的，更好的解决方案是禁用我们想要禁用的规则，而不是使用 <代码>--仅错误。这可以通过 --disable=, -d 来完成。

消息 ID 列表可以在此处找到。对于问题中提到的具体错误，消息 ID 为 C0111。

要在您选择的 IDE 或文本编辑器中使用 --disable= 参数，您需要弄清楚如何操作。

对于 VS Code，可以通过在 settings.json 中添加以下内容来完成：

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

As mentioned by followben in the comments, a better solution is to just disable the rules that we want to disable rather than using --errors-only. This can be done with --disable=<msg ids>, -d <msg ids>.

The list of message IDs can be found here. For the specific error mentioned in the question, the message ID is C0111.

For using --disable= param in your choise of IDE or Text Editor, you will need to figure out how to do it.

For VS Code, this can be done by adding this in settings.json:

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

回复收藏 0 原文

亂 2024-12-18 08:45:56

只需将以下行放在要禁用这些警告的任何文件的开头即可。

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

Just put the following lines at the beginning of any file you want to disable these warnings for.

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

回复收藏 0 原文

攒一口袋星星 2024-12-18 08:45:56

我只是想添加 @Milovan Tomašević 上面发布的内容。我决定在 VSCode 的 python.linting.pylintArgs >全局设置，因为它比使用 .pylintrc 文件方便得多。
另外，我没有使用开关 ID（例如 C0115），而是使用符号名称。

Pylint 选项和开关的完整参考位于此处。

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

I just wanted to add to what @Milovan Tomašević posted above. I decided to use python.linting.pylintArgs in VSCode's global settings, as it was far more convenient than using a .pylintrc file.
Also, instead of using an ID for the switch (such as C0115), I used the symbolic names instead.

Full reference to Pylint options and switches is here.

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

回复收藏 0 原文

只是在用心讲痛 2024-12-18 08:45:56

就我而言，使用 Pylint 2.6.0，即使在显式禁用 missing-module-docstring、missing-class-docstring 和 <我的 .pylintrc 文件中的 code>missing-function-docstring 。最后，以下配置对我有用：

[MESSAGES CONTROL]

disable=missing-docstring,empty-docstring

显然，Pylint 2.6.0 仍然会验证文档字符串，除非这两项检查都被禁用。

In my case, with Pylint 2.6.0, the missing docstring messages wouldn't disappear, even after explicitly disabling missing-module-docstring, missing-class-docstring and missing-function-docstring in my .pylintrc file. Finally, the following configuration worked for me:

[MESSAGES CONTROL]

disable=missing-docstring,empty-docstring

Apparently, Pylint 2.6.0 still validates docstrings unless both checks are disabled.

回复收藏 0 原文

深海少女心 2024-12-18 08:45:56

我来寻找答案是因为，cerin 说，在 Django 项目中，将模块文档字符串添加到每个文件中是麻烦且多余的Django 在创建新应用程序时自动生成。

因此，作为 Pylint 不允许您指定文档字符串类型差异这一事实的解决方法，您可以这样做：

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

您必须更新 msg 模板，以便当您 grep 时您仍然知道文件名。这将返回除模块之外的所有其他缺失文档字符串类型。

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

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

I came looking for an answer because, as cerin said, in Django projects it is cumbersome and redundant to add module docstrings to every one of the files that Django automatically generates when creating a new application.

So, as a workaround for the fact that Pylint doesn't let you specify a difference in docstring types, you can do this:

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

You have to update the msg-template, so that when you grep you will still know the file name. This returns all the other missing-docstring types excluding modules.

Then you can fix all of those errors, and afterwards just run:

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

回复收藏 0 原文

烟花易冷人易散 2024-12-18 08:45:56

使用 Pylint 2.4 及更高版本，您可以使用以下三个子消息来区分各种 missing-docstring：

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

所以以下 .pylintrc 文件应该可以工作：

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

With Pylint 2.4 and above you can differentiate between the various missing-docstring by using the three following sub-messages:

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

So the following .pylintrc file should work:

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

回复收藏 0 原文

零崎曲识 2024-12-18 08:45:56

我认为在不禁用此功能的情况下修复相对容易。

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

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

I think the fix is relative easy without disabling this feature.

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

All you need to do is add the triple double quotes string in every function.

回复收藏 0 原文

飘逸的'云 2024-12-18 08:45:56

我正在使用 VSCode (1.78.0)，看起来他们更改了参数。
您应该使用

  "pylint.args": [
    "--disable=C0116",
    "--disable=C0111",
    "--disable=C0114"
  ]

2024 - 文档：

禁用文档、模块和函数文档需要三个参数：

缺少文档字符串 / C0111
missing-module-docstring / C0114
< a href="https://pylint.readthedocs.io/en/latest/user_guide/messages/convention/missing-function-docstring.html" rel="nofollow noreferrer">缺少函数文档字符串 / C0116

I'm using VSCode (1.78.0) and it looks like they changed the parameters.
You should use

  "pylint.args": [
    "--disable=C0116",
    "--disable=C0111",
    "--disable=C0114"
  ]

2024 - Documentation:

Three args are necessary to disable doc, module and functions documentation:

回复收藏 0 原文

初熏 2024-12-18 08:45:56

不。 Pylint 目前不允许您区分文档字符串警告。

但是，您可以使用 Flake8 进行所有 Python 代码检查以及文档 -字符串扩展来忽略此警告。

使用 pip 安装文档字符串扩展（在内部，它使用 pydocstyle）。

pip install flake8_docstrings

然后您只需使用 --ignore D100 开关即可。例如，flake8 file.py --ignore D100

No. Pylint doesn't currently let you discriminate between doc-string warnings.

However, you can use Flake8 for all Python code checking along with the doc-string extension to ignore this warning.

Install the doc-string extension with pip (internally, it uses pydocstyle).

pip install flake8_docstrings

You can then just use the --ignore D100 switch. For example, flake8 file.py --ignore D100

回复收藏 0 原文

燃情 2024-12-18 08:45:56

如果您是想要忽略此问题的 Visual Studio Code 用户，可以将 python.linting.pylintArgs 添加到 .vscode/设置.json：

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

If you are a Visual Studio Code user who wants to ignore this, you can add python.linting.pylintArgs to .vscode/settings.json:

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

回复收藏 0 原文

诗笺 2024-12-18 08:45:56

编辑文件“C:\Users\Your User\AppData\Roaming\Code\User\settings.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"
    ],
}

Edit file "C:\Users\Your User\AppData\Roaming\Code\User\settings.json" and add these python.linting.pylintArgs lines at the end as shown below:

{
    "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"
    ],
}

回复收藏 0 原文

娇柔作态 2024-12-18 08:45:56

Ctrl + Shift + P
然后键入并单击 >首选项：配置特定于语言的设置
，然后输入“python”。粘贴代码

<前><代码> {
“python.linting.pylintArgs”：[
“--load-plugins=pylint_django”，“--仅错误”
],
}

Ctrl + Shift + P
Then type and click on > preferences:configure language specific settings

and then type "python" after that. Paste the code

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

回复收藏 0 原文

喜爱皱眉﹌ 2024-12-18 08:45:56

打开用户设置（JSON）并将以下行复制并粘贴到大括号之间，然后保存并退出文件。

"pylint.args": [
    "disable=missing-module-docstring",
    "disable=missing-class-docstring",
    "disable=missing-function-docstring"
]

这对我来说是上述解决方案的一部分。

Open User Settings(JSON) and copy and paste the following lines in between the the curly braces, then save and exit the file.

"pylint.args": [
    "disable=missing-module-docstring",
    "disable=missing-class-docstring",
    "disable=missing-function-docstring"
]

This worked for me out of the above solution.

回复收藏 0 原文

柒夜笙歌凉 2024-12-18 08:45:56

我在任何地方都找不到这个，这是唯一真正有效的东西。我在 pylint 的设置中搜索，注意到语法看起来有所不同，这在此处的注释中进行了解释。这是我的确切用户> settings.json 文件以及我如何获取它，以便 VS Code 中的文档字符串不会显示 linting 错误。

{
    "workbench.colorTheme": "Default High Contrast",
    "editor.fontSize": 15,
    "debug.console.fontSize": 16,
    "terminal.integrated.fontSize": 16,
    "terminal.integrated.defaultProfile.osx": "bash",
    "editor.tabSize": 2,
    "[python]": {
        "editor.insertSpaces": true,
        "editor.tabSize": 4
      },
      "pylint.args": [
        "--disable=missing-class-docstring",
        "--disable=missing-function-docstring",
        "--disable=missing-module-docstring"
      ]
}

更改该文件后，我执行了 CMD+shift+P 并搜索 Developer reload window 并重新加载了 VS code。保存你的 python 文件，你不应该看到 doc 字符串的 linting 错误。

I couldn't find this anywhere and this is the only thing that actually worked. I searched in settings for pylint and noticed the syntax looked different that was was being explained in comments here. This is my exact user > settings.json file and how I was able to get it so no linting errors showed for docs-strings in VS Code.

{
    "workbench.colorTheme": "Default High Contrast",
    "editor.fontSize": 15,
    "debug.console.fontSize": 16,
    "terminal.integrated.fontSize": 16,
    "terminal.integrated.defaultProfile.osx": "bash",
    "editor.tabSize": 2,
    "[python]": {
        "editor.insertSpaces": true,
        "editor.tabSize": 4
      },
      "pylint.args": [
        "--disable=missing-class-docstring",
        "--disable=missing-function-docstring",
        "--disable=missing-module-docstring"
      ]
}

After changing that file I did a CMD+shift+P and search for Developer reload window and did a reload of VS code. Save your python file, and you should not see the linting error for doc string.

回复收藏 0 原文

稚气少女 2024-12-18 08:45:56

转到文件“settings.json”并禁用 Python pydocstyle：

"python.linting.pydocstyleEnabled": false

Go to file "settings.json" and disable the Python pydocstyle:

"python.linting.pydocstyleEnabled": false

回复收藏 0 原文

杯别 2024-12-18 08:45:56

对我来说，我喜欢完全控制文档字符串的放置位置和时间，而不会让 VSCode（或任何 IDE/代码编辑器）给我带来视觉混乱 - 因此我只是简单地插入

[pylint.messages control]
disable = missing-docstring

到我的 .pylintrc 文件中。该文件未提交，例如 gitignore 的一部分 - 因此从事该项目的每个团队成员都可以有自己的设置。仅当项目已经存在一个遵循的标准时，这才有效（否则每个人都会用这些注释和文档字符串及其混乱做自己的事情） - 因此，在使用此设置之前，请确保您知道自己在做什么。与长期合作并遵守如何为项目编写代码的内部标准的团队合作。

For me, I like to have total control on where and when I put my docstrings without having VSCode (or any IDE / code editor) throw visual chaos at me - hence I have simply inserted

[pylint.messages control]
disable = missing-docstring

in my .pylintrc file. This file is not committed e.g. part of gitignore - hence each team member working on the project can have their own setting. This only works if there is already a standard that the project adheres to (else everyone will be doing their own thing with these comments and docstrings and its chaos) - so make sure you know what you're doing before using this setup. works with teams that have been working together for a long time and who adhere to internal standards on how to write code for the project.

回复收藏 0 原文

幻想少年梦 2024-12-18 08:45:56

ruff 用户。

[lint]
select = ["D"] # enable docstring checks in ruff
ignore = ["D100"] # ignore missing module docstring

对于位于 ruff.toml 文件内的

For ruff users that would be

[lint]
select = ["D"] # enable docstring checks in ruff
ignore = ["D100"] # ignore missing module docstring

inside your ruff.toml file.

回复收藏 0 原文

~没有更多了~

关于作者

风筝在阴天搁浅。

暂无简介

0 文章

0 评论

24 人气

关注发私信

友情链接

文江博客

如何禁用“缺少文档字符串” Pylint 中文件级别的警告？

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

评论（18）

2024 - 文档：

2024 - Documentation:

关于作者

相关话题

热门标签

推荐作者

尘世孤行

烟─花易冷

你是年少的欢喜

倒带

忱杏

送君千里

友情链接

如何禁用“缺少文档字符串” Pylint 中文件级别的警告？

如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

评论（18）

2024 - 文档：

2024 - Documentation:

关于作者

相关话题

热门标签

推荐作者

尘世孤行

烟─花易冷

你是年少的欢喜

倒带

忱杏

送君千里

友情链接

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。