Upgrade pydocstringformatter to 0.5.0

.pre-commit-config.yaml

@@ -95,7 +95,9 @@ repos:
         args: [--prose-wrap=always, --print-width=88]
         exclude: tests(/.*)*/data
   - repo: https://github.com/DanielNoord/pydocstringformatter
-    rev: a9f94bf13b08fe33f784ed7f0a0fc39e2a8549e2
+    rev: v0.5.0
     hooks:
       - id: pydocstringformatter
         exclude: *fixtures
+        args: ["--max-summary-lines=2", "--split-summary-body", "-w"]
+        files: "pylint"

doc/exts/pylint_messages.py

@@ -52,6 +52,7 @@ def _get_all_messages(
 ) -> 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.
     """
     messages_dict: MessagesDict = {
@@ -202,6 +203,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

pylint/checkers/__init__.py

@@ -77,8 +77,9 @@ def table_lines_from_stats(
     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
+    and return a formatted list of values.
+
+    The return value is designed to be given to a ureport.Table object
     """
     lines: List[str] = []
     if stat_type == "duplicated_lines":

pylint/checkers/base.py

@@ -102,8 +102,7 @@
 
 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.
+    forms of regular expressions, but we need to special-case stuff like dunder names in method names.
     """
 
     ANY: Pattern[str] = re.compile(".*")
@@ -234,6 +233,7 @@ 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.
+
     Returns True if the node redefines an import, False otherwise.
     """
     current = node
@@ -940,7 +940,9 @@ def _check_redefinition(self, redeftype, node):
 
 
 class BasicChecker(_BasicChecker):
-    """Checks for :
+    """Basic checker.
+
+    Checks for :
     * doc strings
     * number of arguments, local variables, branches, returns and statements in
     functions, methods
@@ -1360,7 +1362,9 @@ def is_iterable(internal_node):
 
     @utils.check_messages("unreachable", "lost-exception")
     def visit_return(self, node: nodes.Return) -> None:
-        """1 - check if the node has a right sibling (if so, that's some
+        """Return node visitor.
+
+        1 - check if the node has a right sibling (if so, that's some
         unreachable code)
         2 - check if the node is inside the 'finally' clause of a 'try...finally'
         block
@@ -1378,7 +1382,9 @@ def visit_continue(self, node: nodes.Continue) -> None:
 
     @utils.check_messages("unreachable", "lost-exception")
     def visit_break(self, node: nodes.Break) -> None:
-        """1 - check if the node has a right sibling (if so, that's some
+        """Break node visitor.
+
+        1 - check if the node has a right sibling (if so, that's some
         unreachable code)
         2 - check if the node is inside the 'finally' clause of a 'try...finally'
         block
