From b05cf87ac0c35220f3ff991cba3d0cde4c9a308a Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Wed, 17 Sep 2025 22:19:17 +0200 Subject: [PATCH] [script] Add :ref: automatically in the documentation --- .pre-commit-config.yaml | 11 + .../u/useless-parent-delegation/related.rst | 2 +- doc/user_guide/checkers/features.rst | 8 +- doc/whatsnew/0/0.x.rst | 2 +- doc/whatsnew/1/1.0.rst | 18 +- doc/whatsnew/1/1.1.rst | 18 +- doc/whatsnew/1/1.2.rst | 30 +- doc/whatsnew/1/1.3.rst | 36 +- doc/whatsnew/1/1.4.rst | 78 ++-- doc/whatsnew/1/1.5.rst | 152 +++---- doc/whatsnew/1/1.6/full.rst | 18 +- doc/whatsnew/1/1.6/summary.rst | 6 +- doc/whatsnew/1/1.7/full.rst | 64 +-- doc/whatsnew/1/1.7/summary.rst | 18 +- doc/whatsnew/1/1.8/full.rst | 10 +- doc/whatsnew/1/1.8/summary.rst | 4 +- doc/whatsnew/2/2.0/full.rst | 24 +- doc/whatsnew/2/2.0/summary.rst | 6 +- doc/whatsnew/2/2.1/full.rst | 2 +- doc/whatsnew/2/2.10/full.rst | 2 +- doc/whatsnew/2/2.11/full.rst | 2 +- doc/whatsnew/2/2.13/full.rst | 2 +- doc/whatsnew/2/2.13/summary.rst | 2 +- doc/whatsnew/2/2.14/full.rst | 2 +- doc/whatsnew/2/2.15/index.rst | 2 +- doc/whatsnew/2/2.16/index.rst | 6 +- doc/whatsnew/2/2.17/index.rst | 6 +- doc/whatsnew/2/2.3/full.rst | 4 +- doc/whatsnew/2/2.4/full.rst | 6 +- doc/whatsnew/2/2.5/full.rst | 26 +- doc/whatsnew/2/2.6/full.rst | 2 +- doc/whatsnew/2/2.6/summary.rst | 2 +- doc/whatsnew/2/2.9/full.rst | 4 +- doc/whatsnew/3/3.0/index.rst | 12 +- doc/whatsnew/3/3.1/index.rst | 4 +- doc/whatsnew/3/3.2/index.rst | 2 +- doc/whatsnew/3/3.3/index.rst | 2 +- script/check_message_references.py | 388 ++++++++++++++++++ 38 files changed, 691 insertions(+), 292 deletions(-) create mode 100644 script/check_message_references.py diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 6e36bf4c0b..e4fdcb609e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -122,6 +122,17 @@ repos: types: [text] files: ^(doc/whatsnew/fragments) exclude: doc/whatsnew/fragments/_.*.rst + - id: check-message-references + name: Check pylint message references + entry: python script/check_message_references.py + language: system + args: ["--fix"] + types_or: [python, rst, markdown, text] + files: ^doc/(whatsnew|data/messages)/.*\.rst$ + exclude: + \.( doc/development_guide/api/pylint.rst| + doc/development_guide/how_tos/custom_checkers.rst| )$ + pass_filenames: true - repo: https://github.com/rstcheck/rstcheck rev: "v6.2.5" hooks: diff --git a/doc/data/messages/u/useless-parent-delegation/related.rst b/doc/data/messages/u/useless-parent-delegation/related.rst index 1f356c13a4..3adb3c5d47 100644 --- a/doc/data/messages/u/useless-parent-delegation/related.rst +++ b/doc/data/messages/u/useless-parent-delegation/related.rst @@ -1 +1 @@ -- `Stackoverflow explanation for 'useless-super-delegation' `_ +- `Stackoverflow explanation for ':ref:`useless-super-delegation`' `_ diff --git a/doc/user_guide/checkers/features.rst b/doc/user_guide/checkers/features.rst index 5040bf68e5..b4879c1636 100644 --- a/doc/user_guide/checkers/features.rst +++ b/doc/user_guide/checkers/features.rst @@ -689,11 +689,11 @@ Match Statements checker Messages :invalid-match-args-definition (E1902): *`__match_args__` must be a tuple of strings.* Emitted if `__match_args__` isn't a tuple of strings required for match. :too-many-positional-sub-patterns (E1903): *%s expects %d positional sub-patterns (given %d)* - Emitted when the number of allowed positional sub-patterns exceeds the - number of allowed sub-patterns specified in `__match_args__`. + Emitted when the number of allowed positional sub-patterns exceeds the number + of allowed sub-patterns specified in `__match_args__`. :multiple-class-sub-patterns (E1904): *Multiple sub-patterns for attribute %s* - Emitted when there is more than one sub-pattern for a specific attribute in - a class pattern. + Emitted when there is more than one sub-pattern for a specific attribute in a + class pattern. Method Args checker diff --git a/doc/whatsnew/0/0.x.rst b/doc/whatsnew/0/0.x.rst index 793f07a941..96259358b5 100644 --- a/doc/whatsnew/0/0.x.rst +++ b/doc/whatsnew/0/0.x.rst @@ -29,7 +29,7 @@ Release date: 2013-04-25 * Simplify checks for dangerous default values by unifying tests for all different mutable compound literals. -* Improve the description for E1124[redundant-keyword-arg] +* Improve the description for E1124[:ref:`redundant-keyword-arg`] What's New in Pylint 0.27.0? diff --git a/doc/whatsnew/1/1.0.rst b/doc/whatsnew/1/1.0.rst index a3dc48b588..e9bf9324f9 100644 --- a/doc/whatsnew/1/1.0.rst +++ b/doc/whatsnew/1/1.0.rst @@ -19,7 +19,7 @@ Release date: 2013-08-06 * Do not double-check parameter names with the regex for parameters and inline variables. -* Added a new warning missing-final-newline (C0304) for files missing +* Added a new warning :ref:`missing-final-newline` (C0304) for files missing the final newline. * Methods that are decorated as properties are now treated as attributes @@ -34,13 +34,13 @@ Release date: 2013-08-06 pylint can detect that value on the right-hand side is a class (like collections.namedtuple()). -* Simplified invalid-name message +* Simplified :ref:`invalid-name` message * Added a new warning invalid-encoded-data (W0512) for files that contain data that cannot be decoded with the specified or default encoding. -* New warning bad-open-mode (W1501) for calls to open (or file) that +* New warning :ref:`bad-open-mode` (W1501) for calls to open (or file) that specify invalid open modes (Original implementation by Sasha Issayev). * New warning old-style-class (C1001) for classes that do not have any @@ -49,18 +49,18 @@ Release date: 2013-08-06 * Add new name type 'class_attribute' for attributes defined in class scope. By default, allow both const and variable names. -* New warning trailing-whitespace (C0303) that warns about +* New warning :ref:`trailing-whitespace` (C0303) that warns about trailing whitespace. * Added a new warning unpacking-in-except (W0712) about unpacking exceptions in handlers, which is unsupported in Python 3. -* Add a configuration option for missing-docstring to +* Add a configuration option for :ref:`missing-docstring` to optionally exempt short functions/methods/classes from the check. -* Add the type of the offending node to missing-docstring - and empty-docstring. +* Add the type of the offending node to :ref:`missing-docstring` + and :ref:`empty-docstring`. * New utility classes for per-checker unittests in testutils.py @@ -70,7 +70,7 @@ Release date: 2013-08-06 * Do not treat all variables starting with _ as dummy variables, only _ itself. -* Make the line-too-long warning configurable by adding a regex for lines +* Make the :ref:`line-too-long` warning configurable by adding a regex for lines for with the length limit should not be enforced * Do not warn about a long line if a pylint disable @@ -81,7 +81,7 @@ Release date: 2013-08-06 * Added a new warning 'old-raise-syntax' for the deprecated syntax raise Exception, args -* Support for PEP 3102 and new missing-kwoa (E1125) message for missing +* Support for PEP 3102 and new :ref:`missing-kwoa` (E1125) message for missing mandatory keyword argument Closes Logilab #107788 diff --git a/doc/whatsnew/1/1.1.rst b/doc/whatsnew/1/1.1.rst index ece4c5447e..03e81d94c9 100644 --- a/doc/whatsnew/1/1.1.rst +++ b/doc/whatsnew/1/1.1.rst @@ -5,10 +5,10 @@ Release date: 2013-12-22 * Add new check for use of deprecated pragma directives "pylint:disable-msg" - or "pylint:enable-msg" (I0022, deprecated-pragma) which was previously + or "pylint:enable-msg" (I0022, :ref:`deprecated-pragma`) which was previously emitted as a regular warn(). -* Avoid false used-before-assignment for except handler defined +* Avoid false :ref:`used-before-assignment` for except handler defined identifier used on the same line. Closes #111 @@ -16,7 +16,7 @@ Release date: 2013-12-22 * Combine 'no-space-after-operator', 'no-space-after-comma' and 'no-space-before-operator' into a new warning 'bad-whitespace'. -* Add a new warning 'superfluous-parens' for unnecessary +* Add a new warning ':ref:`superfluous-parens`' for unnecessary parentheses after certain keywords. * Fix a potential crash in the redefine-in-handler warning @@ -25,7 +25,7 @@ Release date: 2013-12-22 * Add a new option for the multi-statement warning to allow single-line if statements. -* Add 'bad-context-manager' error, checking that '__exit__' +* Add ':ref:`bad-context-manager`' error, checking that '__exit__' special method accepts the right number of arguments. * Run pylint as a python module 'python -m pylint' (Anatoly Techtonik). @@ -39,14 +39,14 @@ Release date: 2013-12-22 Closes BitBucket #53 Closes BitBucket #54 -* Added a new warning, 'non-iterator-returned', for non-iterators +* Added a new warning, ':ref:`non-iterator-returned`', for non-iterators returned by '__iter__'. * Add new checks for unpacking non-sequences in assignments - (unpacking-non-sequence) as well as unbalanced tuple unpacking - (unbalanced-tuple-unpacking). + (:ref:`unpacking-non-sequence`) as well as unbalanced tuple unpacking + (:ref:`unbalanced-tuple-unpacking`). -* useless-else-on-loop not emitted if there is a break in the +* :ref:`useless-else-on-loop` not emitted if there is a break in the else clause of inner loop. Closes #117 @@ -70,6 +70,6 @@ Release date: 2013-12-22 * Various documentation fixes and enhancements -* Fix a false-positive trailing-whitespace on Windows +* Fix a false-positive :ref:`trailing-whitespace` on Windows Closes #55 diff --git a/doc/whatsnew/1/1.2.rst b/doc/whatsnew/1/1.2.rst index 55ef46f0e6..d5ba21cfce 100644 --- a/doc/whatsnew/1/1.2.rst +++ b/doc/whatsnew/1/1.2.rst @@ -10,7 +10,7 @@ Release date: 2014-04-30 * Add a new warning [bad-continuation] for badly indented continued lines. -* Emit [assignment-from-none] when the function contains bare returns. +* Emit [:ref:`assignment-from-none`] when the function contains bare returns. Closes BitBucket #191 @@ -24,8 +24,8 @@ Release date: 2014-04-30 Closes BitBucket #151 -* Extend the checking for unbalanced-tuple-unpacking and - unpacking-non-sequence to instance attribute unpacking as well. +* Extend the checking for :ref:`unbalanced-tuple-unpacking` and + :ref:`unpacking-non-sequence` to instance attribute unpacking as well. * Fix explicit checking of python script (1.2 regression) @@ -66,7 +66,7 @@ Release date: 2014-04-18 Closes BitBucket #170 -* Add new warning 'eval-used', checking that the builtin function ``eval`` was used. +* Add new warning ':ref:`eval-used`', checking that the builtin function ``eval`` was used. * Make it possible to show a naming hint for invalid name by setting include-naming-hint. Also make the naming hints configurable. @@ -84,7 +84,7 @@ Release date: 2014-04-18 warnings; contributed by sebastianu@google.com. * Added a new configuration option logging-modules to make the list - of module names that can be checked for 'logging-not-lazy' et. al. + of module names that can be checked for ':ref:`logging-not-lazy`' et. al. configurable; contributed by morbo@google.com. * ensure init-hooks is evaluated before other options, notably load-plugins @@ -97,11 +97,11 @@ Release date: 2014-04-18 Closes BitBucket #50 Closes BitBucket #62 -* pylint doesn't crash when looking for used-before-assignment in context manager assignments. +* pylint doesn't crash when looking for :ref:`used-before-assignment` in context manager assignments. Closes BitBucket #128 -* Add new warning, 'bad-reversed-sequence', for checking that the +* Add new warning, ':ref:`bad-reversed-sequence`', for checking that the reversed() builtin receive a sequence (implements ``__getitem__`` and ``__len__``, without being a dict or a dict subclass) or an instance which implements ``__reversed__``. @@ -110,25 +110,25 @@ Release date: 2014-04-18 Closes #8 -* Add new warning 'bad-exception-context', checking +* Add new warning ':ref:`bad-exception-context`', checking that ``raise ... from ...`` uses a proper exception context (None or an exception). -* Enhance the check for 'used-before-assignment' to look +* Enhance the check for ':ref:`used-before-assignment`' to look for 'nonlocal' uses. -* Emit 'undefined-all-variable' if a package's __all__ +* Emit ':ref:`undefined-all-variable`' if a package's __all__ variable contains a missing submodule. Closes #126 -* Add a new warning 'abstract-class-instantiated' for checking +* Add a new warning ':ref:`abstract-class-instantiated`' for checking that abstract classes created with ``abc`` module and with abstract methods are instantiated. -* Do not warn about 'return-arg-in-generator' in Python 3.3+. +* Do not warn about ':ref:`return-arg-in-generator`' in Python 3.3+. -* Do not warn about 'abstract-method' when the abstract method +* Do not warn about ':ref:`abstract-method`' when the abstract method is implemented through assignment Closes #155 @@ -145,11 +145,11 @@ Release date: 2014-04-18 * Don't register the new style checker w/ python >= 3 -* Fix unused-import false positive w/ augment assignment +* Fix :ref:`unused-import` false positive w/ augment assignment Closes #78 -* Fix access-member-before-definition false negative wrt aug assign +* Fix :ref:`access-member-before-definition` false negative wrt aug assign Closes #164 diff --git a/doc/whatsnew/1/1.3.rst b/doc/whatsnew/1/1.3.rst index 4b3d4dd86d..60875094c6 100644 --- a/doc/whatsnew/1/1.3.rst +++ b/doc/whatsnew/1/1.3.rst @@ -21,7 +21,7 @@ Release date: 2014-07-26 Closes #205. -* Emit 'undefined-variable' for undefined names when using the +* Emit ':ref:`undefined-variable`' for undefined names when using the Python 3 ``metaclass=`` argument. * Checkers respect priority now. @@ -32,29 +32,29 @@ Release date: 2014-07-26 Closes #149. -* Fix unused-import false positive with Python 3 metaclasses +* Fix :ref:`unused-import` false positive with Python 3 metaclasses Closes #143 -* Don't warn with 'bad-format-character' when encountering +* Don't warn with ':ref:`bad-format-character`' when encountering the 'a' format on Python 3. * Add multiple checks for PEP 3101 advanced string formatting: - 'bad-format-string', 'missing-format-argument-key', - 'unused-format-string-argument', 'format-combined-specification', - 'missing-format-attribute' and 'invalid-format-index'. + ':ref:`bad-format-string`', ':ref:`missing-format-argument-key`', + ':ref:`unused-format-string-argument`', ':ref:`format-combined-specification`', + ':ref:`missing-format-attribute`' and ':ref:`invalid-format-index`'. -* Issue broad-except and bare-except even if the number +* Issue :ref:`broad-except` and :ref:`bare-except` even if the number of except handlers is different than 1. Closes #113 -* Issue attribute-defined-outside-init for all cases, not just +* Issue :ref:`attribute-defined-outside-init` for all cases, not just for the last assignment. Closes #262 -* Emit 'not-callable' when calling properties. +* Emit ':ref:`not-callable`' when calling properties. Closes #268. @@ -63,17 +63,17 @@ Release date: 2014-07-26 Closes #273. -* Add new checks, 'invalid-slice-index' and 'invalid-sequence-index' +* Add new checks, ':ref:`invalid-slice-index`' and ':ref:`invalid-sequence-index`' for invalid sequence and slice indices. -* Add 'assigning-non-slot' warning, which detects assignments to +* Add ':ref:`assigning-non-slot`' warning, which detects assignments to attributes not defined in slots. -* Don't emit 'no-name-in-module' for ignored modules. +* Don't emit ':ref:`no-name-in-module`' for ignored modules. Closes #223. -* Fix an 'unused-variable' false positive, where the variable is +* Fix an ':ref:`unused-variable`' false positive, where the variable is assigned through an import. Closes #196. @@ -83,7 +83,7 @@ Release date: 2014-07-26 Closes #257. -* Don't emit 'unused-variable' when assigning to a nonlocal. +* Don't emit ':ref:`unused-variable`' when assigning to a nonlocal. Closes #275. @@ -92,7 +92,7 @@ Release date: 2014-07-26 Closes #203. -* Don't emit 'pointless-string-statement' for attribute docstrings. +* Don't emit ':ref:`pointless-string-statement`' for attribute docstrings. Closes #193. @@ -103,14 +103,14 @@ Release date: 2014-07-26 * Don't emit hidden-method message when the attribute has been monkey-patched, you're on your own when you do that. -* Only emit attribute-defined-outside-init for definition within the same +* Only emit :ref:`attribute-defined-outside-init` for definition within the same module as the offended class, avoiding to mangle the output in some cases. -* Don't emit 'unnecessary-lambda' if the body of the lambda call contains +* Don't emit ':ref:`unnecessary-lambda`' if the body of the lambda call contains call chaining. Closes #243. -* Don't emit 'missing-docstring' when the actual docstring uses ``.format``. +* Don't emit ':ref:`missing-docstring`' when the actual docstring uses ``.format``. Closes #281. diff --git a/doc/whatsnew/1/1.4.rst b/doc/whatsnew/1/1.4.rst index c7088a5b79..a33245d257 100644 --- a/doc/whatsnew/1/1.4.rst +++ b/doc/whatsnew/1/1.4.rst @@ -38,16 +38,16 @@ Release date: 2015-03-11 Closes #463 * Take in account all the methods from the ancestors - when checking for too-few-public-methods. + when checking for :ref:`too-few-public-methods`. Closes #471 -* Catch enchant errors and emit 'invalid-characters-in-docstring' +* Catch enchant errors and emit ':ref:`invalid-characters-in-docstring`' when checking for spelling errors. Closes #469 -* Use all the inferred statements for the super-init-not-called +* Use all the inferred statements for the :ref:`super-init-not-called` check. Closes #389 @@ -73,7 +73,7 @@ Release date: 2015-03-11 appropriate built-in is not used in an iterating context (semantics taken from 2to3). -* Add a new warning, 'unidiomatic-typecheck', emitted when an explicit +* Add a new warning, ':ref:`unidiomatic-typecheck`', emitted when an explicit typecheck uses type() instead of isinstance(). For example, `type(x) == Y` instead of `isinstance(x, Y)`. Patch by Chris Rebert. @@ -99,11 +99,11 @@ What's New in Pylint 1.4.1? =========================== Release date: 2015-01-16 -* Look only in the current function's scope for bad-super-call. +* Look only in the current function's scope for :ref:`bad-super-call`. Closes #403 -* Check the return of properties when checking for not-callable. +* Check the return of properties when checking for :ref:`not-callable`. Closes #406 @@ -111,7 +111,7 @@ Release date: 2015-01-16 Closes #411 -* Proper abstract method lookup while checking for abstract-class-instantiated. +* Proper abstract method lookup while checking for :ref:`abstract-class-instantiated`. Closes #401 @@ -119,12 +119,12 @@ Release date: 2015-01-16 Closes #415 -* Fix a false positive with catching-non-exception and tuples of exceptions. +* Fix a false positive with :ref:`catching-non-exception` and tuples of exceptions. -* Fix a false negative with raising-non-exception, when the raise used +* Fix a false negative with :ref:`raising-non-exception`, when the raise used an uninferrable exception context. -* Fix a false positive on Python 2 for raising-bad-type, when +* Fix a false positive on Python 2 for :ref:`raising-bad-type`, when raising tuples in the form 'raise (ZeroDivisionError, None)'. * Fix a false positive with invalid-slots-objects, where the slot entry @@ -132,13 +132,13 @@ Release date: 2015-01-16 Closes #421 -* Add a new warning, 'redundant-unittest-assert', emitted when using +* Add a new warning, ':ref:`redundant-unittest-assert`', emitted when using unittest's methods assertTrue and assertFalse with constant value as argument. Patch by Vlad Temian. * Add a new JSON reporter, usable through -f flag. -* Add the method names for the 'signature-differs' and 'argument-differs' +* Add the method names for the ':ref:`signature-differs`' and 'argument-differs' warnings. Closes #433 @@ -177,21 +177,21 @@ Release date: 2014-11-23 all messages that were emitted even though an inference failure happened during checking. -* Improved presenting unused-import message. +* Improved presenting :ref:`unused-import` message. Closes #293 * Add new checker for finding spelling errors. New messages: - wrong-spelling-in-comment, wrong-spelling-in-docstring. + :ref:`wrong-spelling-in-comment`, :ref:`wrong-spelling-in-docstring`. New options: spelling-dict, spelling-ignore-words. * Add new '-j' option for running checks in sub-processes. * Added new checks for line endings if they are mixed (LF vs CRLF) - or if they are not as expected. New messages: mixed-line-endings, - unexpected-line-ending-format. New option: expected-line-ending-format. + or if they are not as expected. New messages: :ref:`mixed-line-endings`, + :ref:`unexpected-line-ending-format`. New option: expected-line-ending-format. -* 'dangerous-default-value' no longer evaluates the value of the arguments, +* ':ref:`dangerous-default-value`' no longer evaluates the value of the arguments, which could result in long error messages or sensitive data being leaked. Closes #282 @@ -208,7 +208,7 @@ Release date: 2014-11-23 * Proper handle class level scope for lambdas. -* Handle 'too-few-format-args' or 'too-many-format-args' for format +* Handle ':ref:`too-few-format-args`' or ':ref:`too-many-format-args`' for format strings with both named and positional fields. Closes #286 @@ -221,7 +221,7 @@ Release date: 2014-11-23 Closes #294 -* Don't emit 'attribute-defined-outside-init' if the attribute +* Don't emit ':ref:`attribute-defined-outside-init`' if the attribute was set by a function call in a defining method. Closes #192 @@ -230,22 +230,22 @@ Release date: 2014-11-23 Closes #296 -* Don't emit 'import-error' if an import was protected by a try-except, +* Don't emit ':ref:`import-error`' if an import was protected by a try-except, which excepted ImportError. -* Fix an 'unused-import' false positive, when the error was emitted +* Fix an ':ref:`unused-import`' false positive, when the error was emitted for all the members imported with 'from import' form. Closes #304 -* Don't emit 'invalid-name' when assigning a name in an +* Don't emit ':ref:`invalid-name`' when assigning a name in an ImportError handler. Closes #302 * Don't count branches from nested functions. -* Fix a false positive with 'too-few-format-args', when the format +* Fix a false positive with ':ref:`too-few-format-args`', when the format strings contains duplicate manual position arguments. Closes #310 @@ -254,7 +254,7 @@ Release date: 2014-11-23 Closes #311 -* Don't emit 'unused-import' when a special object is imported +* Don't emit ':ref:`unused-import`' when a special object is imported (__all__, __doc__ etc.). Closes #309 @@ -264,7 +264,7 @@ Release date: 2014-11-23 Closes #306 -* Don't emit 'protected-access' if the attribute is accessed using +* Don't emit ':ref:`protected-access`' if the attribute is accessed using a property defined at the class level. * Detect calls of the parent's __init__, through a binded super() call. @@ -272,31 +272,31 @@ Release date: 2014-11-23 * Check that a class has an explicitly defined metaclass before emitting 'old-style-class' for Python 2. -* Emit 'catching-non-exception' for non-class nodes. +* Emit ':ref:`catching-non-exception`' for non-class nodes. Closes #303 * Order of reporting is consistent. -* Add a new warning, 'boolean-datetime', emitted when an instance +* Add a new warning, ':ref:`boolean-datetime`', emitted when an instance of 'datetime.time' is used in a boolean context. Closes #239 -* Fix a crash which occurred while checking for 'method-hidden', +* Fix a crash which occurred while checking for ':ref:`method-hidden`', when the parent frame was something different than a function. * Generate html output for missing files. Closes #320 -* Fix a false positive with 'too-many-format-args', when the format +* Fix a false positive with ':ref:`too-many-format-args`', when the format string contains mixed attribute access arguments and manual fields. Closes #322 -* Extend the cases where 'undefined-variable' and 'used-before-assignment' +* Extend the cases where ':ref:`undefined-variable`' and ':ref:`used-before-assignment`' can be detected. Closes #291 @@ -306,20 +306,20 @@ Release date: 2014-11-23 Closes #326 -* Add a new warning, 'logging-format-interpolation', emitted when .format() +* Add a new warning, ':ref:`logging-format-interpolation`', emitted when .format() string interpolation is used within logging function calls. -* Don't emit 'unbalanced-tuple-unpacking' when the rhs of the assignment +* Don't emit ':ref:`unbalanced-tuple-unpacking`' when the rhs of the assignment is a variable length argument. Closes #329 -* Add a new warning, 'inherit-non-class', emitted when a class inherits +* Add a new warning, ':ref:`inherit-non-class`', emitted when a class inherits from something which is not a class. Closes #331 -* Fix another false positives with 'undefined-variable', where the variable +* Fix another false positives with ':ref:`undefined-variable`', where the variable can be found as a class assignment and used in a function annotation. Closes #342 @@ -340,7 +340,7 @@ Release date: 2014-11-23 __coerce__, __delslice__, __getslice__, __setslice__, __cmp__, __oct__, __nonzero__ and __hex__. -* Don't emit 'assigning-non-slot' when the assignment is for a property. +* Don't emit ':ref:`assigning-non-slot`' when the assignment is for a property. Closes #359 @@ -350,12 +350,12 @@ Release date: 2014-11-23 Closes #319 -* 'too-many-public-methods' is reported only for methods defined in a class, +* ':ref:`too-many-public-methods`' is reported only for methods defined in a class, not in its ancestors. Closes #248 -* 'too-many-lines' disable pragma can be located on any line, not only the +* ':ref:`too-many-lines`' disable pragma can be located on any line, not only the first. Closes #321 @@ -367,7 +367,7 @@ Release date: 2014-11-23 a corresponding ``from __future__ import division``. * Add a new option, 'exclude-protected', for excluding members - from the protected-access warning. + from the :ref:`protected-access` warning. Closes #48 @@ -383,7 +383,7 @@ Release date: 2014-11-23 * Warn when performing parameter tuple unpacking; it is not supported in Python 3. -* 'abstract-class-instantiated' is also emitted for Python 2. +* ':ref:`abstract-class-instantiated`' is also emitted for Python 2. It was previously disabled. * Add 'long-suffix' error, emitted when encountering the long suffix diff --git a/doc/whatsnew/1/1.5.rst b/doc/whatsnew/1/1.5.rst index 51c7cf2ce9..a72ff121ed 100644 --- a/doc/whatsnew/1/1.5.rst +++ b/doc/whatsnew/1/1.5.rst @@ -46,14 +46,14 @@ Release date: 2016-01-15 messages from the StringFormatChecker would have resulted in no messages at all. -* Don't apply unneeded-not over sets. +* Don't apply :ref:`unneeded-not` over sets. What's New in Pylint 1.5.3? =========================== Release date: 2016-01-11 -* Handle the import fallback idiom with regard to wrong-import-order. +* Handle the import fallback idiom with regard to :ref:`wrong-import-order`. Closes #750 @@ -75,7 +75,7 @@ Release date: 2016-01-11 Inferring variadic positional arguments and keyword arguments will result into empty Tuples and Dicts, which can lead in - some cases to false positives with regard to no-value-for-parameter. + some cases to false positives with regard to :ref:`no-value-for-parameter`. In order to avoid this, until we'll have support for call context propagation, we're ignoring such cases if detected. @@ -92,7 +92,7 @@ Release date: 2016-01-11 Closes #745 -* Suppress reporting 'unneeded-not' inside ``__ne__`` methods +* Suppress reporting ':ref:`unneeded-not`' inside ``__ne__`` methods Closes #749 @@ -106,7 +106,7 @@ Release date: 2015-12-21 Closes #168 -* Accept only functions and methods for the deprecated-method checker. +* Accept only functions and methods for the :ref:`deprecated-method` checker. This prevents a crash which can occur when an object doesn't have .qname() method after the inference. @@ -130,21 +130,21 @@ Release date: 2015-12-02 Closes #711 -* Add wrong-import-position to check_messages's decorator arguments +* Add :ref:`wrong-import-position` to check_messages's decorator arguments for ImportChecker.leave_module - This fixes an esoteric bug which occurs when ungrouped-imports and - wrong-import-order are disabled and pylint is executed on multiple files. - What happens is that without wrong-import-position in check_messages, + This fixes an esoteric bug which occurs when :ref:`ungrouped-imports` and + :ref:`wrong-import-order` are disabled and pylint is executed on multiple files. + What happens is that without :ref:`wrong-import-position` in check_messages, leave_module will never be called, which means that the first non-import node from other files might leak into the current file, - leading to wrong-import-position being emitted by pylint. + leading to :ref:`wrong-import-position` being emitted by pylint. * Fix a crash which occurred when old visit methods are encountered in plugin modules. Closes #711 -* Don't emit import-self and cyclic-import for relative imports +* Don't emit :ref:`import-self` and :ref:`cyclic-import` for relative imports of modules with the same name as the package itself. Closes #708 @@ -155,30 +155,30 @@ What's New in Pylint 1.5.0? =========================== Release date: 2015-11-29 -* Added multiple warnings related to imports. 'wrong-import-order' +* Added multiple warnings related to imports. ':ref:`wrong-import-order`' is emitted when PEP 8 recommendations regarding imports are not respected (that is, standard imports should be followed by third-party - imports and then by local imports). 'ungrouped-imports' is emitted + imports and then by local imports). ':ref:`ungrouped-imports`' is emitted when imports from the same package or module are not placed - together, but scattered around in the code. 'wrong-import-position' + together, but scattered around in the code. ':ref:`wrong-import-position`' is emitted when code is mixed with imports, being recommended for the latter to be at the top of the file, in order to figure out easier by a human reader what dependencies a module has. Closes #692 -* Added a new refactoring warning, 'unneeded-not', emitted +* Added a new refactoring warning, ':ref:`unneeded-not`', emitted when an expression with the not operator could be simplified. Closes #670 -* Added a new refactoring warning, 'simplifiable-if-statement', +* Added a new refactoring warning, ':ref:`simplifiable-if-statement`', used when an if statement could be reduced to a boolean evaluation of its test. Closes #698 -* Added a new refactoring warning, 'too-many-boolean-expressions', +* Added a new refactoring warning, ':ref:`too-many-boolean-expressions`', used when an if statement contains too many boolean expressions, which makes the code less maintainable and harder to understand. @@ -189,13 +189,13 @@ Release date: 2015-11-29 Closes #284 -* Add a new refactoring error, 'too-many-nested-blocks', which is emitted +* Add a new refactoring error, ':ref:`too-many-nested-blocks`', which is emitted when a function or a method has too many nested blocks, which makes the code less readable and harder to understand. Closes #668 -* Add a new error, 'unsubscriptable-object', that is emitted when +* Add a new error, ':ref:`unsubscriptable-object`', that is emitted when value used in subscription expression doesn't support subscription (i.e. doesn't define __getitem__ method). @@ -208,22 +208,22 @@ Release date: 2015-11-29 Closes #632 -* non-iterator-returned can detect classes with iterator-metaclasses. +* :ref:`non-iterator-returned` can detect classes with iterator-metaclasses. Closes #679 -* Add a new error, 'unsupported-membership-test', emitted when value +* Add a new error, ':ref:`unsupported-membership-test`', emitted when value to the right of the 'in' operator doesn't support membership test protocol (i.e. doesn't define __contains__/__iter__/__getitem__) -* Add new errors, 'not-an-iterable', emitted when non-iterable value +* Add new errors, ':ref:`not-an-iterable`', emitted when non-iterable value is used in an iterating context (starargs, for-statement, - comprehensions, etc), and 'not-a-mapping', emitted when non-mapping + comprehensions, etc), and ':ref:`not-a-mapping`', emitted when non-mapping value is used in a mapping context. Closes #563 -* Make 'no-self-use' checker not emit a warning if there is a 'super()' +* Make ':ref:`no-self-use`' checker not emit a warning if there is a 'super()' call inside the method. Closes #667 @@ -232,39 +232,39 @@ Release date: 2015-11-29 Closes #598 -* Fix unused-argument false positive when the "+=" operator is used. +* Fix :ref:`unused-argument` false positive when the "+=" operator is used. Closes #518 -* Don't emit import-error for ignored modules. PyLint will not emit import +* Don't emit :ref:`import-error` for ignored modules. PyLint will not emit import errors for any import which is, or is a subpackage of, a module in the ignored-modules list. Closes #223 -* Fix unused-import false positive when the import is used in a +* Fix :ref:`unused-import` false positive when the import is used in a class assignment. Closes #475 -* Add a new error, 'not-context-manager', emitted when something +* Add a new error, ':ref:`not-context-manager`', emitted when something that doesn't implement __enter__ and __exit__ is used in a with statement. -* Add a new warning, 'confusing-with-statement', emitted by the +* Add a new warning, ':ref:`confusing-with-statement`', emitted by the base checker, when an ambiguous looking with statement is used. For example `with open() as first, second` which looks like a tuple assignment but is actually 2 context managers. -* Add a new warning, 'duplicate-except', emitted when there is an +* Add a new warning, ':ref:`duplicate-except`', emitted when there is an exception handler which handles an exception type that was handled before. Closes #485 * A couple of warnings got promoted to errors, since they could uncover - potential bugs in the code. These warnings are: assignment-from-none, - unbalanced-tuple-unpacking, unpacking-non-sequence, non-iterator-returned. + potential bugs in the code. These warnings are: :ref:`assignment-from-none`, + :ref:`unbalanced-tuple-unpacking`, :ref:`unpacking-non-sequence`, :ref:`non-iterator-returned`. Closes #388 @@ -282,7 +282,7 @@ Release date: 2015-11-29 Closes #479 -* Don't emit an unused-wildcard-import when the imported name comes +* Don't emit an :ref:`unused-wildcard-import` when the imported name comes from another module and it is in fact a __future__ name. * The colorized reporter now works on Windows. @@ -298,19 +298,19 @@ Release date: 2015-11-29 crashed when it encountered a bytes string with a .format method called. -* Don't warn about no-self-use for builtin properties. +* Don't warn about :ref:`no-self-use` for builtin properties. -* Fix a false positive for bad-reversed-sequence, when a subclass +* Fix a false positive for :ref:`bad-reversed-sequence`, when a subclass of a ``dict`` provides a __reversed__ method. -* Change the default no-docstring-rgx so missing-docstring isn't +* Change the default no-docstring-rgx so :ref:`missing-docstring` isn't emitted for private functions. -* Don't emit redefined-outer-name for __future__ directives. +* Don't emit :ref:`redefined-outer-name` for __future__ directives. Closes #520. -* Provide some hints for the bad-builtin message. +* Provide some hints for the :ref:`bad-builtin` message. Closes #522. @@ -324,21 +324,21 @@ Release date: 2015-11-29 Closes #429. -* Don't emit no-member for classes with unknown bases. +* Don't emit :ref:`no-member` for classes with unknown bases. Since we don't know what those bases might add, we simply ignore the error in this case. -* Lookup in the implicit metaclass when checking for no-member, +* Lookup in the implicit metaclass when checking for :ref:`no-member`, if the class in question has an implicit metaclass, which is True for new style classes. Closes #438. -* Add two new warnings, duplicate-bases and inconsistent-mro. +* Add two new warnings, :ref:`duplicate-bases` and :ref:`inconsistent-mro`. - duplicate-bases is emitted when a class has the same bases - listed more than once in its bases definition, while inconsistent-mro + :ref:`duplicate-bases` is emitted when a class has the same bases + listed more than once in its bases definition, while :ref:`inconsistent-mro` is emitted when no sane mro hierarchy can be determined. Closes #526. @@ -365,12 +365,12 @@ Release date: 2015-11-29 documentation in Sphinx, Google, and Numpy style. * Detect undefined variable cases, where the "definition" of an undefined - variable was in del statement. Instead of emitting used-before-assignment, - which is totally misleading, it now emits undefined-variable. + variable was in del statement. Instead of emitting :ref:`used-before-assignment`, + which is totally misleading, it now emits :ref:`undefined-variable`. Closes #528. -* Don't emit attribute-defined-outside-init and access-member-before-definition +* Don't emit :ref:`attribute-defined-outside-init` and :ref:`access-member-before-definition` for mixin classes. Actual errors can occur in mixin classes, but this is controlled by the ignore-mixin-members option. @@ -382,34 +382,34 @@ Release date: 2015-11-29 Closes #342 and issue #404. -* Add a new warning, 'unexpected-special-method-signature', which is emitted +* Add a new warning, ':ref:`unexpected-special-method-signature`', which is emitted when a special method (dunder method) doesn't have the expected signature, which can lead to actual errors in the application code. Closes #253. -* Remove 'bad-context-manager' due to the inclusion of 'unexpected-special-method-signature'. +* Remove ':ref:`bad-context-manager`' due to the inclusion of ':ref:`unexpected-special-method-signature`'. -* Don't emit no-name-in-module if the import is guarded by an ImportError, Exception or +* Don't emit :ref:`no-name-in-module` if the import is guarded by an ImportError, Exception or a bare except clause. -* Don't emit no-member if the attribute access node is protected by an +* Don't emit :ref:`no-member` if the attribute access node is protected by an except handler, which handles AttributeError, Exception or it is a bare except. -* Don't emit import-error if the import is guarded by an ImportError, Exception or a +* Don't emit :ref:`import-error` if the import is guarded by an ImportError, Exception or a bare except clause. -* Don't emit undefined-variable if the node is guarded by a NameError, Exception +* Don't emit :ref:`undefined-variable` if the node is guarded by a NameError, Exception or bare except clause. -* Add a new warning, 'using-constant-test', which is emitted when a conditional +* Add a new warning, ':ref:`using-constant-test`', which is emitted when a conditional statement (If, IfExp) uses a test which is always constant, such as numbers, classes, functions etc. This is most likely an error from the user's part. Closes #524. -* Don't emit 'raising-non-exception' when the exception has unknown +* Don't emit ':ref:`raising-non-exception`' when the exception has unknown bases. We don't know what those bases actually are and it's better to assume that the user knows what he is doing rather than emitting a message which can be considered a false positive. @@ -442,11 +442,11 @@ Release date: 2015-11-29 * yield-outside-func is also emitted for ``yield from``. -* Add a new error, 'too-many-star-expressions', emitted when +* Add a new error, ':ref:`too-many-star-expressions`', emitted when there are more than one starred expression (`*x`) in an assignment. The warning is emitted only on Python 3. -* Add a new error, 'invalid-star-assignment-target', emitted when +* Add a new error, ':ref:`invalid-star-assignment-target`', emitted when a starred expression (`*x`) is used as the lhs side of an assignment, as in `*x = [1, 2]`. This is not a SyntaxError on Python 3 though. @@ -458,11 +458,11 @@ Release date: 2015-11-29 module level, which is an error on Python 3. Using this will emit a SyntaxWarning on Python 2. -* Add a new error, 'star-needs-assignment-target', emitted on Python 3 when +* Add a new error, ':ref:`star-needs-assignment-target`', emitted on Python 3 when a Starred expression (`*x`) is not used in an assignment target. This is not caught when parsing the AST on Python 3, so it needs to be a separate check. -* Add a new error, 'unsupported-binary-operation', emitted when +* Add a new error, ':ref:`unsupported-binary-operation`', emitted when two a binary arithmetic operation is executed between two objects which don't support it (a number plus a string for instance). This is currently disabled, since the it exhibits way too many false @@ -473,11 +473,11 @@ Release date: 2015-11-29 These were moved since they didn't belong in astroid. -* Enable misplaced-future for Python 3. +* Enable :ref:`misplaced-future` for Python 3. Closes #580. -* Add a new error, 'nonlocal-and-global', which is emitted when a +* Add a new error, ':ref:`nonlocal-and-global`', which is emitted when a name is found to be both nonlocal and global in the same scope. Closes #581. @@ -507,9 +507,9 @@ Release date: 2015-11-29 Closes #608. -* Improved the not-in-loop checker to properly detect more cases. +* Improved the :ref:`not-in-loop` checker to properly detect more cases. -* Add a new error, 'continue-in-finally', which is emitted when +* Add a new error, ':ref:`continue-in-finally`', which is emitted when the ``continue`` keyword is found inside a ``finally`` clause, which is a SyntaxError. @@ -542,7 +542,7 @@ Release date: 2015-11-29 * --profile flag is obsolete and it will be removed in Pylint 1.6. -* Add a new error, 'misplaced-bare-raise'. +* Add a new error, ':ref:`misplaced-bare-raise`'. The error is used when a bare raise is not used inside an except clause. This can generate a RuntimeError in Python, if there are no active exceptions @@ -576,14 +576,14 @@ Release date: 2015-11-29 Closes #424. -* Add a new error, 'nonlocal-without-binding' +* Add a new error, ':ref:`nonlocal-without-binding`' The error is emitted on Python 3 when a nonlocal name is not bound to any variable in the parents scopes. Closes #582. -* 'deprecated-module' can be shown for modules which aren't +* ':ref:`deprecated-module`' can be shown for modules which aren't available. Closes #362. @@ -591,51 +591,51 @@ Release date: 2015-11-29 * Don't consider a class abstract if its members can't be properly inferred. - This fixes a false positive related to abstract-class-instantiated. + This fixes a false positive related to :ref:`abstract-class-instantiated`. Closes #648. * Add a new checker for the async features added by PEP 492. -* Add a new error, 'yield-inside-async-function', emitted on +* Add a new error, ':ref:`yield-inside-async-function`', emitted on Python 3.5 and upwards when the ``yield`` statement is found inside a new coroutine function (PEP 492). -* Add a new error, 'not-async-context-manager', emitted when +* Add a new error, ':ref:`not-async-context-manager`', emitted when an async context manager block is used with an object which doesn't support this protocol (PEP 492). -* Add a new convention warning, 'singleton-comparison', emitted when +* Add a new convention warning, ':ref:`singleton-comparison`', emitted when comparison to True, False or None is found. -* Don't emit 'assigning-non-slot' for descriptors. +* Don't emit ':ref:`assigning-non-slot`' for descriptors. Closes #652. -* Add a new error, 'repeated-keyword', when a keyword argument is passed +* Add a new error, ':ref:`repeated-keyword`', when a keyword argument is passed multiple times into a function call. - This is similar with redundant-keyword-arg, but it's mildly different + This is similar with :ref:`redundant-keyword-arg`, but it's mildly different that it needs to be a separate error. * --enable=all can now be used. Closes #142. -* Add a new convention message, 'misplaced-comparison-constant', +* Add a new convention message, ':ref:`misplaced-comparison-constant`', emitted when a constant is placed in the left hand side of a comparison, as in '5 == func()'. This is also called Yoda condition, since the flow of code reminds of the Star Wars green character, conditions usually encountered in languages with variabile assignments in conditional statements. -* Add a new convention message, 'consider-using-enumerate', which is +* Add a new convention message, ':ref:`consider-using-enumerate`', which is emitted when code that uses ``range`` and ``len`` for iterating is encountered. Closes #684. -* Added two new refactoring messages, 'no-classmethod-decorator' and - 'no-staticmethod-decorator', which are emitted when a static method or a class +* Added two new refactoring messages, ':ref:`no-classmethod-decorator`' and + ':ref:`no-staticmethod-decorator`', which are emitted when a static method or a class method is declared without using decorators syntax. Closes #675. diff --git a/doc/whatsnew/1/1.6/full.rst b/doc/whatsnew/1/1.6/full.rst index 3bcd37e826..a88fa4b6bc 100644 --- a/doc/whatsnew/1/1.6/full.rst +++ b/doc/whatsnew/1/1.6/full.rst @@ -59,12 +59,12 @@ Release date: 2016-07-03 Closes #923 -* bad-builtin is now an extension check. +* :ref:`bad-builtin` is now an extension check. * generated-members support qualified name through regular expressions. For instance, one can specify a regular expression as --generated-members=astroid.node_classes.* - for ignoring every no-member error that is accessed as in ``astroid.node_classes.missing.object``. + for ignoring every :ref:`no-member` error that is accessed as in ``astroid.node_classes.missing.object``. * Add the ability to ignore files based on regex matching, with the new ``--ignore-patterns`` option. Allow for multiple ignore patterns to be specified. Rather than clobber the existing @@ -72,7 +72,7 @@ Release date: 2016-07-03 Closes #156 -* Added a new error, 'trailing-newlines', which is emitted when a file +* Added a new error, ':ref:`trailing-newlines`', which is emitted when a file has trailing new lines. Closes #682 @@ -86,7 +86,7 @@ Release date: 2016-07-03 Closes #162 -* Add a new recommendation checker, 'consider-iterating-dictionary', which is emitted +* Add a new recommendation checker, ':ref:`consider-iterating-dictionary`', which is emitted which is emitted when a dictionary is iterated through .keys(). Closes #699 @@ -98,12 +98,12 @@ Release date: 2016-07-03 Closes #828 -* A new error was added, 'invalid-length-returned', when the ``__len__`` +* A new error was added, ':ref:`invalid-length-returned`', when the ``__len__`` special method returned something else than a non-negative number. Closes #557 -* Switch to using isort internally for wrong-import-order. +* Switch to using isort internally for :ref:`wrong-import-order`. Closes #879 @@ -111,14 +111,14 @@ Release date: 2016-07-03 Closes #887 -* Don't warn about invalid-sequence-index if the indexed object has unknown base +* Don't warn about :ref:`invalid-sequence-index` if the indexed object has unknown base classes. Closes #867 -* Don't crash when checking, for super-init-not-called, a method defined in an if block. +* Don't crash when checking, for :ref:`super-init-not-called`, a method defined in an if block. -* Do not emit import-error or no-name-in-module for fallback import blocks by default. +* Do not emit :ref:`import-error` or :ref:`no-name-in-module` for fallback import blocks by default. Until now, we warned with these errors when a fallback import block (a TryExcept block that contained imports for Python 2 and 3) was found, but this gets cumbersome when diff --git a/doc/whatsnew/1/1.6/summary.rst b/doc/whatsnew/1/1.6/summary.rst index e8f61f02ff..51c666c58e 100644 --- a/doc/whatsnew/1/1.6/summary.rst +++ b/doc/whatsnew/1/1.6/summary.rst @@ -83,7 +83,7 @@ New features contains more forward-looking functions:: $ cat a.py - # Oups, now pylint emits a redefined-builtin message. + # Oups, now pylint emits a :ref:`redefined-builtin` message. from six.moves import open $ pylint a.py --redefining-builtins-modules=six.moves @@ -120,9 +120,9 @@ Other Changes This allows having comments inside list values, in the configuration, such as:: - disable=no-member, + disable=:ref:`no-member`, # Don't like this check - bad-indentation + :ref:`bad-indentation` * We now use the isort_ package internally. diff --git a/doc/whatsnew/1/1.7/full.rst b/doc/whatsnew/1/1.7/full.rst index 9e3234a02e..d95d096e93 100644 --- a/doc/whatsnew/1/1.7/full.rst +++ b/doc/whatsnew/1/1.7/full.rst @@ -22,17 +22,17 @@ What's New in Pylint 1.7? Release date: 2017-04-13 -* Don't emit missing-final-newline or trailing-whitespace for formfeeds (page breaks). +* Don't emit :ref:`missing-final-newline` or :ref:`trailing-whitespace` for formfeeds (page breaks). Closes #1218 and #1219 -* Don't emit by default no-member if we have opaque inference objects in the inference results +* Don't emit by default :ref:`no-member` if we have opaque inference objects in the inference results This is controlled through the new flag ignore-on-opaque-inference, which is by default True. The inference can return multiple potential results while evaluating a Python object, but some branches might not be evaluated, which results in partial inference. In that case, it might be useful to still emit - no-member and other checks for the rest of the inferred objects. + :ref:`no-member` and other checks for the rest of the inferred objects. * Added new message ``assign-to-new-keyword`` to warn about assigning to names which will become a keyword in future Python releases. @@ -40,12 +40,12 @@ Release date: 2017-04-13 Closes #1351 * Split the 'missing or differing' in parameter documentation in different error. - 'differing-param-doc' covers the differing part of the old 'missing-param-doc', - and 'differing-type-doc' covers the differing part of the old 'missing-type-doc' + ':ref:`differing-param-doc`' covers the differing part of the old ':ref:`missing-param-doc`', + and ':ref:`differing-type-doc`' covers the differing part of the old ':ref:`missing-type-doc`' Closes #1342 -* Added a new error, 'used-prior-global-declaration', which is emitted when a name +* Added a new error, ':ref:`used-prior-global-declaration`', which is emitted when a name is used prior a global declaration in a function. This causes a SyntaxError in Python 3.6 @@ -62,18 +62,18 @@ Release date: 2017-04-13 * Require one space for annotations with type hints, as per PEP 8. -* 'trailing-comma-tuple' check was added +* ':ref:`trailing-comma-tuple`' check was added This message is emitted when pylint finds an one-element tuple, created by a stray comma. This can suggest a potential problem in the code and it is recommended to use parentheses in order to emphasise the creation of a tuple, rather than relying on the comma itself. -* Don't emit not-callable for instances with unknown bases. +* Don't emit :ref:`not-callable` for instances with unknown bases. Closes #1213 -* Treat keyword only arguments the same as positional arguments with regard to unused-argument check +* Treat keyword only arguments the same as positional arguments with regard to :ref:`unused-argument` check * Don't try to access variables defined in a separate scope when checking for ``protected-access`` @@ -84,7 +84,7 @@ Release date: 2017-04-13 * Added new extension to detect comparisons of integers against zero -* Added new error conditions for 'bad-super-call' +* Added new error conditions for ':ref:`bad-super-call`' Now detects ``super(type(self), self)`` and ``super(self.__class__, self)`` which can lead to recursion loop in derived classes. @@ -97,7 +97,7 @@ Release date: 2017-04-13 Closes #1035 -* Add a new warning, 'redefined-argument-from-local' +* Add a new warning, ':ref:`redefined-argument-from-local`' Closes #649 @@ -111,20 +111,20 @@ Release date: 2017-04-13 Closes #441 -* Added a new warning, 'useless-super-delegation' +* Added a new warning, ':ref:`useless-super-delegation`' Close 839. -* Added a new error, 'invalid-metaclass', raised when +* Added a new error, ':ref:`invalid-metaclass`', raised when we can detect that a class is using an improper metaclass. Closes #579 -* Added a new refactoring message, 'literal-comparison'. +* Added a new refactoring message, ':ref:`literal-comparison`'. Closes #786 -* arguments-differ takes in consideration kwonlyargs and variadics +* :ref:`arguments-differ` takes in consideration kwonlyargs and variadics Closes #983 @@ -142,13 +142,13 @@ Release date: 2017-04-13 Fixes part of #975 -* ignored-argument-names is now used for ignoring arguments for unused-variable check. +* ignored-argument-names is now used for ignoring arguments for :ref:`unused-variable` check. This option was used for ignoring arguments when computing the correct number of arguments a function should have, but for handling the arguments with regard - to unused-variable check, dummy-variables-rgx was used instead. Now, ignored-argument-names + to :ref:`unused-variable` check, dummy-variables-rgx was used instead. Now, ignored-argument-names is used for its original purpose and also for ignoring the matched arguments for - the unused-variable check. This offers a better control of what should be ignored + the :ref:`unused-variable` check. This offers a better control of what should be ignored and how. Also, the same option was moved from the design checker to the variables checker, which means that the option now appears under the ``[VARIABLES]`` section inside @@ -159,7 +159,7 @@ Release date: 2017-04-13 * Fix a false positive for keyword variadics with regard to keyword only arguments. If a keyword only argument was necessary for a function, but that function was called - with keyword variadics (\**kwargs), then we were emitting a missing-kwoa false positive, + with keyword variadics (\**kwargs), then we were emitting a :ref:`missing-kwoa` false positive, which is now fixed. Closes #934. @@ -195,30 +195,30 @@ Release date: 2017-04-13 Refs #746. * Catch more cases as not proper iterables for __slots__ with - regard to invalid-slots pattern. + regard to :ref:`invalid-slots` pattern. Closes #775 * empty indent strings are rejected. -* Added a new error, 'relative-beyond-top-level', which is emitted +* Added a new error, ':ref:`relative-beyond-top-level`', which is emitted when a relative import was attempted beyond the top level package. Closes #588 -* Added a new warning, 'unsupported-assignment-operation', which is +* Added a new warning, ':ref:`unsupported-assignment-operation`', which is emitted when item assignment is tried on an object which doesn't have this ability. Closes #591 -* Added a new warning, 'unsupported-delete-operation', which is +* Added a new warning, ':ref:`unsupported-delete-operation`', which is emitted when item deletion is tried on an object which doesn't have this ability. Closes #592 -* Fix a false positive of 'redundant-returns-doc', occurred when the documented +* Fix a false positive of ':ref:`redundant-returns-doc`', occurred when the documented function was using *yield* instead of *return*. Closes #984. @@ -226,13 +226,13 @@ Release date: 2017-04-13 * Fix false positives of 'missing-[raises|params|type]-doc' due to not recognizing keyword synonyms supported by Sphinx. -* Added a new refactoring message, 'consider-merging-isinstance', which is +* Added a new refactoring message, ':ref:`consider-merging-isinstance`', which is emitted whenever we can detect that consecutive isinstance calls can be merged together. Closes #968 -* Fix a false positive of 'missing-param-doc' and 'missing-type-doc', +* Fix a false positive of ':ref:`missing-param-doc`' and ':ref:`missing-type-doc`', occurred when a class docstring uses the 'For the parameters, see' magic string but the class __init__ docstring does not, or vice versa. @@ -241,7 +241,7 @@ Release date: 2017-04-13 Closes #911. -* Added proper exception type inference for 'missing-raises-doc'. +* Added proper exception type inference for ':ref:`missing-raises-doc`'. * Added InvalidMessageError exception class to replace asserts in pylint.utils. @@ -274,7 +274,7 @@ Release date: 2017-04-13 * Added a new Python 3 warning around implementing '__div__', '__idiv__', or '__rdiv__' as those methods are phased out in Python 3. -* Added a new warning, 'overlapping-except', which is +* Added a new warning, ':ref:`overlapping-except`', which is emitted when two exceptions in the same except-clause are aliases for each other or one exceptions is an ancestor of another. @@ -283,7 +283,7 @@ Release date: 2017-04-13 * Added a new Python 3 warning for calling 'str.encode' or 'str.decode' with a non-text encoding. -* Added new coding convention message, 'single-string-used-for-slots'. +* Added new coding convention message, ':ref:`single-string-used-for-slots`'. Closes #1166 @@ -299,9 +299,9 @@ Release date: 2017-04-13 Closes #1032 and #1034 -* Added refactoring message 'no-else-return'. +* Added refactoring message ':ref:`no-else-return`'. -* Improve unused-variable checker to warn about unused variables in module scope. +* Improve :ref:`unused-variable` checker to warn about unused variables in module scope. Closes #919 @@ -313,7 +313,7 @@ Release date: 2017-04-13 Closes #1177 -* Added refactoring message 'consider-using-ternary'. +* Added refactoring message ':ref:`consider-using-ternary`'. Closes #1204 diff --git a/doc/whatsnew/1/1.7/summary.rst b/doc/whatsnew/1/1.7/summary.rst index 83a7b48a53..1f09ee1884 100644 --- a/doc/whatsnew/1/1.7/summary.rst +++ b/doc/whatsnew/1/1.7/summary.rst @@ -596,7 +596,7 @@ Other Changes default True. The inference can return multiple potential results while evaluating a Python object, but some branches might not be evaluated, which results in partial inference. In that case, it might be useful to still emit - no-member and other checks for the rest of the inferred objects. + :ref:`no-member` and other checks for the rest of the inferred objects. * Namespace packages are now supported by pylint. This includes both explicit namespace packages and implicit namespace packages, supported in Python 3 through PEP 420. @@ -609,13 +609,13 @@ Other Changes can enable the analysis for both branches using this flag. * ``ignored-argument-names`` option is now used for ignoring arguments - for unused-variable check. + for :ref:`unused-variable` check. This option was used for ignoring arguments when computing the correct number of arguments a function should have, but for handling the arguments with regard - to unused-variable check, dummy-variables-rgx was used instead. Now, ignored-argument-names + to :ref:`unused-variable` check, dummy-variables-rgx was used instead. Now, ignored-argument-names is used for its original purpose and also for ignoring the matched arguments for - the unused-variable check. This offers a better control of what should be ignored + the :ref:`unused-variable` check. This offers a better control of what should be ignored and how. Also, the same option was moved from the design checker to the variables checker, which means that the option now appears under the ``[VARIABLES]`` section inside @@ -696,15 +696,15 @@ Other Changes For instance, you can now use the **#** sign for having comments inside comma separated values, as seen below:: - disable=no-member, # Don't care about it for now - bad-indentation, # No need for this - import-error + disable=:ref:`no-member`, # Don't care about it for now + :ref:`bad-indentation`, # No need for this + :ref:`import-error` Of course, interweaving comments with values is also working:: - disable=no-member, + disable=:ref:`no-member`, # Don't care about it for now - bad-indentation # No need for this + :ref:`bad-indentation` # No need for this This works by setting the `inline comment prefixes`_ accordingly. diff --git a/doc/whatsnew/1/1.8/full.rst b/doc/whatsnew/1/1.8/full.rst index 9e79cd7067..3bdfae187e 100644 --- a/doc/whatsnew/1/1.8/full.rst +++ b/doc/whatsnew/1/1.8/full.rst @@ -35,7 +35,7 @@ Release date: 2017-12-15 Closes #1713 -* Fixing u'' string in superfluous-parens message +* Fixing u'' string in :ref:`superfluous-parens` message Closes #1420 @@ -76,9 +76,9 @@ Release date: 2017-12-15 * Added a couple of new Python 3 checks for accessing dict methods in non-iterable context -* Protocol checks (not-a-mapping, not-an-iterable and co.) aren't emitted on classes with dynamic getattr +* Protocol checks (:ref:`not-a-mapping`, :ref:`not-an-iterable` and co.) aren't emitted on classes with dynamic getattr -* Added a new warning, 'bad-thread-instantiation' +* Added a new warning, ':ref:`bad-thread-instantiation`' This message is emitted when the threading.Thread class does not receive the target argument, but receives just one argument, which @@ -147,8 +147,8 @@ Release date: 2017-12-15 Closes #1085 -* Disabling 'wrong-import-order', 'wrong-import-position', or - 'ungrouped-imports' for a single line now prevents that line from +* Disabling ':ref:`wrong-import-order`', ':ref:`wrong-import-position`', or + ':ref:`ungrouped-imports`' for a single line now prevents that line from triggering violations on subsequent lines. Closes #1336 diff --git a/doc/whatsnew/1/1.8/summary.rst b/doc/whatsnew/1/1.8/summary.rst index ffde5a20e6..a27f7b61de 100644 --- a/doc/whatsnew/1/1.8/summary.rst +++ b/doc/whatsnew/1/1.8/summary.rst @@ -271,7 +271,7 @@ New checkers Other Changes ============= -* Fixing u'' string in superfluous-parens message. +* Fixing u'' string in :ref:`superfluous-parens` message. * Configuration options of invalid name checker are significantly redesigned. Predefined rules for common naming styles were introduced. For typical @@ -312,7 +312,7 @@ Other Changes * Spelling checker has a new configuration parameter ``max-spelling-suggestions``, which affects maximum count of suggestions included in emitted message. -* The **invalid-name** check contains the name of the template that caused the failure. +* The **:ref:`invalid-name`** check contains the name of the template that caused the failure. For the given code, **pylint** used to emit ``invalid-name`` in the form ``Invalid constant name var``, without offering any context why ``var`` is not such a good name. diff --git a/doc/whatsnew/2/2.0/full.rst b/doc/whatsnew/2/2.0/full.rst index 39e626d86f..9446b8cdd3 100644 --- a/doc/whatsnew/2/2.0/full.rst +++ b/doc/whatsnew/2/2.0/full.rst @@ -65,7 +65,7 @@ Release date: 2018-07-15 Closes #2081 -* Support typing.TYPE_CHECKING for *unused-import* errors +* Support typing.TYPE_CHECKING for *:ref:`unused-import`* errors Closes #1948 @@ -106,14 +106,14 @@ Release date: 2018-07-15 Closes #2076 -* invalid-slice-index is not emitted when the slice is used as index for a complex object. +* :ref:`invalid-slice-index` is not emitted when the slice is used as index for a complex object. We only use a handful of known objects (list, set and friends) to figure out if - we should emit invalid-slice-index when the slice is used to subscript an object. + we should emit :ref:`invalid-slice-index` when the slice is used to subscript an object. * Don't emit ``unused-import`` anymore for typing imports used in type comments. -* Add a new check 'useless-import-alias'. +* Add a new check ':ref:`useless-import-alias`'. Closes #2052 @@ -140,12 +140,12 @@ Release date: 2018-07-15 Closes #2051 -* Add a new warning, 'logging-fstring-interpolation', emitted when f-string +* Add a new warning, ':ref:`logging-fstring-interpolation`', emitted when f-string is used within logging function calls. Closes #1998 -* Don't show 'useless-super-delegation' if the subclass method has different type annotations. +* Don't show ':ref:`useless-super-delegation`' if the subclass method has different type annotations. Closes #1923 @@ -198,7 +198,7 @@ Release date: 2018-07-15 Closes #1788 -* Don't trigger misplaced-bare-raise when the raise is in a finally clause +* Don't trigger :ref:`misplaced-bare-raise` when the raise is in a finally clause Closes #1924 @@ -256,7 +256,7 @@ Release date: 2018-07-15 Closes #1831 -* Fix stop-iteration-return false positive when next builtin has a +* Fix :ref:`stop-iteration-return` false positive when next builtin has a default value in a generator Closes #1830 @@ -329,7 +329,7 @@ Release date: 2018-07-15 Closes #1120 -* Fix false positive undefined-variable for lambda argument in class definitions +* Fix false positive :ref:`undefined-variable` for lambda argument in class definitions Closes #1824 @@ -351,7 +351,7 @@ Release date: 2018-07-15 Closes #638 -* Fix false positive unused-variable in lambda default arguments +* Fix false positive :ref:`unused-variable` in lambda default arguments Closes #1921 Closes #1552 @@ -368,7 +368,7 @@ Release date: 2018-07-15 Closes #2102 -* Fix 'method-hidden' raised when assigning to a property or data descriptor. +* Fix ':ref:`method-hidden`' raised when assigning to a property or data descriptor. * Fix emitting ``useless-super-delegation`` when changing the default value of keyword arguments. @@ -378,7 +378,7 @@ Release date: 2018-07-15 Closes #2214 -* Fix false-positive undefined-variable in nested lambda +* Fix false-positive :ref:`undefined-variable` in nested lambda Closes #760 diff --git a/doc/whatsnew/2/2.0/summary.rst b/doc/whatsnew/2/2.0/summary.rst index 52d8945073..ee69a1fc9f 100644 --- a/doc/whatsnew/2/2.0/summary.rst +++ b/doc/whatsnew/2/2.0/summary.rst @@ -280,7 +280,7 @@ Other Changes * Skip wildcard import check for ``__init__.py``. -* Don't warn 'useless-super-delegation' if the subclass method has different type annotations. +* Don't warn ':ref:`useless-super-delegation`' if the subclass method has different type annotations. * Don't warn that a global variable is unused if it is defined by an import @@ -321,10 +321,10 @@ Other Changes * Fix emitting ``useless-super-delegation`` when changing the default value of keyword arguments. -* Support ``typing.TYPE_CHECKING`` for *unused-import* errors +* Support ``typing.TYPE_CHECKING`` for *:ref:`unused-import`* errors When modules are imported under ``typing.TYPE_CHECKING`` guard, ``pylint`` - will no longer emit *unused-import*. + will no longer emit *:ref:`unused-import`*. * Fix false positive ``unused-variable`` in lambda default arguments diff --git a/doc/whatsnew/2/2.1/full.rst b/doc/whatsnew/2/2.1/full.rst index 03d1e82ac1..02b1d7653a 100644 --- a/doc/whatsnew/2/2.1/full.rst +++ b/doc/whatsnew/2/2.1/full.rst @@ -78,7 +78,7 @@ Release date: 2018-08-01 Closes #2300 -* Fix false-positive undefined-variable for self referential class name in lamdbas +* Fix false-positive :ref:`undefined-variable` for self referential class name in lamdbas Closes #704 diff --git a/doc/whatsnew/2/2.10/full.rst b/doc/whatsnew/2/2.10/full.rst index 7505890997..a243898b2f 100644 --- a/doc/whatsnew/2/2.10/full.rst +++ b/doc/whatsnew/2/2.10/full.rst @@ -179,4 +179,4 @@ Release date: 2021-08-20 * Improve performance when inferring ``Call`` nodes, by utilizing caching. -* Improve error message for invalid-metaclass when the node is an Instance. +* Improve error message for :ref:`invalid-metaclass` when the node is an Instance. diff --git a/doc/whatsnew/2/2.11/full.rst b/doc/whatsnew/2/2.11/full.rst index 323d28eaed..1e0cf6a259 100644 --- a/doc/whatsnew/2/2.11/full.rst +++ b/doc/whatsnew/2/2.11/full.rst @@ -88,7 +88,7 @@ Release date: 2021-09-16 Closes #1375 Closes #330 -* Fix false positives for invalid-all-format that are lists or tuples at runtime +* Fix false positives for :ref:`invalid-all-format` that are lists or tuples at runtime Closes #4711 diff --git a/doc/whatsnew/2/2.13/full.rst b/doc/whatsnew/2/2.13/full.rst index 7976484317..869cf57dd5 100644 --- a/doc/whatsnew/2/2.13/full.rst +++ b/doc/whatsnew/2/2.13/full.rst @@ -179,7 +179,7 @@ Release date: 2022-03-29 Closes #5998 -* Fix false positive for 'nonexistent-operator' when repeated '-' are +* Fix false positive for ':ref:`nonexistent-operator`' when repeated '-' are separated (e.g. by parens). Closes #5769 diff --git a/doc/whatsnew/2/2.13/summary.rst b/doc/whatsnew/2/2.13/summary.rst index e2ad8698e6..f3d760e2a3 100644 --- a/doc/whatsnew/2/2.13/summary.rst +++ b/doc/whatsnew/2/2.13/summary.rst @@ -600,7 +600,7 @@ Other Changes Closes #6388 -* Fix false positive for 'nonexistent-operator' when repeated '-' are +* Fix false positive for ':ref:`nonexistent-operator`' when repeated '-' are separated (e.g. by parens). Closes #5769 diff --git a/doc/whatsnew/2/2.14/full.rst b/doc/whatsnew/2/2.14/full.rst index 2853a9f665..8bc4de3d99 100644 --- a/doc/whatsnew/2/2.14/full.rst +++ b/doc/whatsnew/2/2.14/full.rst @@ -170,7 +170,7 @@ What's New in Pylint 2.14.0? Release date: 2022-06-01 -* The refactoring checker now also raises 'consider-using-generator' messages for +* The refactoring checker now also raises ':ref:`consider-using-generator`' messages for ``max()``, ``min()`` and ``sum()``. Refs #6595 diff --git a/doc/whatsnew/2/2.15/index.rst b/doc/whatsnew/2/2.15/index.rst index cbc30a8af4..d95f1c99cc 100644 --- a/doc/whatsnew/2/2.15/index.rst +++ b/doc/whatsnew/2/2.15/index.rst @@ -497,7 +497,7 @@ Other Bug Fixes - Fix a failure to lint packages with ``__init__.py`` contained in directories lacking ``__init__.py``. Closes #1667 (`#1667 `_) -- Fixed a syntax-error crash that was not handled properly when the declared encoding of a file +- Fixed a :ref:`syntax-error` crash that was not handled properly when the declared encoding of a file was ``utf-9``. Closes #3860 (`#3860 `_) diff --git a/doc/whatsnew/2/2.16/index.rst b/doc/whatsnew/2/2.16/index.rst index 3a9731ce3a..0e6030cf9a 100644 --- a/doc/whatsnew/2/2.16/index.rst +++ b/doc/whatsnew/2/2.16/index.rst @@ -40,7 +40,7 @@ Release date: 2023-03-06 False Positives Fixed --------------------- -- Fix false positive for isinstance-second-argument-not-valid-type with union +- Fix false positive for :ref:`isinstance-second-argument-not-valid-type` with union types. Closes #8205 (`#8205 `_) @@ -149,9 +149,9 @@ Changes requiring user actions - The ``accept-no-raise-doc`` option related to ``missing-raises-doc`` will now be correctly taken into account all the time. - Pylint will no longer raise missing-raises-doc (W9006) when no exceptions are + Pylint will no longer raise :ref:`missing-raises-doc` (W9006) when no exceptions are documented and accept-no-raise-doc is true (issue #7208). - If you were expecting missing-raises-doc errors to be raised in that case, + If you were expecting :ref:`missing-raises-doc` errors to be raised in that case, you will now have to add ``accept-no-raise-doc=no`` in your configuration to keep the same behavior. diff --git a/doc/whatsnew/2/2.17/index.rst b/doc/whatsnew/2/2.17/index.rst index 44ff31616b..6ae8a1068e 100644 --- a/doc/whatsnew/2/2.17/index.rst +++ b/doc/whatsnew/2/2.17/index.rst @@ -220,7 +220,7 @@ False Positives Fixed Closes #8410 (`#8410 `_) -- Fix false positive for isinstance-second-argument-not-valid-type when union +- Fix false positive for :ref:`isinstance-second-argument-not-valid-type` when union types contains None. Closes #8424 (`#8424 `_) @@ -424,7 +424,7 @@ False Positives Fixed Closes #7574 (`#7574 `_) -- Fix false positive for isinstance-second-argument-not-valid-type with union +- Fix false positive for :ref:`isinstance-second-argument-not-valid-type` with union types. Closes #8205 (`#8205 `_) @@ -444,7 +444,7 @@ False Positives Fixed False Negatives Fixed --------------------- -- Fix a false negative for 'missing-parentheses-for-call-in-test' when +- Fix a false negative for ':ref:`missing-parentheses-for-call-in-test`' when inference failed for the internal of the call as we did not need that information to raise diff --git a/doc/whatsnew/2/2.3/full.rst b/doc/whatsnew/2/2.3/full.rst index 947eedbac6..89463a32b9 100644 --- a/doc/whatsnew/2/2.3/full.rst +++ b/doc/whatsnew/2/2.3/full.rst @@ -58,7 +58,7 @@ Release date: 2019-02-27 Closes #2635 -* Fix missing-raises-doc false positive (W9006) +* Fix :ref:`missing-raises-doc` false positive (W9006) Closes #1502 @@ -125,7 +125,7 @@ Release date: 2019-02-27 Closes #2689 -* Add a new option 'check-str-concat-over-line-jumps' to check 'implicit-str-concat-in-sequence' +* Add a new option 'check-str-concat-over-line-jumps' to check ':ref:`implicit-str-concat-in-sequence`' * Fixes for the new style logging format linter. diff --git a/doc/whatsnew/2/2.4/full.rst b/doc/whatsnew/2/2.4/full.rst index ab871c8b5c..ff3632b841 100644 --- a/doc/whatsnew/2/2.4/full.rst +++ b/doc/whatsnew/2/2.4/full.rst @@ -98,7 +98,7 @@ Release date: 2019-09-25 for emitting ``used-before-assignment`` if a variable was only defined inside a type checking guard (using ``TYPE_CHECKING`` variable from `typing`) Unfortunately that missed the case of using those type checking imports - inside the guard itself, which triggered spurious used-before-assignment errors. + inside the guard itself, which triggered spurious :ref:`used-before-assignment` errors. Closes #3119 @@ -184,7 +184,7 @@ Release date: 2019-09-24 Inferring variadic positional arguments and keyword arguments will result into empty Tuples and Dicts, which can lead in - some cases to false positives with regard to no-value-for-parameter. + some cases to false positives with regard to :ref:`no-value-for-parameter`. In order to avoid this, until we'll have support for call context propagation, we're ignoring such cases if detected. We already did that for function calls, but the previous fix @@ -326,7 +326,7 @@ Release date: 2019-09-24 This check is emitted when ``pylint`` finds a class variable that conflicts with a slot name, which would raise a ``ValueError`` at runtime. -* Added new check: dict-iter-missing-items (E1141) +* Added new check: :ref:`dict-iter-missing-items` (E1141) Closes #2761 diff --git a/doc/whatsnew/2/2.5/full.rst b/doc/whatsnew/2/2.5/full.rst index 06d61f7e48..16454597b3 100644 --- a/doc/whatsnew/2/2.5/full.rst +++ b/doc/whatsnew/2/2.5/full.rst @@ -24,8 +24,8 @@ Release date: 2020-06-8 * In a TOML configuration file, it's now possible to use rich (non-string) types, such as list, integer or boolean instead of strings. For example, one can now define a *list* of message identifiers to enable like this:: enable = [ - "use-symbolic-message-instead", - "useless-suppression", + ":ref:`use-symbolic-message-instead`", + ":ref:`useless-suppression`", ] Closes #3538 @@ -112,7 +112,7 @@ Release date: 2020-04-27 Closes #3445 -* Fix dangerous-default-value rule to account for keyword argument defaults +* Fix :ref:`dangerous-default-value` rule to account for keyword argument defaults Closes #3373 @@ -184,16 +184,16 @@ Release date: 2020-04-27 Closes #3281 * Added errors for protocol functions when invalid return types are detected. - E0304 (invalid-bool-returned): __bool__ did not return a bool - E0305 (invalid-index-returned): __index__ did not return an integer - E0306 (invalid-repr-returned): __repr__ did not return a string - E0307 (invalid-str-returned): __str__ did not return a string - E0308 (invalid-bytes-returned): __bytes__ did not return a string - E0309 (invalid-hash-returned): __hash__ did not return an integer - E0310 (invalid-length-hint-returned): __length_hint__ did not return a non-negative integer - E0311 (invalid-format-returned): __format__ did not return a string - E0312 (invalid-getnewargs-returned): __getnewargs__ did not return a tuple - E0313 (invalid-getnewargs-ex-returned): __getnewargs_ex__ did not return a tuple of the form (tuple, dict) + E0304 (:ref:`invalid-bool-returned`): __bool__ did not return a bool + E0305 (:ref:`invalid-index-returned`): __index__ did not return an integer + E0306 (:ref:`invalid-repr-returned`): __repr__ did not return a string + E0307 (:ref:`invalid-str-returned`): __str__ did not return a string + E0308 (:ref:`invalid-bytes-returned`): __bytes__ did not return a string + E0309 (:ref:`invalid-hash-returned`): __hash__ did not return an integer + E0310 (:ref:`invalid-length-hint-returned`): __length_hint__ did not return a non-negative integer + E0311 (:ref:`invalid-format-returned`): __format__ did not return a string + E0312 (:ref:`invalid-getnewargs-returned`): __getnewargs__ did not return a tuple + E0313 (:ref:`invalid-getnewargs-ex-returned`): __getnewargs_ex__ did not return a tuple of the form (tuple, dict) Closes #560 diff --git a/doc/whatsnew/2/2.6/full.rst b/doc/whatsnew/2/2.6/full.rst index dba2143497..a8e0dc9071 100644 --- a/doc/whatsnew/2/2.6/full.rst +++ b/doc/whatsnew/2/2.6/full.rst @@ -38,7 +38,7 @@ Release date: 2020-08-20 * Add an faq detailing which messages to disable to avoid duplicates w/ other popular linters -* Fix superfluous-parens false-positive for the walrus operator +* Fix :ref:`superfluous-parens` false-positive for the walrus operator Closes #3383 diff --git a/doc/whatsnew/2/2.6/summary.rst b/doc/whatsnew/2/2.6/summary.rst index 9061bd00c0..a95adf8ce1 100644 --- a/doc/whatsnew/2/2.6/summary.rst +++ b/doc/whatsnew/2/2.6/summary.rst @@ -23,6 +23,6 @@ Other Changes * ``mixed-indentation`` has been removed, it is no longer useful since TabError is included directly in python3 -* Fix superfluous-parens false-positive for the walrus operator +* Fix :ref:`superfluous-parens` false-positive for the walrus operator * Add support for both isort 4 and isort 5. If you have pinned isort 4 in your project requirements, nothing changes. If you use isort 5, though, note that the ``known-standard-library`` option is not interpreted the same in isort 4 and isort 5 (see `the migration guide in isort documentation` (no longer available) for further details). For compatibility's sake for most pylint users, the ``known-standard-library`` option in pylint now maps to ``extra-standard-library`` in isort 5. If you really want what ``known-standard-library`` now means in isort 5, you must disable the ``wrong-import-order`` check in pylint and run isort manually with a proper isort configuration file. diff --git a/doc/whatsnew/2/2.9/full.rst b/doc/whatsnew/2/2.9/full.rst index 417943e93d..bb2b5b6926 100644 --- a/doc/whatsnew/2/2.9/full.rst +++ b/doc/whatsnew/2/2.9/full.rst @@ -79,7 +79,7 @@ Release date: 2021-07-20 Closes #4715 -* Clarify documentation for consider-using-from-import +* Clarify documentation for :ref:`consider-using-from-import` * Don't emit ``unreachable`` warning for empty generator functions @@ -288,7 +288,7 @@ Release date: 2021-06-29 Closes #585 * Fix a crash when a plugin from the configuration could not be loaded and raise an error - 'bad-plugin-value' instead + ':ref:`bad-plugin-value`' instead Closes #4555 diff --git a/doc/whatsnew/3/3.0/index.rst b/doc/whatsnew/3/3.0/index.rst index cc975ca40d..3d45a3e8e4 100644 --- a/doc/whatsnew/3/3.0/index.rst +++ b/doc/whatsnew/3/3.0/index.rst @@ -84,7 +84,7 @@ False Positives Fixed Closes #9246 (`#9246 `_) -- Fixed false positive nested-min-max for nested lists. +- Fixed false positive :ref:`nested-min-max` for nested lists. Closes #9307 (`#9307 `_) @@ -117,10 +117,10 @@ False Positives Fixed Closes #9148 (`#9148 `_) -- Fixed incorrect suggestion for shallow copy in unnecessary-comprehension +- Fixed incorrect suggestion for shallow copy in :ref:`unnecessary-comprehension` Example of the suggestion: - #pylint: disable=missing-module-docstring + #pylint: disable=:ref:`missing-module-docstring` a = [1, 2, 3] b = [x for x in a] b[0] = 0 @@ -437,7 +437,7 @@ False Positives Fixed - When checking for unbalanced dict unpacking in for-loops, Pylint will now test whether the length of each value to be unpacked matches the number of unpacking targets. Previously, Pylint would test the number of values for the loop - iteration, which would produce a false unbalanced-dict-unpacking warning. + iteration, which would produce a false :ref:`unbalanced-dict-unpacking` warning. Closes #8156 (`#8156 `_) @@ -456,7 +456,7 @@ False Positives Fixed Closes #8410 (`#8410 `_) -- Fix false positive for isinstance-second-argument-not-valid-type when union types contains None. +- Fix false positive for :ref:`isinstance-second-argument-not-valid-type` when union types contains None. Closes #8424 (`#8424 `_) @@ -694,7 +694,7 @@ Other Changes Closes #8760 (`#8760 `_) -- Renamed the "unneeded-not" error into "unnecessary_negation" to be clearer. +- Renamed the ":ref:`unneeded-not`" error into "unnecessary_negation" to be clearer. Closes #8789 (`#8789 `_) diff --git a/doc/whatsnew/3/3.1/index.rst b/doc/whatsnew/3/3.1/index.rst index 900a5ef0b6..d1e63c4e31 100644 --- a/doc/whatsnew/3/3.1/index.rst +++ b/doc/whatsnew/3/3.1/index.rst @@ -100,7 +100,7 @@ False Positives Fixed False Negatives Fixed --------------------- -- Extend broad-exception-raised and broad-exception-caught to except*. +- Extend :ref:`broad-exception-raised` and :ref:`broad-exception-caught` to except*. Closes #8827 (`#8827 `_) @@ -113,7 +113,7 @@ False Negatives Fixed Other Bug Fixes --------------- -- Improve the message provided for wrong-import-order check. Instead of the import statement ("import x"), the message now specifies the import that is out of order and which imports should come after it. As reported in the issue, this is particularly helpful if there are multiple imports on a single line that do not follow the PEP8 convention. +- Improve the message provided for :ref:`wrong-import-order` check. Instead of the import statement ("import x"), the message now specifies the import that is out of order and which imports should come after it. As reported in the issue, this is particularly helpful if there are multiple imports on a single line that do not follow the PEP8 convention. The message will report imports as follows: For "import X", it will report "(standard/third party/first party/local) import X" diff --git a/doc/whatsnew/3/3.2/index.rst b/doc/whatsnew/3/3.2/index.rst index f2e2cff46a..0cc86200b3 100644 --- a/doc/whatsnew/3/3.2/index.rst +++ b/doc/whatsnew/3/3.2/index.rst @@ -148,7 +148,7 @@ Release date: 2024-06-06 False Positives Fixed --------------------- -- Classes with only an Ellipsis (``...``) in their body do not trigger 'multiple-statements' +- Classes with only an Ellipsis (``...``) in their body do not trigger ':ref:`multiple-statements`' anymore if they are inlined (in accordance with black's 2024 style). Closes #9398 (`#9398 `_) diff --git a/doc/whatsnew/3/3.3/index.rst b/doc/whatsnew/3/3.3/index.rst index 9460f1e732..19e7c5bb87 100644 --- a/doc/whatsnew/3/3.3/index.rst +++ b/doc/whatsnew/3/3.3/index.rst @@ -385,7 +385,7 @@ Internal Changes ---------------- - All variables, classes, functions and file names containing the word 'similar', when it was, - in fact, referring to 'symilar' (the standalone program for the duplicate-code check) were renamed + in fact, referring to 'symilar' (the standalone program for the :ref:`duplicate-code` check) were renamed to 'symilar'. Closes #9734 (`#9734 `_) diff --git a/script/check_message_references.py b/script/check_message_references.py new file mode 100644 index 0000000000..d45b102993 --- /dev/null +++ b/script/check_message_references.py @@ -0,0 +1,388 @@ +#!/usr/bin/env python3 +# Licensed under the GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html +# For details: https://github.com/pylint-dev/pylint/blob/main/LICENSE +# Copyright (c) https://github.com/pylint-dev/pylint/blob/main/CONTRIBUTORS.txt + +"""Pre-commit hook to check and fix pylint message references in documentation. + +This script scans documentation files for words containing dashes (like "no-member") +and converts them to Sphinx references (`:ref:`no-member``) if they are valid +pylint message symbols. +""" + +from __future__ import annotations + +import argparse +import re +import sys +from pathlib import Path +from re import Pattern + +# Try to import pylint components +try: + from pylint.checkers import initialize as initialize_checkers + from pylint.extensions import initialize as initialize_extensions + from pylint.lint.pylinter import PyLinter +except ImportError: + print("Error: This script must be run in an environment where pylint is installed.") + sys.exit(1) + + +class MessageReferenceChecker: + """Checks and fixes pylint message references in documentation files.""" + + # Pattern to find words with dashes that might be message symbols + # Negative lookbehind/lookahead to avoid matching already formatted refs + DASH_WORD_PATTERN: Pattern[str] = re.compile( + r"(? set[str]: + """Load all valid pylint message symbols.""" + linter = PyLinter() + initialize_checkers(linter) + initialize_extensions(linter) + + symbols = set() + for message in linter.msgs_store.messages: + symbols.add(message.symbol) + # Also add old names if they exist + if hasattr(message, "old_names"): + for _, old_symbol in message.old_names: + symbols.add(old_symbol) + + if self.verbose: + print(f"Loaded {len(symbols)} message symbols") + + return symbols + + def _is_in_code_block(self, content: str, match_start: int) -> bool: + """Check if a match position is inside a code block. + + Args: + content: The full file content + match_start: The start position of the match + + Returns: + True if the match is inside a code block + """ + # Get the content before the match + before_match = content[:match_start] + + # Check for RST code blocks + if ".. code-block::" in before_match or "\n::" in before_match: + # Simple heuristic: count indentation changes after last code block start + lines_before = before_match.split("\n") + for i in range(len(lines_before) - 1, -1, -1): + line = lines_before[i] + if ".. code-block::" in line or (line.strip() == "::"): + # We're likely in a code block if we haven't seen a dedent + return True + if line and not line[0].isspace() and line.strip(): + # Found a non-indented line, probably out of code block + break + + # Check for Markdown code fences + fence_count = before_match.count("```") + before_match.count("~~~") + if fence_count % 2 == 1: # Odd number means we're inside a fence + return True + + # Check if we're in inline code + line_start = before_match.rfind("\n") + 1 + line_end = content.find("\n", match_start) + if line_end == -1: + line_end = len(content) + current_line = content[line_start:line_end] + + # Check for inline code patterns + rel_pos = match_start - line_start + for pattern in ("``", "`"): + parts = current_line.split(pattern) + current_pos = 0 + in_code = False + for i, part in enumerate(parts): + if i > 0: + in_code = not in_code + if current_pos <= rel_pos < current_pos + len(part): + return in_code + current_pos += len(part) + len(pattern) + + return False + + def _should_skip_match( + self, content: str, match: re.Match[str], filepath: Path + ) -> bool: + """Determine if a match should be skipped. + + Args: + content: The full file content + match: The regex match object + filepath: Path to the file being checked + + Returns: + True if the match should be skipped + """ + # pylint: disable=too-many-locals + word = match.group(1) + start = match.start() + + # Skip if not a valid message symbol + if word not in self.message_symbols: + return True + + # Skip if already properly formatted + # Check the surrounding context + context_start = max(0, start - 10) + context_end = min(len(content), match.end() + 10) + context = content[context_start:context_end] + if ":ref:`" in context and "`" in context: + return True + + # Skip if in a code block + if self._is_in_code_block(content, start): + return True + + # Skip if it looks like a command-line argument (preceded by -- or -) + before_start = max(0, start - 3) + before = content[before_start:start] + if "--" in before or (before and before[-1] == "-"): + return True + + # Get the current line for context-specific checks + line_start = content.rfind("\n", 0, start) + 1 + line_end = content.find("\n", start) + if line_end == -1: + line_end = len(content) + line = content[line_start:line_end] + word_pos_in_line = start - line_start + + # Skip if this is a pylint functional test comment + # Pattern: # [message-name] or # [message-name, other-message] + if "#" in line: + comment_start = line.find("#") + if 0 <= comment_start < word_pos_in_line: + comment_part = line[comment_start:] + # Check for [message-name] pattern in comments + if "[" in comment_part and "]" in comment_part: + bracket_start = comment_part.find("[") + bracket_end = comment_part.find("]") + if bracket_start < bracket_end: + # Check if our word is inside the brackets + word_rel_pos = word_pos_in_line - comment_start + if bracket_start < word_rel_pos < bracket_end: + return True + + # Skip if in a functional test file path + if "functional" in str(filepath) or "test" in str(filepath): + # In test files, be extra conservative about comments + if "#" in line and line.find("#") < word_pos_in_line: + return True + + # Skip if part of a URL or file path + if any( + pattern in line + for pattern in ("http://", "https://", "file://", "../", "./", "\\", "/") + ): + # Check if the word is part of a path or URL + for sep in ("/", "\\", "."): + if (word_pos_in_line > 0 and line[word_pos_in_line - 1] == sep) or ( + word_pos_in_line + len(word) < len(line) + and line[word_pos_in_line + len(word)] == sep + ): + return True + + return False + + def check_file(self, filepath: Path) -> bool: + """Check a single file for message references. + + Args: + filepath: Path to the file to check + + Returns: + True if the file has no issues or all issues were fixed + """ + if filepath.suffix not in self.VALID_EXTENSIONS: + return True + + try: + with open(filepath, encoding="utf-8") as f: + content = f.read() + except (OSError, UnicodeDecodeError) as e: + print(f"Error reading {filepath}: {e}") + return False + + original_content = content + issues_in_file = [] + + # Find all potential message references + for match in self.DASH_WORD_PATTERN.finditer(original_content): + if not self._should_skip_match(original_content, match, filepath): + word = match.group(1) + issues_in_file.append((match.start(), match.end(), word)) + + if not issues_in_file: + if self.verbose: + print(f"✓ {filepath}: No issues found") + return True + + # Report or fix issues + self.issues_found += len(issues_in_file) + + if self.fix: + # Build a list of replacements + replacements = [] + for start, end, word in issues_in_file: + ref = f":ref:`{word}`" + replacements.append((start, end, ref)) + + # Apply replacements from end to start to maintain string positions + replacements.sort(key=lambda x: x[0], reverse=True) + modified_content = content + for start, end, replacement in replacements: + modified_content = ( + modified_content[:start] + replacement + modified_content[end:] + ) + + # Only write if content actually changed + if modified_content != original_content: + try: + return self.fix_the_file( + filepath, issues_in_file, modified_content, original_content + ) + except OSError as e: + print(f"Error writing {filepath}: {e}") + return False + else: + print(f"⚠ {filepath}: No changes made (content unchanged)") + return True + else: + # Report issues + print(f"✗ {filepath}: Found {len(issues_in_file)} issue(s):") + + # Show context for each issue + lines = original_content.split("\n") + for start, _, word in issues_in_file: + line_num = original_content[:start].count("\n") + 1 + col = start - original_content.rfind("\n", 0, start) - 1 + + # Get the line and highlight the issue + if line_num <= len(lines): + line = lines[line_num - 1] + print(f" Line {line_num}:{col}: '{word}' should be :ref:`{word}`") + if self.verbose: + print(f" {line.strip()}") + + return False + + def fix_the_file( + self, + filepath: str | Path, + issues_in_file: list[tuple[int, int, str]], + modified_content: str, + original_content: str, + ) -> bool: + with open(filepath, "w", encoding="utf-8") as f: + f.write(modified_content) + self.files_fixed += 1 + print(f"✓ {filepath}: Fixed {len(issues_in_file)} reference(s)") + # Show what was changed if verbose + if self.verbose: + for start, _, word in issues_in_file: + line_num = original_content[:start].count("\n") + 1 + print(f" Line {line_num}: '{word}' → :ref:`{word}`") + return True + + def check_files(self, filenames: list[str]) -> bool: + """Check multiple files. + + Args: + filenames: List of file paths to check + + Returns: + True if all files have no issues or all issues were fixed + """ + all_good = True + + for filename in filenames: + filepath = Path(filename) + if not filepath.exists(): + print(f"Warning: {filepath} does not exist") + continue + + if not self.check_file(filepath): + all_good = False + + # Print summary + if self.issues_found > 0: + if self.fix: + print( + f"\nSummary: Fixed {self.issues_found} reference(s) in {self.files_fixed} file(s)" + ) + else: + print(f"\nSummary: Found {self.issues_found} issue(s)") + print("Run with --fix to automatically fix these issues") + elif self.verbose: + print("\nNo issues found!") + + return all_good + + +def main(argv: list[str] | None = None) -> int: + """Main entry point for the script.""" + parser = argparse.ArgumentParser( + description="Check and fix pylint message references in documentation files" + ) + parser.add_argument("filenames", nargs="*", help="Files to check") + parser.add_argument("--fix", action="store_true", help="Automatically fix issues") + parser.add_argument("--verbose", "-v", action="store_true", help="Verbose output") + args = parser.parse_args(argv) + + if not args.filenames: + print("No files specified") + return 1 + + checker = MessageReferenceChecker(verbose=args.verbose, fix=args.fix) + success = checker.check_files(args.filenames) + + return 0 if success else 1 + + +if __name__ == "__main__": + sys.exit(main())