Как отключить предупреждения «отсутствует строка документа» на уровне файлов в Pylint?

Question

Pylint выдает ошибки, что в некоторых файлах отсутствуют строки документации. Я пытаюсь добавить строки документации к каждому классу, методу и функции, но кажется, что Pylint также проверяет, что файлы должны иметь строку документации в начале. Могу ли я отключить это как-то? Я хотел бы получить уведомление о том, что в классе, функции или методе отсутствует строка документа, но для файла не обязательно иметь строку документа.

(Есть ли термин юридического жаргона, часто встречающийся в начале проприетарного исходного файла? Какие-нибудь примеры? Я не знаю, нормально ли публиковать такой тривиальный вопрос отдельно.)

Answer 1

Для модуля Python хорошо иметь строку документации, объясняющую, что делает модуль, что он предоставляет, примеры того, как использовать классы.Это отличается от комментариев, которые вы часто видите в начале файла с информацией об авторском праве и лицензии, который IMO не должен указывать в строке документации (некоторые даже утверждают, что они должны вообще исчезнуть, см., Например, http://hackerboss.com/get-rid-of-templates/)

У Pylint нет отдельного кода для различных мест, где могут возникать строки документации, поэтому все, что вы можете сделать, это отключить C0111. Проблема в том, что если вы отключите это в области видимости модуля, то он будет отключен везде в модуле (то есть вы не получите никакой строки C за отсутствующую строку документации функции / класса / метода. Что, возможно, нехорошо, и вы можете внести свой вклад в эту проблему pylint на github , если это вас беспокоит.

Итак, я предлагаю добавить эту маленькую недостающую строку документации, говоря что-то вроде:

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

Достаточно скоро вы найдете здесь полезные вещи, такие как примеры использованияразличные классы / функции модуля, которые не обязательно принадлежат отдельному документуg классов / функций (например, как они взаимодействуют, или что-то вроде краткого руководства по началу работы).

Answer 2

Уже поздно, но все же я нашел это полезным. Так что делюсь. Нашел это здесь .

Вы можете добавить флаг --errors-only для pylint, чтобы отключить предупреждения.

Для этого перейдите в настройки. Отредактируйте следующую строку:

"python.linting.pylintArgs": []

Как

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

И тебе пора!

Answer 3

Я искал ответ, потому что, как сказал @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

Answer 4

Нет. В настоящее время Pylint не позволяет вам различать предупреждения строки документа.

Однако вы можете использовать flake8 для проверки всего кода Python вместе с расширением doc-string, чтобы игнорировать это предупреждение.

Установите расширение doc-string с помощью pip (внутренне оно использует pydocstyle ).

pip install flake8_docstrings

Затем вы можете просто использовать переключатель --ignore D100. Например flake8 file.py --ignore D100

Answer 5

Я думаю, что исправить это относительно легко без отключения этой функции.

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

Все, что вам нужно сделать, это добавить строку тройных двойных кавычек в каждую функцию.