From cf33fcffa1b0c6d6de4ca64052dfc352f971d576 Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Mon, 16 May 2022 18:01:33 +0200 Subject: [doc] Move all messages documentation to user_guide/messages --- .gitignore | 9 +- doc/Makefile | 5 +- doc/conf.py | 3 + doc/exts/pylint_messages.py | 2 +- doc/index.rst | 1 - doc/messages/index.rst | 11 - doc/messages/messages_introduction.rst | 15 - doc/messages/messages_list.rst | 539 ---------------------------- doc/user_guide/index.rst | 2 +- doc/user_guide/message-control.rst | 205 ----------- doc/user_guide/messages/index.rst | 34 ++ doc/user_guide/messages/message-control.rst | 201 +++++++++++ doc/user_guide/messages/messages_list.rst | 539 ++++++++++++++++++++++++++++ 13 files changed, 790 insertions(+), 776 deletions(-) delete mode 100644 doc/messages/index.rst delete mode 100644 doc/messages/messages_introduction.rst delete mode 100644 doc/messages/messages_list.rst delete mode 100644 doc/user_guide/message-control.rst create mode 100644 doc/user_guide/messages/index.rst create mode 100644 doc/user_guide/messages/message-control.rst create mode 100644 doc/user_guide/messages/messages_list.rst diff --git a/.gitignore b/.gitignore index b4fa458be..ea96bb688 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,14 @@ /pylint.egg-info/ .tox *.sw[a-z] -doc/messages/ +# Can't use | operator in .gitignore, see +# https://unix.stackexchange.com/a/31806/189111 +doc/user_guide/messages/convention/ +doc/user_guide/messages/error/ +doc/user_guide/messages/fatal/ +doc/user_guide/messages/information/ +doc/user_guide/messages/refactor/ +doc/user_guide/messages/warning/ doc/technical_reference/extensions.rst doc/technical_reference/features.rst doc/user_guide/configuration/all-options.rst diff --git a/doc/Makefile b/doc/Makefile index 73ab49ae5..ee03e051e 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -36,8 +36,9 @@ help: @echo " linkcheck to check all external links for integrity" clean: - -rm -rf $(BUILDDIR)/* messages/convention messages/error messages/fatal messages/information \ - messages/refactor messages/warning technical_reference/extensions.rst technical_reference/features.rst + -rm -rf $(BUILDDIR)/* user_guide/messages/convention user_guide/messages/error \ + user_guide/messages/fatal user_guide/messages/information user_guide/messages/refactor \ + user_guide/messages/warning technical_reference/extensions.rst technical_reference/features.rst install-dependencies: @echo "Install dependencies" diff --git a/doc/conf.py b/doc/conf.py index 63bb99976..5134ffe67 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -51,6 +51,9 @@ redirects: dict[str, str] = { "intro": "index.html", "support": "contact.html", "user_guide/ide-integration": "installation.html", + "messages/index": "user_guide/messages/index.html", + "messages/messages_introduction": "user_guide/messages/index.html", + "user_guide/message-control": "user_guide/messages/message-control.html", } # Add any paths that contain templates here, relative to this directory. diff --git a/doc/exts/pylint_messages.py b/doc/exts/pylint_messages.py index 4388985d9..7b09f0ff6 100644 --- a/doc/exts/pylint_messages.py +++ b/doc/exts/pylint_messages.py @@ -23,7 +23,7 @@ from pylint.utils import get_rst_title PYLINT_BASE_PATH = Path(__file__).resolve().parent.parent.parent """Base path to the project folder.""" -PYLINT_MESSAGES_PATH = PYLINT_BASE_PATH / "doc" / "messages" +PYLINT_MESSAGES_PATH = PYLINT_BASE_PATH / "doc/user_guide/messages" """Path to the messages documentation folder.""" PYLINT_MESSAGES_DATA_PATH = PYLINT_BASE_PATH / "doc" / "data" / "messages" diff --git a/doc/index.rst b/doc/index.rst index 0a77c7463..df9a4c133 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -44,7 +44,6 @@ re-evaluate and re-enable messages as your priorities evolve. tutorial user_guide/index.rst how_tos/index.rst - messages/index.rst technical_reference/index.rst development_guide/index.rst additional_commands/index.rst diff --git a/doc/messages/index.rst b/doc/messages/index.rst deleted file mode 100644 index aceca53f6..000000000 --- a/doc/messages/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _messages: - -Messages -=================== - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - messages_introduction - messages_list diff --git a/doc/messages/messages_introduction.rst b/doc/messages/messages_introduction.rst deleted file mode 100644 index e351d1b9b..000000000 --- a/doc/messages/messages_introduction.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _messages-introduction: - -Message categories -===================== - -Pylint can emit various messages. These are categorized according to categories:: - - Convention - Error - Fatal - Information - Refactor - Warning - -A list of these messages can be found here: :ref:`messages-list` diff --git a/doc/messages/messages_list.rst b/doc/messages/messages_list.rst deleted file mode 100644 index c7674dcb7..000000000 --- a/doc/messages/messages_list.rst +++ /dev/null @@ -1,539 +0,0 @@ -.. _messages-list: - -Overview of all Pylint messages -=============================== - -.. - NOTE This file is auto-generated. Make any changes to the associated - docs extension in 'pylint_messages.py'. - -Pylint can emit the following messages: - -Fatal ------ - -All messages in the fatal category: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - fatal/astroid-error.rst - fatal/config-parse-error.rst - fatal/fatal.rst - fatal/method-check-failed.rst - fatal/parse-error.rst - -All renamed messages in the fatal category: - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - fatal/old-import-error.rst - - -Error ------ - -All messages in the error category: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - error/abstract-class-instantiated.rst - error/access-member-before-definition.rst - error/assigning-non-slot.rst - error/assignment-from-no-return.rst - error/assignment-from-none.rst - error/await-outside-async.rst - error/bad-configuration-section.rst - error/bad-except-order.rst - error/bad-exception-context.rst - error/bad-format-character.rst - error/bad-option-value.rst - error/bad-plugin-value.rst - error/bad-reversed-sequence.rst - error/bad-str-strip-call.rst - error/bad-string-format-type.rst - error/bad-super-call.rst - error/bidirectional-unicode.rst - error/broken-collections-callable.rst - error/broken-noreturn.rst - error/catching-non-exception.rst - error/class-variable-slots-conflict.rst - error/continue-in-finally.rst - error/dict-iter-missing-items.rst - error/duplicate-argument-name.rst - error/duplicate-bases.rst - error/format-needs-mapping.rst - error/function-redefined.rst - error/import-error.rst - error/inconsistent-mro.rst - error/inherit-non-class.rst - error/init-is-generator.rst - error/invalid-all-format.rst - error/invalid-all-object.rst - error/invalid-bool-returned.rst - error/invalid-bytes-returned.rst - error/invalid-character-backspace.rst - error/invalid-character-carriage-return.rst - error/invalid-character-esc.rst - error/invalid-character-nul.rst - error/invalid-character-sub.rst - error/invalid-character-zero-width-space.rst - error/invalid-class-object.rst - error/invalid-enum-extension.rst - error/invalid-envvar-value.rst - error/invalid-format-returned.rst - error/invalid-getnewargs-ex-returned.rst - error/invalid-getnewargs-returned.rst - error/invalid-hash-returned.rst - error/invalid-index-returned.rst - error/invalid-length-hint-returned.rst - error/invalid-length-returned.rst - error/invalid-metaclass.rst - error/invalid-repr-returned.rst - error/invalid-sequence-index.rst - error/invalid-slice-index.rst - error/invalid-slots.rst - error/invalid-slots-object.rst - error/invalid-star-assignment-target.rst - error/invalid-str-returned.rst - error/invalid-unary-operand-type.rst - error/invalid-unicode-codec.rst - error/logging-format-truncated.rst - error/logging-too-few-args.rst - error/logging-too-many-args.rst - error/logging-unsupported-format.rst - error/method-hidden.rst - error/misplaced-bare-raise.rst - error/misplaced-format-function.rst - error/missing-format-string-key.rst - error/missing-kwoa.rst - error/mixed-format-string.rst - error/modified-iterating-dict.rst - error/modified-iterating-set.rst - error/no-member.rst - error/no-method-argument.rst - error/no-name-in-module.rst - error/no-self-argument.rst - error/no-value-for-parameter.rst - error/non-iterator-returned.rst - error/nonexistent-operator.rst - error/nonlocal-and-global.rst - error/nonlocal-without-binding.rst - error/not-a-mapping.rst - error/not-an-iterable.rst - error/not-async-context-manager.rst - error/not-callable.rst - error/not-context-manager.rst - error/not-in-loop.rst - error/notimplemented-raised.rst - error/potential-index-error.rst - error/raising-bad-type.rst - error/raising-non-exception.rst - error/redundant-keyword-arg.rst - error/relative-beyond-top-level.rst - error/repeated-keyword.rst - error/return-arg-in-generator.rst - error/return-in-init.rst - error/return-outside-function.rst - error/star-needs-assignment-target.rst - error/syntax-error.rst - error/too-few-format-args.rst - error/too-many-format-args.rst - error/too-many-function-args.rst - error/too-many-star-expressions.rst - error/truncated-format-string.rst - error/undefined-all-variable.rst - error/undefined-variable.rst - error/unexpected-keyword-arg.rst - error/unexpected-special-method-signature.rst - error/unhashable-dict-key.rst - error/unpacking-non-sequence.rst - error/unrecognized-inline-option.rst - error/unrecognized-option.rst - error/unsubscriptable-object.rst - error/unsupported-assignment-operation.rst - error/unsupported-binary-operation.rst - error/unsupported-delete-operation.rst - error/unsupported-membership-test.rst - error/used-before-assignment.rst - error/used-prior-global-declaration.rst - error/yield-inside-async-function.rst - error/yield-outside-function.rst - -All renamed messages in the error category: - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - error/bad-context-manager.rst - error/maybe-no-member.rst - error/old-non-iterator-returned-2.rst - error/old-unbalanced-tuple-unpacking.rst - - -Warning -------- - -All messages in the warning category: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - warning/abstract-method.rst - warning/anomalous-backslash-in-string.rst - warning/anomalous-unicode-escape-in-string.rst - warning/arguments-differ.rst - warning/arguments-out-of-order.rst - warning/arguments-renamed.rst - warning/assert-on-string-literal.rst - warning/assert-on-tuple.rst - warning/attribute-defined-outside-init.rst - warning/bad-builtin.rst - warning/bad-format-string.rst - warning/bad-format-string-key.rst - warning/bad-indentation.rst - warning/bad-open-mode.rst - warning/bad-staticmethod-argument.rst - warning/bad-thread-instantiation.rst - warning/bare-except.rst - warning/binary-op-exception.rst - warning/boolean-datetime.rst - warning/broad-except.rst - warning/cell-var-from-loop.rst - warning/comparison-with-callable.rst - warning/confusing-with-statement.rst - warning/consider-ternary-expression.rst - warning/dangerous-default-value.rst - warning/deprecated-argument.rst - warning/deprecated-class.rst - warning/deprecated-decorator.rst - warning/deprecated-method.rst - warning/deprecated-module.rst - warning/deprecated-typing-alias.rst - warning/differing-param-doc.rst - warning/differing-type-doc.rst - warning/duplicate-except.rst - warning/duplicate-key.rst - warning/duplicate-string-formatting-argument.rst - warning/duplicate-value.rst - warning/eq-without-hash.rst - warning/eval-used.rst - warning/exec-used.rst - warning/expression-not-assigned.rst - warning/f-string-without-interpolation.rst - warning/fixme.rst - warning/forgotten-debug-statement.rst - warning/format-combined-specification.rst - warning/format-string-without-interpolation.rst - warning/global-at-module-level.rst - warning/global-statement.rst - warning/global-variable-not-assigned.rst - warning/global-variable-undefined.rst - warning/implicit-str-concat.rst - warning/import-self.rst - warning/inconsistent-quotes.rst - warning/invalid-envvar-default.rst - warning/invalid-format-index.rst - warning/invalid-overridden-method.rst - warning/isinstance-second-argument-not-valid-type.rst - warning/keyword-arg-before-vararg.rst - warning/logging-format-interpolation.rst - warning/logging-fstring-interpolation.rst - warning/logging-not-lazy.rst - warning/lost-exception.rst - warning/method-cache-max-size-none.rst - warning/misplaced-future.rst - warning/missing-any-param-doc.rst - warning/missing-format-argument-key.rst - warning/missing-format-attribute.rst - warning/missing-param-doc.rst - warning/missing-parentheses-for-call-in-test.rst - warning/missing-raises-doc.rst - warning/missing-return-doc.rst - warning/missing-return-type-doc.rst - warning/missing-type-doc.rst - warning/missing-yield-doc.rst - warning/missing-yield-type-doc.rst - warning/modified-iterating-list.rst - warning/multiple-constructor-doc.rst - warning/nan-comparison.rst - warning/non-ascii-file-name.rst - warning/non-parent-init-called.rst - warning/non-str-assignment-to-dunder-name.rst - warning/overlapping-except.rst - warning/overridden-final-method.rst - warning/pointless-statement.rst - warning/pointless-string-statement.rst - warning/possibly-unused-variable.rst - warning/preferred-module.rst - warning/protected-access.rst - warning/raise-missing-from.rst - warning/raising-format-tuple.rst - warning/redeclared-assigned-name.rst - warning/redefined-builtin.rst - warning/redefined-loop-name.rst - warning/redefined-outer-name.rst - warning/redefined-slots-in-subclass.rst - warning/redundant-returns-doc.rst - warning/redundant-u-string-prefix.rst - warning/redundant-unittest-assert.rst - warning/redundant-yields-doc.rst - warning/reimported.rst - warning/self-assigning-variable.rst - warning/self-cls-assignment.rst - warning/shallow-copy-environ.rst - warning/signature-differs.rst - warning/subclassed-final-class.rst - warning/subprocess-popen-preexec-fn.rst - warning/subprocess-run-check.rst - warning/super-init-not-called.rst - warning/super-without-brackets.rst - warning/too-many-try-statements.rst - warning/try-except-raise.rst - warning/unbalanced-tuple-unpacking.rst - warning/undefined-loop-variable.rst - warning/unnecessary-ellipsis.rst - warning/unnecessary-lambda.rst - warning/unnecessary-pass.rst - warning/unnecessary-semicolon.rst - warning/unreachable.rst - warning/unspecified-encoding.rst - warning/unused-argument.rst - warning/unused-format-string-argument.rst - warning/unused-format-string-key.rst - warning/unused-import.rst - warning/unused-private-member.rst - warning/unused-variable.rst - warning/unused-wildcard-import.rst - warning/useless-else-on-loop.rst - warning/useless-param-doc.rst - warning/useless-super-delegation.rst - warning/useless-type-doc.rst - warning/useless-with-lock.rst - warning/using-constant-test.rst - warning/using-f-string-in-unsupported-version.rst - warning/using-final-decorator-in-unsupported-version.rst - warning/while-used.rst - warning/wildcard-import.rst - warning/wrong-exception-operation.rst - -All renamed messages in the warning category: - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - warning/cache-max-size-none.rst - warning/implicit-str-concat-in-sequence.rst - warning/lru-cache-decorating-method.rst - warning/old-assignment-from-none.rst - warning/old-empty-docstring.rst - warning/old-missing-param-doc.rst - warning/old-missing-returns-doc.rst - warning/old-missing-type-doc.rst - warning/old-missing-yields-doc.rst - warning/old-non-iterator-returned-1.rst - warning/old-unidiomatic-typecheck.rst - warning/old-unpacking-non-sequence.rst - - -Convention ----------- - -All messages in the convention category: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - convention/bad-classmethod-argument.rst - convention/bad-docstring-quotes.rst - convention/bad-file-encoding.rst - convention/bad-mcs-classmethod-argument.rst - convention/bad-mcs-method-argument.rst - convention/compare-to-empty-string.rst - convention/compare-to-zero.rst - convention/consider-iterating-dictionary.rst - convention/consider-using-any-or-all.rst - convention/consider-using-dict-items.rst - convention/consider-using-enumerate.rst - convention/consider-using-f-string.rst - convention/disallowed-name.rst - convention/docstring-first-line-empty.rst - convention/empty-docstring.rst - convention/import-outside-toplevel.rst - convention/import-private-name.rst - convention/invalid-characters-in-docstring.rst - convention/invalid-name.rst - convention/line-too-long.rst - convention/misplaced-comparison-constant.rst - convention/missing-class-docstring.rst - convention/missing-final-newline.rst - convention/missing-function-docstring.rst - convention/missing-module-docstring.rst - convention/mixed-line-endings.rst - convention/multiple-imports.rst - convention/multiple-statements.rst - convention/non-ascii-module-import.rst - convention/non-ascii-name.rst - convention/single-string-used-for-slots.rst - convention/singleton-comparison.rst - convention/superfluous-parens.rst - convention/too-many-lines.rst - convention/trailing-newlines.rst - convention/trailing-whitespace.rst - convention/typevar-double-variance.rst - convention/typevar-name-incorrect-variance.rst - convention/typevar-name-mismatch.rst - convention/unexpected-line-ending-format.rst - convention/ungrouped-imports.rst - convention/unidiomatic-typecheck.rst - convention/unnecessary-direct-lambda-call.rst - convention/unnecessary-dunder-call.rst - convention/unnecessary-lambda-assignment.rst - convention/unneeded-not.rst - convention/use-implicit-booleaness-not-comparison.rst - convention/use-implicit-booleaness-not-len.rst - convention/use-maxsplit-arg.rst - convention/use-sequence-for-iteration.rst - convention/useless-import-alias.rst - convention/wrong-import-order.rst - convention/wrong-import-position.rst - convention/wrong-spelling-in-comment.rst - convention/wrong-spelling-in-docstring.rst - -All renamed messages in the convention category: - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - convention/blacklisted-name.rst - convention/len-as-condition.rst - convention/missing-docstring.rst - convention/old-misplaced-comparison-constant.rst - convention/old-non-ascii-name.rst - - -Refactor --------- - -All messages in the refactor category: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - refactor/chained-comparison.rst - refactor/comparison-of-constants.rst - refactor/comparison-with-itself.rst - refactor/condition-evals-to-constant.rst - refactor/confusing-consecutive-elif.rst - refactor/consider-alternative-union-syntax.rst - refactor/consider-merging-isinstance.rst - refactor/consider-swap-variables.rst - refactor/consider-using-alias.rst - refactor/consider-using-assignment-expr.rst - refactor/consider-using-dict-comprehension.rst - refactor/consider-using-from-import.rst - refactor/consider-using-generator.rst - refactor/consider-using-get.rst - refactor/consider-using-in.rst - refactor/consider-using-join.rst - refactor/consider-using-max-builtin.rst - refactor/consider-using-min-builtin.rst - refactor/consider-using-namedtuple-or-dataclass.rst - refactor/consider-using-set-comprehension.rst - refactor/consider-using-sys-exit.rst - refactor/consider-using-ternary.rst - refactor/consider-using-tuple.rst - refactor/consider-using-with.rst - refactor/cyclic-import.rst - refactor/duplicate-code.rst - refactor/else-if-used.rst - refactor/empty-comment.rst - refactor/inconsistent-return-statements.rst - refactor/literal-comparison.rst - refactor/no-classmethod-decorator.rst - refactor/no-else-break.rst - refactor/no-else-continue.rst - refactor/no-else-raise.rst - refactor/no-else-return.rst - refactor/no-self-use.rst - refactor/no-staticmethod-decorator.rst - refactor/property-with-parameters.rst - refactor/redefined-argument-from-local.rst - refactor/redefined-variable-type.rst - refactor/simplifiable-condition.rst - refactor/simplifiable-if-expression.rst - refactor/simplifiable-if-statement.rst - refactor/simplify-boolean-expression.rst - refactor/stop-iteration-return.rst - refactor/super-with-arguments.rst - refactor/too-complex.rst - refactor/too-few-public-methods.rst - refactor/too-many-ancestors.rst - refactor/too-many-arguments.rst - refactor/too-many-boolean-expressions.rst - refactor/too-many-branches.rst - refactor/too-many-instance-attributes.rst - refactor/too-many-locals.rst - refactor/too-many-nested-blocks.rst - refactor/too-many-public-methods.rst - refactor/too-many-return-statements.rst - refactor/too-many-statements.rst - refactor/trailing-comma-tuple.rst - refactor/unnecessary-comprehension.rst - refactor/unnecessary-dict-index-lookup.rst - refactor/unnecessary-list-index-lookup.rst - refactor/use-a-generator.rst - refactor/use-dict-literal.rst - refactor/use-list-literal.rst - refactor/use-set-for-membership.rst - refactor/useless-object-inheritance.rst - refactor/useless-return.rst - -All renamed messages in the refactor category: - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - refactor/old-no-self-use.rst - refactor/old-simplifiable-if-statement.rst - refactor/old-too-many-nested-blocks.rst - - -Information ------------ - -All messages in the information category: - -.. toctree:: - :maxdepth: 2 - :titlesonly: - - information/bad-inline-option.rst - information/c-extension-no-member.rst - information/deprecated-pragma.rst - information/file-ignored.rst - information/locally-disabled.rst - information/raw-checker-failed.rst - information/suppressed-message.rst - information/use-symbolic-message-instead.rst - information/useless-suppression.rst - -All renamed messages in the information category: - -.. toctree:: - :maxdepth: 1 - :titlesonly: - - information/deprecated-disable-all.rst diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst index 84947b530..739a22fa5 100644 --- a/doc/user_guide/index.rst +++ b/doc/user_guide/index.rst @@ -9,7 +9,7 @@ User Guide installation run output - message-control + messages/index options ide_integration/ide-integration pre-commit-integration diff --git a/doc/user_guide/message-control.rst b/doc/user_guide/message-control.rst deleted file mode 100644 index 0f735e533..000000000 --- a/doc/user_guide/message-control.rst +++ /dev/null @@ -1,205 +0,0 @@ -.. _message-control: - -Messages control -================ - -``pylint`` has an advanced message control for its checks, offering the ability -to enable / disable a message either from the command line or from the configuration -file, as well as from the code itself. - -For all of these controls, ``pylint`` accepts the following values: - -* a symbolic message: ``no-member``, ``undefined-variable`` etc. - -* a numerical ID: ``E1101``, ``E1102`` etc. - -* The name of the group of checks. You can grab those with ``pylint --list-groups``. - For example, you can disable / enable all the checks related to type checking, with - ``typecheck`` or all the checks related to variables with ``variables`` - -* Corresponding category of the checks - - * ``C`` convention related checks - * ``R`` refactoring related checks - * ``W`` various warnings - * ``E`` errors, for probable bugs in the code - * ``F`` fatal, if an error occurred which prevented ``pylint`` from doing further processing. - -* All the checks with ``all`` - - -Block disables --------------- - -This describes how the pragma controls operate at a code level. - -The pragma controls can disable / enable: - -* All the violations on a single line - - .. sourcecode:: python - - a, b = ... # pylint: disable=unbalanced-tuple-unpacking - -* All the violations on the following line - - .. sourcecode:: python - - # pylint: disable-next=unbalanced-tuple-unpacking - a, b = ... - -* All the violations in a single scope - - .. sourcecode:: python - - def test(): - # Disable all the no-member violations in this function - # pylint: disable=no-member - ... - -* All the violations in a `block`. For instance, each separate branch of an - ``if`` statement is considered a separate block, as in the following example: - - .. sourcecode:: python - - def meth5(self): - # pylint: disable=no-member - # no error - print(self.bla) - if self.blop: - # pylint: enable=no-member - # enable all no-members for this block - print(self.blip) - else: - # This is affected by the scope disable - print(self.blip) - # pylint: enable=no-member - print(self.blip) - if self.blop: - # pylint: disable=no-member - # disable all no-members for this block - print(self.blip) - else: - # This emits a violation - print(self.blip) - - -* If the violation occurs on a block starting line, then it applies only to that line - - .. sourcecode:: python - - if self.blop: # pylint: disable=no-member; applies only to this line - # Here we get an error - print(self.blip) - else: - # error - print(self.blip) - - - -Here's an example with all these rules in a single place: - -.. sourcecode:: python - - """pylint option block-disable""" - - __revision__ = None - - class Foo(object): - """block-disable test""" - - def __init__(self): - pass - - def meth1(self, arg): - """this issues a message""" - print(self) - - def meth2(self, arg): - """and this one not""" - # pylint: disable=unused-argument - print(self\ - + "foo") - - def meth3(self): - """test one line disabling""" - # no error - print(self.bla) # pylint: disable=no-member - # error - print(self.blop) - - def meth4(self): - """test re-enabling""" - # pylint: disable=no-member - # no error - print(self.bla) - print(self.blop) - # pylint: enable=no-member - # error - print(self.blip) - - def meth5(self): - """test IF sub-block re-enabling""" - # pylint: disable=no-member - # no error - print(self.bla) - if self.blop: - # pylint: enable=no-member - # error - print(self.blip) - else: - # no error - print(self.blip) - # no error - print(self.blip) - - def meth6(self): - """test TRY/EXCEPT sub-block re-enabling""" - # pylint: disable=no-member - # no error - print(self.bla) - try: - # pylint: enable=no-member - # error - print(self.blip) - except UndefinedName: # pylint: disable=undefined-variable - # no error - print(self.blip) - # no error - print(self.blip) - - def meth7(self): - """test one line block opening disabling""" - if self.blop: # pylint: disable=no-member - # error - print(self.blip) - else: - # error - print(self.blip) - # error - print(self.blip) - - def meth8(self): - """test late disabling""" - # error - print(self.blip) - # pylint: disable=no-member - # no error - print(self.bla) - print(self.blop) - - def meth9(self): - """test next line disabling""" - # no error - # pylint: disable-next=no-member - print(self.bla) - # error - print(self.blop) - - -Detecting useless disables --------------------------- - -As pylint gets better and false positives are removed, -disables that became useless can accumulate and clutter the code. -In order to clean them you can enable the ``useless-suppression`` warning. diff --git a/doc/user_guide/messages/index.rst b/doc/user_guide/messages/index.rst new file mode 100644 index 000000000..f21efb539 --- /dev/null +++ b/doc/user_guide/messages/index.rst @@ -0,0 +1,34 @@ +.. _messages: + +######## +Messages +######## + +.. toctree:: + :maxdepth: 2 + :hidden: + + + messages_list.rst + message-control.rst + +Pylint can emit various messages. These are categorized according +to categories corresponding to bit-encoded exit codes: + +* :ref:`Fatal` (1) +* :ref:`Error` (2) +* :ref:`Warning` (4) +* :ref:`Convention` (8) +* :ref:`Refactor` (16) +* :ref:`Information` (NA) + +A list of these messages can be found in :ref:`messages-list` + +Disabling messages +================== + +``pylint`` has an advanced message control for its checks, offering the ability +to enable / disable a message either from the command line or from the configuration +file, as well as from the code itself. + +For more detail see :ref:`message-control` diff --git a/doc/user_guide/messages/message-control.rst b/doc/user_guide/messages/message-control.rst new file mode 100644 index 000000000..4ac6cec4b --- /dev/null +++ b/doc/user_guide/messages/message-control.rst @@ -0,0 +1,201 @@ +.. _message-control: + +Messages control +================ + +In order to control messages, ``pylint`` accepts the following values: + +* a symbolic message: ``no-member``, ``undefined-variable`` etc. + +* a numerical ID: ``E1101``, ``E1102`` etc. + +* The name of the group of checks. You can grab those with ``pylint --list-groups``. + For example, you can disable / enable all the checks related to type checking, with + ``typecheck`` or all the checks related to variables with ``variables`` + +* Corresponding category of the checks + + * ``C`` convention related checks + * ``R`` refactoring related checks + * ``W`` various warnings + * ``E`` errors, for probable bugs in the code + * ``F`` fatal, if an error occurred which prevented ``pylint`` from doing further processing. + +* All the checks with ``all`` + + +Block disables +-------------- + +This describes how the pragma controls operate at a code level. + +The pragma controls can disable / enable: + +* All the violations on a single line + + .. sourcecode:: python + + a, b = ... # pylint: disable=unbalanced-tuple-unpacking + +* All the violations on the following line + + .. sourcecode:: python + + # pylint: disable-next=unbalanced-tuple-unpacking + a, b = ... + +* All the violations in a single scope + + .. sourcecode:: python + + def test(): + # Disable all the no-member violations in this function + # pylint: disable=no-member + ... + +* All the violations in a `block`. For instance, each separate branch of an + ``if`` statement is considered a separate block, as in the following example: + + .. sourcecode:: python + + def meth5(self): + # pylint: disable=no-member + # no error + print(self.bla) + if self.blop: + # pylint: enable=no-member + # enable all no-members for this block + print(self.blip) + else: + # This is affected by the scope disable + print(self.blip) + # pylint: enable=no-member + print(self.blip) + if self.blop: + # pylint: disable=no-member + # disable all no-members for this block + print(self.blip) + else: + # This emits a violation + print(self.blip) + + +* If the violation occurs on a block starting line, then it applies only to that line + + .. sourcecode:: python + + if self.blop: # pylint: disable=no-member; applies only to this line + # Here we get an error + print(self.blip) + else: + # error + print(self.blip) + + + +Here's an example with all these rules in a single place: + +.. sourcecode:: python + + """pylint option block-disable""" + + __revision__ = None + + class Foo(object): + """block-disable test""" + + def __init__(self): + pass + + def meth1(self, arg): + """this issues a message""" + print(self) + + def meth2(self, arg): + """and this one not""" + # pylint: disable=unused-argument + print(self\ + + "foo") + + def meth3(self): + """test one line disabling""" + # no error + print(self.bla) # pylint: disable=no-member + # error + print(self.blop) + + def meth4(self): + """test re-enabling""" + # pylint: disable=no-member + # no error + print(self.bla) + print(self.blop) + # pylint: enable=no-member + # error + print(self.blip) + + def meth5(self): + """test IF sub-block re-enabling""" + # pylint: disable=no-member + # no error + print(self.bla) + if self.blop: + # pylint: enable=no-member + # error + print(self.blip) + else: + # no error + print(self.blip) + # no error + print(self.blip) + + def meth6(self): + """test TRY/EXCEPT sub-block re-enabling""" + # pylint: disable=no-member + # no error + print(self.bla) + try: + # pylint: enable=no-member + # error + print(self.blip) + except UndefinedName: # pylint: disable=undefined-variable + # no error + print(self.blip) + # no error + print(self.blip) + + def meth7(self): + """test one line block opening disabling""" + if self.blop: # pylint: disable=no-member + # error + print(self.blip) + else: + # error + print(self.blip) + # error + print(self.blip) + + def meth8(self): + """test late disabling""" + # error + print(self.blip) + # pylint: disable=no-member + # no error + print(self.bla) + print(self.blop) + + def meth9(self): + """test next line disabling""" + # no error + # pylint: disable-next=no-member + print(self.bla) + # error + print(self.blop) + + +Detecting useless disables +-------------------------- + +As pylint gets better and false positives are removed, +disables that became useless can accumulate and clutter the code. +In order to clean them you can enable the ``useless-suppression`` warning. diff --git a/doc/user_guide/messages/messages_list.rst b/doc/user_guide/messages/messages_list.rst new file mode 100644 index 000000000..c7674dcb7 --- /dev/null +++ b/doc/user_guide/messages/messages_list.rst @@ -0,0 +1,539 @@ +.. _messages-list: + +Overview of all Pylint messages +=============================== + +.. + NOTE This file is auto-generated. Make any changes to the associated + docs extension in 'pylint_messages.py'. + +Pylint can emit the following messages: + +Fatal +----- + +All messages in the fatal category: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + fatal/astroid-error.rst + fatal/config-parse-error.rst + fatal/fatal.rst + fatal/method-check-failed.rst + fatal/parse-error.rst + +All renamed messages in the fatal category: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + fatal/old-import-error.rst + + +Error +----- + +All messages in the error category: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + error/abstract-class-instantiated.rst + error/access-member-before-definition.rst + error/assigning-non-slot.rst + error/assignment-from-no-return.rst + error/assignment-from-none.rst + error/await-outside-async.rst + error/bad-configuration-section.rst + error/bad-except-order.rst + error/bad-exception-context.rst + error/bad-format-character.rst + error/bad-option-value.rst + error/bad-plugin-value.rst + error/bad-reversed-sequence.rst + error/bad-str-strip-call.rst + error/bad-string-format-type.rst + error/bad-super-call.rst + error/bidirectional-unicode.rst + error/broken-collections-callable.rst + error/broken-noreturn.rst + error/catching-non-exception.rst + error/class-variable-slots-conflict.rst + error/continue-in-finally.rst + error/dict-iter-missing-items.rst + error/duplicate-argument-name.rst + error/duplicate-bases.rst + error/format-needs-mapping.rst + error/function-redefined.rst + error/import-error.rst + error/inconsistent-mro.rst + error/inherit-non-class.rst + error/init-is-generator.rst + error/invalid-all-format.rst + error/invalid-all-object.rst + error/invalid-bool-returned.rst + error/invalid-bytes-returned.rst + error/invalid-character-backspace.rst + error/invalid-character-carriage-return.rst + error/invalid-character-esc.rst + error/invalid-character-nul.rst + error/invalid-character-sub.rst + error/invalid-character-zero-width-space.rst + error/invalid-class-object.rst + error/invalid-enum-extension.rst + error/invalid-envvar-value.rst + error/invalid-format-returned.rst + error/invalid-getnewargs-ex-returned.rst + error/invalid-getnewargs-returned.rst + error/invalid-hash-returned.rst + error/invalid-index-returned.rst + error/invalid-length-hint-returned.rst + error/invalid-length-returned.rst + error/invalid-metaclass.rst + error/invalid-repr-returned.rst + error/invalid-sequence-index.rst + error/invalid-slice-index.rst + error/invalid-slots.rst + error/invalid-slots-object.rst + error/invalid-star-assignment-target.rst + error/invalid-str-returned.rst + error/invalid-unary-operand-type.rst + error/invalid-unicode-codec.rst + error/logging-format-truncated.rst + error/logging-too-few-args.rst + error/logging-too-many-args.rst + error/logging-unsupported-format.rst + error/method-hidden.rst + error/misplaced-bare-raise.rst + error/misplaced-format-function.rst + error/missing-format-string-key.rst + error/missing-kwoa.rst + error/mixed-format-string.rst + error/modified-iterating-dict.rst + error/modified-iterating-set.rst + error/no-member.rst + error/no-method-argument.rst + error/no-name-in-module.rst + error/no-self-argument.rst + error/no-value-for-parameter.rst + error/non-iterator-returned.rst + error/nonexistent-operator.rst + error/nonlocal-and-global.rst + error/nonlocal-without-binding.rst + error/not-a-mapping.rst + error/not-an-iterable.rst + error/not-async-context-manager.rst + error/not-callable.rst + error/not-context-manager.rst + error/not-in-loop.rst + error/notimplemented-raised.rst + error/potential-index-error.rst + error/raising-bad-type.rst + error/raising-non-exception.rst + error/redundant-keyword-arg.rst + error/relative-beyond-top-level.rst + error/repeated-keyword.rst + error/return-arg-in-generator.rst + error/return-in-init.rst + error/return-outside-function.rst + error/star-needs-assignment-target.rst + error/syntax-error.rst + error/too-few-format-args.rst + error/too-many-format-args.rst + error/too-many-function-args.rst + error/too-many-star-expressions.rst + error/truncated-format-string.rst + error/undefined-all-variable.rst + error/undefined-variable.rst + error/unexpected-keyword-arg.rst + error/unexpected-special-method-signature.rst + error/unhashable-dict-key.rst + error/unpacking-non-sequence.rst + error/unrecognized-inline-option.rst + error/unrecognized-option.rst + error/unsubscriptable-object.rst + error/unsupported-assignment-operation.rst + error/unsupported-binary-operation.rst + error/unsupported-delete-operation.rst + error/unsupported-membership-test.rst + error/used-before-assignment.rst + error/used-prior-global-declaration.rst + error/yield-inside-async-function.rst + error/yield-outside-function.rst + +All renamed messages in the error category: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + error/bad-context-manager.rst + error/maybe-no-member.rst + error/old-non-iterator-returned-2.rst + error/old-unbalanced-tuple-unpacking.rst + + +Warning +------- + +All messages in the warning category: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + warning/abstract-method.rst + warning/anomalous-backslash-in-string.rst + warning/anomalous-unicode-escape-in-string.rst + warning/arguments-differ.rst + warning/arguments-out-of-order.rst + warning/arguments-renamed.rst + warning/assert-on-string-literal.rst + warning/assert-on-tuple.rst + warning/attribute-defined-outside-init.rst + warning/bad-builtin.rst + warning/bad-format-string.rst + warning/bad-format-string-key.rst + warning/bad-indentation.rst + warning/bad-open-mode.rst + warning/bad-staticmethod-argument.rst + warning/bad-thread-instantiation.rst + warning/bare-except.rst + warning/binary-op-exception.rst + warning/boolean-datetime.rst + warning/broad-except.rst + warning/cell-var-from-loop.rst + warning/comparison-with-callable.rst + warning/confusing-with-statement.rst + warning/consider-ternary-expression.rst + warning/dangerous-default-value.rst + warning/deprecated-argument.rst + warning/deprecated-class.rst + warning/deprecated-decorator.rst + warning/deprecated-method.rst + warning/deprecated-module.rst + warning/deprecated-typing-alias.rst + warning/differing-param-doc.rst + warning/differing-type-doc.rst + warning/duplicate-except.rst + warning/duplicate-key.rst + warning/duplicate-string-formatting-argument.rst + warning/duplicate-value.rst + warning/eq-without-hash.rst + warning/eval-used.rst + warning/exec-used.rst + warning/expression-not-assigned.rst + warning/f-string-without-interpolation.rst + warning/fixme.rst + warning/forgotten-debug-statement.rst + warning/format-combined-specification.rst + warning/format-string-without-interpolation.rst + warning/global-at-module-level.rst + warning/global-statement.rst + warning/global-variable-not-assigned.rst + warning/global-variable-undefined.rst + warning/implicit-str-concat.rst + warning/import-self.rst + warning/inconsistent-quotes.rst + warning/invalid-envvar-default.rst + warning/invalid-format-index.rst + warning/invalid-overridden-method.rst + warning/isinstance-second-argument-not-valid-type.rst + warning/keyword-arg-before-vararg.rst + warning/logging-format-interpolation.rst + warning/logging-fstring-interpolation.rst + warning/logging-not-lazy.rst + warning/lost-exception.rst + warning/method-cache-max-size-none.rst + warning/misplaced-future.rst + warning/missing-any-param-doc.rst + warning/missing-format-argument-key.rst + warning/missing-format-attribute.rst + warning/missing-param-doc.rst + warning/missing-parentheses-for-call-in-test.rst + warning/missing-raises-doc.rst + warning/missing-return-doc.rst + warning/missing-return-type-doc.rst + warning/missing-type-doc.rst + warning/missing-yield-doc.rst + warning/missing-yield-type-doc.rst + warning/modified-iterating-list.rst + warning/multiple-constructor-doc.rst + warning/nan-comparison.rst + warning/non-ascii-file-name.rst + warning/non-parent-init-called.rst + warning/non-str-assignment-to-dunder-name.rst + warning/overlapping-except.rst + warning/overridden-final-method.rst + warning/pointless-statement.rst + warning/pointless-string-statement.rst + warning/possibly-unused-variable.rst + warning/preferred-module.rst + warning/protected-access.rst + warning/raise-missing-from.rst + warning/raising-format-tuple.rst + warning/redeclared-assigned-name.rst + warning/redefined-builtin.rst + warning/redefined-loop-name.rst + warning/redefined-outer-name.rst + warning/redefined-slots-in-subclass.rst + warning/redundant-returns-doc.rst + warning/redundant-u-string-prefix.rst + warning/redundant-unittest-assert.rst + warning/redundant-yields-doc.rst + warning/reimported.rst + warning/self-assigning-variable.rst + warning/self-cls-assignment.rst + warning/shallow-copy-environ.rst + warning/signature-differs.rst + warning/subclassed-final-class.rst + warning/subprocess-popen-preexec-fn.rst + warning/subprocess-run-check.rst + warning/super-init-not-called.rst + warning/super-without-brackets.rst + warning/too-many-try-statements.rst + warning/try-except-raise.rst + warning/unbalanced-tuple-unpacking.rst + warning/undefined-loop-variable.rst + warning/unnecessary-ellipsis.rst + warning/unnecessary-lambda.rst + warning/unnecessary-pass.rst + warning/unnecessary-semicolon.rst + warning/unreachable.rst + warning/unspecified-encoding.rst + warning/unused-argument.rst + warning/unused-format-string-argument.rst + warning/unused-format-string-key.rst + warning/unused-import.rst + warning/unused-private-member.rst + warning/unused-variable.rst + warning/unused-wildcard-import.rst + warning/useless-else-on-loop.rst + warning/useless-param-doc.rst + warning/useless-super-delegation.rst + warning/useless-type-doc.rst + warning/useless-with-lock.rst + warning/using-constant-test.rst + warning/using-f-string-in-unsupported-version.rst + warning/using-final-decorator-in-unsupported-version.rst + warning/while-used.rst + warning/wildcard-import.rst + warning/wrong-exception-operation.rst + +All renamed messages in the warning category: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + warning/cache-max-size-none.rst + warning/implicit-str-concat-in-sequence.rst + warning/lru-cache-decorating-method.rst + warning/old-assignment-from-none.rst + warning/old-empty-docstring.rst + warning/old-missing-param-doc.rst + warning/old-missing-returns-doc.rst + warning/old-missing-type-doc.rst + warning/old-missing-yields-doc.rst + warning/old-non-iterator-returned-1.rst + warning/old-unidiomatic-typecheck.rst + warning/old-unpacking-non-sequence.rst + + +Convention +---------- + +All messages in the convention category: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + convention/bad-classmethod-argument.rst + convention/bad-docstring-quotes.rst + convention/bad-file-encoding.rst + convention/bad-mcs-classmethod-argument.rst + convention/bad-mcs-method-argument.rst + convention/compare-to-empty-string.rst + convention/compare-to-zero.rst + convention/consider-iterating-dictionary.rst + convention/consider-using-any-or-all.rst + convention/consider-using-dict-items.rst + convention/consider-using-enumerate.rst + convention/consider-using-f-string.rst + convention/disallowed-name.rst + convention/docstring-first-line-empty.rst + convention/empty-docstring.rst + convention/import-outside-toplevel.rst + convention/import-private-name.rst + convention/invalid-characters-in-docstring.rst + convention/invalid-name.rst + convention/line-too-long.rst + convention/misplaced-comparison-constant.rst + convention/missing-class-docstring.rst + convention/missing-final-newline.rst + convention/missing-function-docstring.rst + convention/missing-module-docstring.rst + convention/mixed-line-endings.rst + convention/multiple-imports.rst + convention/multiple-statements.rst + convention/non-ascii-module-import.rst + convention/non-ascii-name.rst + convention/single-string-used-for-slots.rst + convention/singleton-comparison.rst + convention/superfluous-parens.rst + convention/too-many-lines.rst + convention/trailing-newlines.rst + convention/trailing-whitespace.rst + convention/typevar-double-variance.rst + convention/typevar-name-incorrect-variance.rst + convention/typevar-name-mismatch.rst + convention/unexpected-line-ending-format.rst + convention/ungrouped-imports.rst + convention/unidiomatic-typecheck.rst + convention/unnecessary-direct-lambda-call.rst + convention/unnecessary-dunder-call.rst + convention/unnecessary-lambda-assignment.rst + convention/unneeded-not.rst + convention/use-implicit-booleaness-not-comparison.rst + convention/use-implicit-booleaness-not-len.rst + convention/use-maxsplit-arg.rst + convention/use-sequence-for-iteration.rst + convention/useless-import-alias.rst + convention/wrong-import-order.rst + convention/wrong-import-position.rst + convention/wrong-spelling-in-comment.rst + convention/wrong-spelling-in-docstring.rst + +All renamed messages in the convention category: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + convention/blacklisted-name.rst + convention/len-as-condition.rst + convention/missing-docstring.rst + convention/old-misplaced-comparison-constant.rst + convention/old-non-ascii-name.rst + + +Refactor +-------- + +All messages in the refactor category: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + refactor/chained-comparison.rst + refactor/comparison-of-constants.rst + refactor/comparison-with-itself.rst + refactor/condition-evals-to-constant.rst + refactor/confusing-consecutive-elif.rst + refactor/consider-alternative-union-syntax.rst + refactor/consider-merging-isinstance.rst + refactor/consider-swap-variables.rst + refactor/consider-using-alias.rst + refactor/consider-using-assignment-expr.rst + refactor/consider-using-dict-comprehension.rst + refactor/consider-using-from-import.rst + refactor/consider-using-generator.rst + refactor/consider-using-get.rst + refactor/consider-using-in.rst + refactor/consider-using-join.rst + refactor/consider-using-max-builtin.rst + refactor/consider-using-min-builtin.rst + refactor/consider-using-namedtuple-or-dataclass.rst + refactor/consider-using-set-comprehension.rst + refactor/consider-using-sys-exit.rst + refactor/consider-using-ternary.rst + refactor/consider-using-tuple.rst + refactor/consider-using-with.rst + refactor/cyclic-import.rst + refactor/duplicate-code.rst + refactor/else-if-used.rst + refactor/empty-comment.rst + refactor/inconsistent-return-statements.rst + refactor/literal-comparison.rst + refactor/no-classmethod-decorator.rst + refactor/no-else-break.rst + refactor/no-else-continue.rst + refactor/no-else-raise.rst + refactor/no-else-return.rst + refactor/no-self-use.rst + refactor/no-staticmethod-decorator.rst + refactor/property-with-parameters.rst + refactor/redefined-argument-from-local.rst + refactor/redefined-variable-type.rst + refactor/simplifiable-condition.rst + refactor/simplifiable-if-expression.rst + refactor/simplifiable-if-statement.rst + refactor/simplify-boolean-expression.rst + refactor/stop-iteration-return.rst + refactor/super-with-arguments.rst + refactor/too-complex.rst + refactor/too-few-public-methods.rst + refactor/too-many-ancestors.rst + refactor/too-many-arguments.rst + refactor/too-many-boolean-expressions.rst + refactor/too-many-branches.rst + refactor/too-many-instance-attributes.rst + refactor/too-many-locals.rst + refactor/too-many-nested-blocks.rst + refactor/too-many-public-methods.rst + refactor/too-many-return-statements.rst + refactor/too-many-statements.rst + refactor/trailing-comma-tuple.rst + refactor/unnecessary-comprehension.rst + refactor/unnecessary-dict-index-lookup.rst + refactor/unnecessary-list-index-lookup.rst + refactor/use-a-generator.rst + refactor/use-dict-literal.rst + refactor/use-list-literal.rst + refactor/use-set-for-membership.rst + refactor/useless-object-inheritance.rst + refactor/useless-return.rst + +All renamed messages in the refactor category: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + refactor/old-no-self-use.rst + refactor/old-simplifiable-if-statement.rst + refactor/old-too-many-nested-blocks.rst + + +Information +----------- + +All messages in the information category: + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + information/bad-inline-option.rst + information/c-extension-no-member.rst + information/deprecated-pragma.rst + information/file-ignored.rst + information/locally-disabled.rst + information/raw-checker-failed.rst + information/suppressed-message.rst + information/use-symbolic-message-instead.rst + information/useless-suppression.rst + +All renamed messages in the information category: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + information/deprecated-disable-all.rst -- cgit v1.2.1