@@ -1495,6 +1501,7 @@ 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.
         """
@@ -2561,6 +2568,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 classes inheriting BaseChecker
+        can have the same name.
+
+        See: MessageHandlerMixIn.get_full_documentation()
         """
         return self.get_full_documentation(
             msgs=self.msgs, options=self.options_and_values(), reports=self.reports

pylint/checkers/classes/class_checker.py

@@ -362,7 +362,9 @@ def _has_data_descriptor(cls, attr):
 
 def _called_in_methods(func, klass, methods):
     """Check if the func was called in any of the given methods,
-    belonging to the *klass*. Returns True if so, False otherwise.
+    belonging to the *klass*.
+
+    Returns True if so, False otherwise.
     """
     if not isinstance(func, nodes.FunctionDef):
         return False
@@ -697,7 +699,9 @@ def accessed(self, scope):
 
 
 class ClassChecker(BaseChecker):
-    """Checks for :
+    """Checker for class nodes.
+
+    Checks for :
     * methods without self as first argument
     * overridden methods signature
     * access only to existent members via self
@@ -876,7 +880,8 @@ def _check_typing_final(self, node: nodes.ClassDef) -> None:
 
     @check_messages("unused-private-member", "attribute-defined-outside-init")
     def leave_classdef(self, node: nodes.ClassDef) -> None:
-        """Close a class node:
+        """Checker for Class nodes.
+
         check that instance attributes are defined in __init__ and check
         access to existent members
         """
@@ -1463,7 +1468,9 @@ def leave_functiondef(self, node: nodes.FunctionDef) -> None:
 
     def visit_attribute(self, node: nodes.Attribute) -> None:
         """Check if the getattr is an access to a class member
-        if so, register it. Also check for access to protected
+        if so, register it
+
+        Also check for access to protected
         class member from outside its class (but ignore __special__
         methods)
         """
@@ -1617,7 +1624,9 @@ def _check_classmethod_declaration(self, node):
 
     def _check_protected_attribute_access(self, node: nodes.Attribute):
         """Given an attribute access node (set or get), check if attribute
-        access is legitimate. Call _check_first_attr with node before calling
+        access is legitimate.
+
+        Call _check_first_attr with node before calling
         this method. Valid cases are:
         * self._attr in a method or cls._attr in a classmethod. Checked by
         _check_first_attr.

pylint/checkers/deprecated.py

@@ -22,6 +22,7 @@
 
 class DeprecatedMixin(BaseChecker):
     """A mixin implementing logic for checking deprecated symbols.
+
     A class implementing mixin must define "deprecated-method" Message.
     """
 
@@ -180,8 +181,9 @@ def check_deprecated_module(self, node, mod_path):
                 self.add_message("deprecated-module", node=node, args=mod_path)
 
     def check_deprecated_method(self, node, inferred):
-        """Executes the checker for the given node. This method should
-        be called from the checker implementing this mixin.
+        """Executes the checker for the given node.
+
+        This method should be called from the checker implementing this mixin.
         """
 
         # Reject nodes which aren't of interest to us.

pylint/checkers/design_analysis.py

@@ -298,7 +298,9 @@ def _get_parents(
 
 
 class MisdesignChecker(BaseChecker):
-    """Checks for sign of poor/misdesign:
+    """Checker of potential misdesigns.
+
+    Checks for sign of poor/misdesign:
     * number of methods, attributes, local variables...
     * size, complexity of functions, methods
     """

pylint/checkers/ellipsis_checker.py

@@ -28,7 +28,8 @@ class EllipsisChecker(BaseChecker):
     @check_messages("unnecessary-ellipsis")
     def visit_const(self, node: nodes.Const) -> None:
         """Check if the ellipsis constant is used unnecessarily.
-        Emit a warning when:
+
+        Emits a warning when:
          - A line consisting of an ellipsis is preceded by a docstring.
          - A statement exists in the same scope as the ellipsis.
            For example: A function consisting of an ellipsis followed by a

pylint/checkers/exceptions.py

@@ -58,6 +58,7 @@ def predicate(obj):
 
 def _annotated_unpack_infer(stmt, context=None):
     """Recursively generate nodes inferred by the given statement.
+
     If the inferred value is a list or a tuple, recurse on the elements.
     Returns an iterator which yields tuples in the format
     ('original node', 'inferred node').

pylint/checkers/format.py

@@ -237,7 +237,9 @@ def line(self, idx):
 
 
 class FormatChecker(BaseTokenChecker):
-    """Checks for :
+    """Formatting checker.
+
+    Checks for :
     * unauthorized constructions
     * strict indentation
     * line length
@@ -739,7 +741,9 @@ def specific_splitlines(lines: str) -> List[str]:
         return res
 
     def check_lines(self, lines: str, lineno: int) -> None:
-        """Check lines have :
+        """Check given lines for potential messages.
+
+        Check lines have :
         - a final newline
         - no trailing whitespace
         - less than a maximum number of characters

pylint/checkers/imports.py

@@ -300,7 +300,9 @@ def _make_graph(
 
 
 class ImportsChecker(DeprecatedMixin, BaseChecker):
-    """Checks for
+    """BaseChecker for import statements.
+
+    Checks for
     * external modules dependencies
     * relative / wildcard imports
     * cyclic imports

pylint/checkers/misc.py

@@ -76,7 +76,9 @@ def process_module(self, node: nodes.Module) -> None:
 
 class EncodingChecker(BaseChecker):
 
-    """Checks for:
+    """BaseChecker for encoding issues.
+
+    Checks for:
     * warning notes in the code like FIXME, XXX
     * encoding issues.
     """

pylint/checkers/newstyle.py

@@ -45,7 +45,8 @@
 
 class NewStyleConflictChecker(BaseChecker):
     """Checks for usage of new style capabilities on old style classes and
-    other new/old styles conflicts problems
+    other new/old styles conflicts problems.
+
     * use of property, __slots__, super
     * "super" usage
     """

pylint/checkers/raw_metrics.py

@@ -60,7 +60,9 @@ def report_raw_stats(
 
 
 class RawMetricsChecker(BaseTokenChecker):
-    """Does not check anything but gives some raw metrics :
+    """Checker that provides raw metrics instead of checking anything.
+
+    Provides:
     * total number of lines
     * total number of code lines
     * total number of docstring lines

pylint/checkers/refactoring/implicit_booleaness_checker.py

@@ -128,8 +128,7 @@ def instance_has_bool(class_def: nodes.ClassDef) -> bool:
     @utils.check_messages("use-implicit-booleaness-not-len")
     def visit_unaryop(self, node: nodes.UnaryOp) -> None:
         """`not len(S)` must become `not S` regardless if the parent block
-        is a test condition or something else (boolean expression)
-        e.g. `if not len(S):`
+        is a test condition or something else (boolean expression) e.g. `if not len(S):`
         """
         if (
             isinstance(node, nodes.UnaryOp)

pylint/checkers/refactoring/refactoring_checker.py

@@ -1531,6 +1531,7 @@ def _check_use_list_or_dict_literal(self, node: nodes.Call) -> None:
 
     def _check_consider_using_join(self, aug_assign):
         """We start with the augmented assignment and work our way upwards.
+
         Names of variables for nodes if match successful:
         result = ''  # assign
         for number in ['1', '2', '3']  # for_loop
@@ -1824,7 +1825,7 @@ def _has_return_in_siblings(node: nodes.NodeNG) -> bool:
         return False
 
     def _is_function_def_never_returning(self, node: nodes.FunctionDef) -> bool:
-        """Return True if the function never returns. False otherwise.
+        """Return True if the function never returns, False otherwise.
 
         Args:
             node (nodes.FunctionDef): function definition node to be analyzed.
@@ -1846,7 +1847,9 @@ def _is_function_def_never_returning(self, node: nodes.FunctionDef) -> bool:
 
     def _check_return_at_the_end(self, node):
         """Check for presence of a *single* return statement at the end of a
-        function. "return" or "return None" are useless because None is the
+        function.
+
+        "return" or "return None" are useless because None is the
         default return type if they are missing.
 
         NOTE: produces a message only if there is a single return statement

pylint/checkers/similar.py

@@ -109,9 +109,8 @@ class LineSpecifs(NamedTuple):
 
 
 class CplSuccessiveLinesLimits:
-    """This class holds a couple of SuccessiveLinesLimits objects, one for each file compared,
-    and a counter on the number of common lines between both stripped lines collections extracted
-    from both files
+    """Holds a SuccessiveLinesLimits object for each file compared and a
+    counter on the number of common lines between both stripped lines collections extracted from both files
     """
 
     __slots__ = ("first_file", "second_file", "effective_cmn_lines_nb")
@@ -230,7 +229,9 @@ def increment(self, value: Index) -> "LineSetStartCouple":
 def hash_lineset(
     lineset: "LineSet", min_common_lines: int = DEFAULT_MIN_SIMILARITY_LINE
 ) -> Tuple[HashToIndex_T, IndexToLines_T]:
-    """Return two dicts. The first associates the hash of successive stripped lines of a lineset
+    """Return two dicts.
+
+    The first associates the hash of successive stripped lines of a lineset
     to the indices of the starting lines.
     The second dict, associates the index of the starting line in the lineset's stripped lines to the
     couple [start, end] lines number in the corresponding file.
@@ -318,9 +319,12 @@ def filter_noncode_lines(
     stindex_2: Index,
     common_lines_nb: int,
 ) -> int:
-    """Return the effective number of common lines between lineset1 and lineset2 filtered from non code lines, that is to say the number of
-    common successive stripped lines except those that do not contain code (for example a ligne with only an
-    ending parathensis)
+    """Return the effective number of common lines between lineset1
+    and lineset2 filtered from non code lines.
+
+    That is to say the number of common successive stripped
+    lines except those that do not contain code (for example
+    a line with only an ending parathensis)
 
     :param ls_1: first lineset
     :param stindex_1: first lineset starting index
@@ -665,6 +669,7 @@ def _get_functions(
 @functools.total_ordering
 class LineSet:
     """Holds and indexes all the lines of a single source file.
+
     Allows for correspondence between real lines of the source file and stripped ones, which
     are the real ones from which undesired patterns have been removed.
     """
@@ -737,9 +742,10 @@ def report_similarities(
 
 # wrapper to get a pylint checker from the similar class
 class SimilarChecker(BaseChecker, Similar, MapReduceMixin):
-    """Checks for similarities and duplicated code. This computation may be
-    memory / CPU intensive, so you should disable it if you experiment some
-    problems.
+    """Checks for similarities and duplicated code.
+
+    This computation may be memory / CPU intensive, so you
+    should disable it if you experiment some problems.
     """
 
     __implements__ = (IRawChecker,)

pylint/checkers/stdlib.py

@@ -646,9 +646,7 @@ def _check_redundant_assert(self, node, infer):
             )
 
     def _check_datetime(self, node):
-        """Check that a datetime was inferred.
-        If so, emit boolean-datetime warning.
-        """
+        """Check that a datetime was inferred, if so, emit boolean-datetime warning."""
         try:
             inferred = next(node.infer())
         except astroid.InferenceError: