Result of a docstring formatter and some manual fixes on top of it

doc/exts/pylint_extensions.py

@@ -2,7 +2,9 @@
 # Licensed under the GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 # For details: https://github.com/PyCQA/pylint/blob/main/LICENSE
 
-"""Script used to generate the extensions file before building the actual documentation."""
+"""Script used to generate the extensions file before building the actual
+documentation.
+"""
 
 import os
 import re

doc/exts/pylint_features.py

@@ -2,7 +2,9 @@
 # Licensed under the GPL: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 # For details: https://github.com/PyCQA/pylint/blob/main/LICENSE
 
-"""Script used to generate the features file before building the actual documentation."""
+"""Script used to generate the features file before building the actual
+documentation.
+"""
 
 import os
 

doc/exts/pylint_messages.py

@@ -50,9 +50,11 @@ def _register_all_checkers_and_extensions(linter: PyLinter) -> None:
 def _get_all_messages(
     linter: PyLinter,
 ) -> Tuple[MessagesDict, OldMessagesDict]:
-    """Get all messages registered to a linter and return a dictionary indexed by message
-    type.
-    Also return a dictionary of old message and the new messages they can be mapped to.
+    """Get all messages registered to a linter and return a dictionary indexed
+    by message type.
+
+    Also return a dictionary of old message and the new messages they
+    can be mapped to.
     """
     messages_dict: MessagesDict = {
         "fatal": [],
@@ -202,6 +204,7 @@ def _write_redirect_pages(old_messages: OldMessagesDict) -> None:
 # pylint: disable-next=unused-argument
 def build_messages_pages(app: Optional[Sphinx]) -> None:
     """Overwrite messages files by printing the documentation to a stream.
+
     Documentation is written in ReST format.
     """
     # Create linter, register all checkers and extensions and get all messages

doc/user_guide/message-control.rst

@@ -112,7 +112,7 @@ Here's an example with all these rules in a single place:
             pass
 
         def meth1(self, arg):
-            """this issues a message"""
+            """This issues a message"""
             print(self)
 
         def meth2(self, arg):
@@ -122,14 +122,14 @@ Here's an example with all these rules in a single place:
                   + "foo")
 
         def meth3(self):
-            """test one line disabling"""
+            """Test one line disabling"""
             # no error
             print(self.bla) # pylint: disable=no-member
             # error
             print(self.blop)
 
         def meth4(self):
-            """test re-enabling"""
+            """Test re-enabling"""
             # pylint: disable=no-member
             # no error
             print(self.bla)
@@ -139,7 +139,7 @@ Here's an example with all these rules in a single place:
             print(self.blip)
 
         def meth5(self):
-            """test IF sub-block re-enabling"""
+            """Test IF sub-block re-enabling"""
             # pylint: disable=no-member
             # no error
             print(self.bla)
@@ -154,7 +154,7 @@ Here's an example with all these rules in a single place:
             print(self.blip)
 
         def meth6(self):
-            """test TRY/EXCEPT sub-block re-enabling"""
+            """Test TRY/EXCEPT sub-block re-enabling"""
             # pylint: disable=no-member
             # no error
             print(self.bla)
@@ -169,7 +169,7 @@ Here's an example with all these rules in a single place:
             print(self.blip)
 
         def meth7(self):
-            """test one line block opening disabling"""
+            """Test one line block opening disabling"""
             if self.blop: # pylint: disable=no-member
                 # error
                 print(self.blip)
@@ -180,7 +180,7 @@ Here's an example with all these rules in a single place:
             print(self.blip)
 
         def meth8(self):
-            """test late disabling"""
+            """Test late disabling"""
             # error
             print(self.blip)
             # pylint: disable=no-member
@@ -189,7 +189,7 @@ Here's an example with all these rules in a single place:
             print(self.blop)
 
         def meth9(self):
-            """test next line disabling"""
+            """Test next line disabling"""
             # no error
             # pylint: disable-next=no-member
             print(self.bla)

examples/custom_raw.py

@@ -10,8 +10,8 @@
 
 
 class MyRawChecker(BaseChecker):
-    """Check for line continuations with '\' instead of using triple
-    quoted string or parenthesis
+    """Check for line continuations with '\' instead of using triple quoted
+    string or parenthesis.
     """
 
     __implements__ = IRawChecker

examples/deprecation_checker.py

@@ -1,6 +1,6 @@
-"""Example checker detecting deprecated functions/methods. Following example searches for usages of
-deprecated function `deprecated_function` and deprecated method `MyClass.deprecated_method`
-from module mymodule:
+"""Example checker detecting deprecated functions/methods. Following example
+searches for usages of deprecated function `deprecated_function` and deprecated
+method `MyClass.deprecated_method` from module mymodule:
 
 .. code-block:: console
     $ cat mymodule.py
@@ -59,7 +59,8 @@ class DeprecationChecker(DeprecatedMixin, BaseChecker):
     name = "deprecated"
 
     def deprecated_methods(self) -> Set[str]:
