Pylint throws errors that some of files are missing docstrings. I try and add docstrings to each class, method and function but it seems that Pylint also checks that files should a docstring at the beginning of it. Can i disable this somehow? I would like to be notified of a docstring is missing inside a class, function or method but it shouldn't be mandatory for a file to have a docstring.
Pylint会抛出某些文件缺少文档字符串的错误。我尝试将docstrings添加到每个类，方法和函数，但似乎Pylint还检查文件应该在文档字符串的开头。我可以以某种方式禁用它吗？我希望收到有关类，函数或方法中缺少docstring的通知，但对于文件来说，文件字符串不应该是强制性的。
(Is there a term of the legal jargon often found at the beginning of a proprietary source file? Any examples? I don't know whether it is a okay to post such a trivial question separately.)
（在专有源文件的开头是否有一个法律术语的术语？任何例子？我不知道是否可以单独发布这样一个小问题。）
5 个解决方案
#1
31
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 eg. http://hackerboss.com/get-rid-of-templates/)
Python模块有一个文档字符串，解释模块的功能，提供的内容，如何使用类的示例，这很好。这与你在文件开头经常看到的评论有所不同，这些评论提供了版权和许可信息，IMO不应该在文档字符串中（有些人甚至认为它们应该完全消失，参见例如http：// hackerboss。 COM / GET-RID-的模板/）
Pylint 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, and you may want to contribute to this pylint issue on github if it bothers you.
Pylint没有单独的代码用于可以发生文档字符串的各个位置，因此您所能做的就是禁用C0111。问题是，如果你在模块范围内禁用它，那么它将在模块中的任何地方被禁用（即你不会得到任何C行缺少函数/类/方法docstring。这可能是不好的，你可能想要如果它困扰你，在github上为这个pylint问题做出贡献。
So what I suggest is adding that small missing docstring, saying something like:
所以我建议添加一些小的缺失docstring，说：
"""
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).
很快，您将找到有用的东西放在那里，例如提供如何使用模块的各种类/函数的示例，这些类/函数不一定属于类/函数的各个文档字符串（例如如何互动，或类似快速入门指南之类的东西）。
#2
7
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 app.
我来寻找答案是因为，正如@cerin所说，在Django项目中，将模块文档字符串添加到django在创建新应用程序时自动生成的每个文件时都很麻烦且多余。
So, as a workaround for the fact that pylint doesn't let you specify a difference in docstring types, you can do this:
因此，作为pylint不允许您在docstring类型中指定差异的事实的解决方法，您可以这样做：
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.
您必须更新msg-template，以便在grep时仍然可以知道文件名。这将返回除模块之外的所有其他missing-docstring类型。
Then you can fix all of those errors, and afterwards just run:
然后你可以解决所有这些错误，然后运行：
pylint */*.py --disable=missing-docstring
#3
6
It's late, but still I found it useful. So sharing. Found this here.
已经很晚了，但我发现它很有用。分享。在这里找到了。
You can add "--errors-only" flag for pylint to disable warnings.
您可以为pylint添加“--errors-only”标志以禁用警告。
To do this, go to settings. Edit the following line:
为此，请转到设置。编辑以下行：
"python.linting.pylintArgs": []
“python.linting.pylintArgs”：[]
As
如
"python.linting.pylintArgs": ["--errors-only"]
“python.linting.pylintArgs”：[“ - error-only”]
And you are good to go!
你很高兴去！
#4
3
The question was asking whether you can disable the "missing module docstring" pylint error. The answer to this question is No. Pylint doesn't currently let you discriminate between doc-string warnings (which very annoying).
问题是询问是否可以禁用“missing module docstring”pylint错误。这个问题的答案是否定的.Pylint目前不允许你区分doc-string警告（这非常烦人）。
However, all is not lost, I recommend using flake8 for all python code checking. They really have their act together and I would have abandoned the python ship long ago without them. You can install the doc-string extension with pip --> pip install flake8_docstrings. It uses http://www.pydocstyle.org/en/latest/index.html.
但是，一切都没有丢失，我建议使用flake8进行所有python代码检查。他们真的一起行动，很久以前我就放弃了蟒蛇船。您可以使用pip - > pip install flake8_docstrings安装doc-string扩展。它使用http://www.pydocstyle.org/en/latest/index.html。
You can then just use the --ignore D100 switch. For example flake8 file.py --ignore D100
然后，您可以使用--ignore D100开关。例如flake8 file.py --ignore D100
#5
2
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.
您需要做的就是在每个函数中添加三重双引号字符串。
#1
31
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 eg. http://hackerboss.com/get-rid-of-templates/)
Python模块有一个文档字符串，解释模块的功能，提供的内容，如何使用类的示例，这很好。这与你在文件开头经常看到的评论有所不同，这些评论提供了版权和许可信息，IMO不应该在文档字符串中（有些人甚至认为它们应该完全消失，参见例如http：// hackerboss。 COM / GET-RID-的模板/）
Pylint 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, and you may want to contribute to this pylint issue on github if it bothers you.
Pylint没有单独的代码用于可以发生文档字符串的各个位置，因此您所能做的就是禁用C0111。问题是，如果你在模块范围内禁用它，那么它将在模块中的任何地方被禁用（即你不会得到任何C行缺少函数/类/方法docstring。这可能是不好的，你可能想要如果它困扰你，在github上为这个pylint问题做出贡献。
So what I suggest is adding that small missing docstring, saying something like:
所以我建议添加一些小的缺失docstring，说：
"""
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).
很快，您将找到有用的东西放在那里，例如提供如何使用模块的各种类/函数的示例，这些类/函数不一定属于类/函数的各个文档字符串（例如如何互动，或类似快速入门指南之类的东西）。
#2
7
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 app.
我来寻找答案是因为，正如@cerin所说，在Django项目中，将模块文档字符串添加到django在创建新应用程序时自动生成的每个文件时都很麻烦且多余。
So, as a workaround for the fact that pylint doesn't let you specify a difference in docstring types, you can do this:
因此，作为pylint不允许您在docstring类型中指定差异的事实的解决方法，您可以这样做：
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.
您必须更新msg-template，以便在grep时仍然可以知道文件名。这将返回除模块之外的所有其他missing-docstring类型。
Then you can fix all of those errors, and afterwards just run:
然后你可以解决所有这些错误，然后运行：
pylint */*.py --disable=missing-docstring
#3
6
It's late, but still I found it useful. So sharing. Found this here.
已经很晚了，但我发现它很有用。分享。在这里找到了。
You can add "--errors-only" flag for pylint to disable warnings.
您可以为pylint添加“--errors-only”标志以禁用警告。
To do this, go to settings. Edit the following line:
为此，请转到设置。编辑以下行：
"python.linting.pylintArgs": []
“python.linting.pylintArgs”：[]
As
如
"python.linting.pylintArgs": ["--errors-only"]
“python.linting.pylintArgs”：[“ - error-only”]
And you are good to go!
你很高兴去！
#4
3
The question was asking whether you can disable the "missing module docstring" pylint error. The answer to this question is No. Pylint doesn't currently let you discriminate between doc-string warnings (which very annoying).
问题是询问是否可以禁用“missing module docstring”pylint错误。这个问题的答案是否定的.Pylint目前不允许你区分doc-string警告（这非常烦人）。
However, all is not lost, I recommend using flake8 for all python code checking. They really have their act together and I would have abandoned the python ship long ago without them. You can install the doc-string extension with pip --> pip install flake8_docstrings. It uses http://www.pydocstyle.org/en/latest/index.html.
但是，一切都没有丢失，我建议使用flake8进行所有python代码检查。他们真的一起行动，很久以前我就放弃了蟒蛇船。您可以使用pip - > pip install flake8_docstrings安装doc-string扩展。它使用http://www.pydocstyle.org/en/latest/index.html。
You can then just use the --ignore D100 switch. For example flake8 file.py --ignore D100
然后，您可以使用--ignore D100开关。例如flake8 file.py --ignore D100
#5
2
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.
您需要做的就是在每个函数中添加三重双引号字符串。