-        """Callback method called by DeprecatedMixin for every method/function found in the code.
+        """Callback method called by DeprecatedMixin for every method/function
+        found in the code.
 
         Returns:
             collections.abc.Container of deprecated function/method names.

pylint/__init__.py

@@ -21,7 +21,8 @@
 def run_pylint(argv: Optional[Sequence[str]] = None):
     """Run pylint.
 
-    argv can be a sequence of strings normally supplied as arguments on the command line
+    argv can be a sequence of strings normally supplied as arguments on
+    the command line
     """
     from pylint.lint import Run as PylintRun
 
@@ -34,7 +35,8 @@ def run_pylint(argv: Optional[Sequence[str]] = None):
 def run_epylint(argv: Optional[Sequence[str]] = None):
     """Run epylint.
 
-    argv can be a list of strings normally supplied as arguments on the command line
+    argv can be a list of strings normally supplied as arguments on the
+    command line
     """
     from pylint.epylint import Run as EpylintRun
 
@@ -44,7 +46,8 @@ def run_epylint(argv: Optional[Sequence[str]] = None):
 def run_pyreverse(argv: Optional[Sequence[str]] = None):
     """Run pyreverse.
 
-    argv can be a sequence of strings normally supplied as arguments on the command line
+    argv can be a sequence of strings normally supplied as arguments on
+    the command line
     """
     from pylint.pyreverse.main import Run as PyreverseRun
 
@@ -54,7 +57,8 @@ def run_pyreverse(argv: Optional[Sequence[str]] = None):
 def run_symilar(argv: Optional[Sequence[str]] = None):
     """Run symilar.
 
-    argv can be a sequence of strings normally supplied as arguments on the command line
+    argv can be a sequence of strings normally supplied as arguments on
+    the command line
     """
     from pylint.checkers.similar import Run as SimilarRun
 

pylint/checkers/__init__.py

@@ -53,7 +53,6 @@
 
 The raw_metrics checker has no number associated since it doesn't emit any
 messages nor reports. XXX not true, emit a 07 report !
-
 """
 
 import sys
@@ -75,9 +74,9 @@ def table_lines_from_stats(
     old_stats: Optional[LinterStats],
     stat_type: Literal["duplicated_lines", "message_types"],
 ) -> List[str]:
-    """Get values listed in <columns> from <stats> and <old_stats>,
-    and return a formatted list of values, designed to be given to a
-    ureport.Table object
+    """Get values listed in <columns> from <stats> and <old_stats>, and return
+    a formatted list of values, designed to be given to a ureport.Table
+    object.
     """
     lines: List[str] = []
     if stat_type == "duplicated_lines":

pylint/checkers/base.py

@@ -101,9 +101,9 @@
 
 
 class NamingStyle:
-    """It may seem counterintuitive that single naming style has multiple "accepted"
-    forms of regular expressions, but we need to special-case stuff like dunder names
-    in method names.
+    """It may seem counterintuitive that single naming style has multiple
+    "accepted" forms of regular expressions, but we need to special-case stuff
+    like dunder names in method names.
     """
 
     ANY: Pattern[str] = re.compile(".*")
@@ -231,8 +231,9 @@ class AnyStyle(NamingStyle):
 
 
 def _redefines_import(node):
-    """Detect that the given node (AssignName) is inside an
-    exception handler and redefines an import from the tryexcept body.
+    """Detect that the given node (AssignName) is inside an exception handler
+    and redefines an import from the tryexcept body.
+
     Returns True if the node redefines an import, False otherwise.
     """
     current = node
@@ -267,7 +268,7 @@ def in_loop(node: nodes.NodeNG) -> bool:
 
 def in_nested_list(nested_list, obj):
     """Return true if the object is an element of <nested_list> or of a nested
-    list
+    list.
     """
     for elmt in nested_list:
         if isinstance(elmt, (list, tuple)):
@@ -337,8 +338,8 @@ def _is_multi_naming_match(match, node_type, confidence):
 def _get_properties(config):
     """Returns a tuple of property classes and names.
 
-    Property classes are fully qualified, such as 'abc.abstractproperty' and
-    property names are the actual names, such as 'abstract_property'.
+    Property classes are fully qualified, i.e. 'abc.abstractproperty'
+    and property names are the actual names, i.e. 'abstract_property'.
     """
     property_classes = {BUILTIN_PROPERTY}
     property_names = set()  # Not returning 'property', it has its own check.
@@ -390,8 +391,8 @@ def _determine_function_name_type(node: nodes.FunctionDef, config=None):
 def _has_abstract_methods(node):
     """Determine if the given `node` has abstract methods.
 
-    The methods should be made abstract by decorating them
-    with `abc` decorators.
+    The methods should be made abstract by decorating them with `abc`
+    decorators.
     """
     return len(utils.unimplemented_abstract_methods(node)) > 0
 
@@ -784,9 +785,7 @@ def visit_nonlocal(self, node: nodes.Nonlocal) -> None:
 
     @utils.check_messages("abstract-class-instantiated")
     def visit_call(self, node: nodes.Call) -> None:
-        """Check instantiating abstract class with
-        abc.ABCMeta as metaclass.
-        """
+        """Check instantiating abstract class with abc.ABCMeta as metaclass."""
         for inferred in infer_all(node.func):
             self._check_inferred_class_is_abstract(inferred, node)
 
@@ -1167,8 +1166,8 @@ def visit_module(self, _: nodes.Module) -> None:
         self.linter.stats.node_count["module"] += 1
 
     def visit_classdef(self, _: nodes.ClassDef) -> None:
-        """Check module name, docstring and redefinition
-        increment branch counter
+        """Check module name, docstring and redefinition increment branch
+        counter.
         """
         self.linter.stats.node_count["klass"] += 1
 
@@ -1306,8 +1305,8 @@ def visit_lambda(self, node: nodes.Lambda) -> None:
 
     @utils.check_messages("dangerous-default-value")
     def visit_functiondef(self, node: nodes.FunctionDef) -> None:
-        """Check function name, docstring, arguments, redefinition,
-        variable names, max locals
+        """Check function name, docstring, arguments, redefinition, variable
+        names, max locals.
         """
         if node.is_method():
             self.linter.stats.node_count["method"] += 1
@@ -1370,8 +1369,8 @@ def visit_return(self, node: nodes.Return) -> None:
 
     @utils.check_messages("unreachable")
     def visit_continue(self, node: nodes.Continue) -> None:
-        """Check is the node has a right sibling (if so, that's some unreachable
-        code)
+        """Check is the node has a right sibling (if so, that's some
+        unreachable code)
         """
         self._check_unreachable(node)
 
@@ -1389,8 +1388,8 @@ def visit_break(self, node: nodes.Break) -> None:
 
     @utils.check_messages("unreachable")
     def visit_raise(self, node: nodes.Raise) -> None:
-        """Check if the node has a right sibling (if so, that's some unreachable
-        code)
+        """Check if the node has a right sibling (if so, that's some
+        unreachable code)
         """
         self._check_unreachable(node)
 
@@ -1419,7 +1418,8 @@ def _check_misplaced_format_function(self, call_node):
         "eval-used", "exec-used", "bad-reversed-sequence", "misplaced-format-function"
     )
     def visit_call(self, node: nodes.Call) -> None:
-        """Visit a Call node -> check if this is not a disallowed builtin
+        """Visit a Call node -> check if this is not a disallowed builtin.
+
         call and check for * or ** use
         """
         self._check_misplaced_format_function(node)
@@ -1494,8 +1494,9 @@ def _check_unreachable(self, node):
     def _check_not_in_finally(self, node, node_name, breaker_classes=()):
         """Check that a node is not inside a 'finally' clause of a
         'try...finally' statement.
-        If we find a parent which type is in breaker_classes before
-        a 'try...finally' block we skip the whole check.
+
+        If we find a parent which type is in breaker_classes before a
+        'try...finally' block we skip the whole check.
         """
         # if self._tryfinallys is empty, we're not an in try...finally block
         if not self._tryfinallys:
@@ -2263,8 +2264,8 @@ def visit_pass(self, node: nodes.Pass) -> None:
 
 
 def _is_one_arg_pos_call(call):
-    """Is this a call with exactly 1 argument,
-    where that argument is positional?
+    """Is this a call with exactly 1 argument, where that argument is
+    positional?
     """
     return isinstance(call, nodes.Call) and len(call.args) == 1 and not call.keywords
 
@@ -2436,7 +2437,9 @@ def _is_nan(node) -> bool:
         )
 
     def _check_literal_comparison(self, literal, node: nodes.Compare):
-        """Check if we compare to a literal, which is usually what we do not want to do."""
+        """Check if we compare to a literal, which is usually what we do not
+        want to do.
+        """
         is_other_literal = isinstance(literal, (nodes.List, nodes.Dict, nodes.Set))
         is_const = False
         if isinstance(literal, nodes.Const):
@@ -2450,6 +2453,7 @@ def _check_literal_comparison(self, literal, node: nodes.Compare):
 
     def _check_logical_tautology(self, node: nodes.Compare):
         """Check if identifier is compared against itself.
+
         :param node: Compare node
         :Example:
         val = 786

pylint/checkers/base_checker.py

@@ -67,8 +67,10 @@ def __repr__(self):
         return f"{status} '{self.name}' (responsible for '{msgs}')"
 
     def __str__(self):
-        """This might be incomplete because multiple class inheriting BaseChecker
-        can have the same name. Cf MessageHandlerMixIn.get_full_documentation()
+        """This might be incomplete because multiple class inheriting
+        BaseChecker can have the same name.
+
+        Cf MessageHandlerMixIn.get_full_documentation()
         """
         return self.get_full_documentation(
             msgs=self.msgs, options=self.options_and_values(), reports=self.reports