Some modifications for pep237 with pydocstringformatter (#1792)

Co-authored-by: Daniël van Noord <[email protected]>

Author: Pierre-Sassoulas

astroid/astroid_manager.py

@@ -1,5 +1,7 @@
 """
-This file contain the global astroid MANAGER, to prevent circular import that happened
+This file contain the global astroid MANAGER.
+
+It prevents a circular import that happened
 when the only possibility to import it was from astroid.__init__.py.
 
 This AstroidManager is a singleton/borg so it's possible to instantiate an

astroid/brain/brain_boto3.py

@@ -2,7 +2,8 @@
 # For details: https://github.com/PyCQA/astroid/blob/main/LICENSE
 # Copyright (c) https://github.com/PyCQA/astroid/blob/main/CONTRIBUTORS.txt
 
-"""Astroid hooks for understanding boto3.ServiceRequest()."""
+"""Astroid hooks for understanding ``boto3.ServiceRequest()``."""
+
 from astroid import extract_node
 from astroid.manager import AstroidManager
 from astroid.nodes.scoped_nodes import ClassDef

astroid/brain/brain_collections.py

@@ -86,8 +86,8 @@ def __class_getitem__(cls, item): return cls"""
 
 def _looks_like_subscriptable(node: ClassDef) -> bool:
     """
-    Returns True if the node corresponds to a ClassDef of the Collections.abc module that
-    supports subscripting
+    Returns True if the node corresponds to a ClassDef of the Collections.abc module
+    that supports subscripting.
 
     :param node: ClassDef node
     """

astroid/brain/brain_ctypes.py

@@ -19,7 +19,9 @@
 
 def enrich_ctypes_redefined_types():
     """
-    For each ctypes redefined types, overload 'value' and '_type_' members definition.
+    For each ctypes redefined types, overload 'value' and '_type_' members
+    definition.
+
     Overloading 'value' is mandatory otherwise astroid cannot infer the correct type for it.
     Overloading '_type_' is necessary because the class definition made here replaces the original
     one, in which '_type_' member is defined. Luckily those original class definitions are very short

astroid/brain/brain_numpy_core_einsumfunc.py

@@ -4,7 +4,7 @@
 
 """
 Astroid hooks for numpy.core.einsumfunc module:
-https://github.com/numpy/numpy/blob/main/numpy/core/einsumfunc.py
+https://github.com/numpy/numpy/blob/main/numpy/core/einsumfunc.py.
 """
 
 from astroid import nodes

astroid/brain/brain_numpy_utils.py

@@ -22,8 +22,9 @@ def numpy_supports_type_hints() -> bool:
 
 def _get_numpy_version() -> tuple[str, str, str]:
     """
-    Return the numpy version number if numpy can be imported. Otherwise returns
-    ('0', '0', '0')
+    Return the numpy version number if numpy can be imported.
+
+    Otherwise returns ('0', '0', '0')
     """
     try:
         import numpy  # pylint: disable=import-outside-toplevel

astroid/brain/brain_unittest.py

@@ -2,7 +2,7 @@
 # For details: https://github.com/PyCQA/astroid/blob/main/LICENSE
 # Copyright (c) https://github.com/PyCQA/astroid/blob/main/CONTRIBUTORS.txt
 
-"""Astroid hooks for unittest module"""
+"""Astroid hooks for unittest module."""
 from astroid.brain.helpers import register_module_extender
 from astroid.builder import parse
 from astroid.const import PY38_PLUS
@@ -11,9 +11,11 @@
 
 def IsolatedAsyncioTestCaseImport():
     """
-    In the unittest package, the IsolatedAsyncioTestCase class is imported lazily, i.e only
-    when the __getattr__ method of the unittest module is called with 'IsolatedAsyncioTestCase' as
-    argument. Thus the IsolatedAsyncioTestCase is not imported statically (during import time).
+    In the unittest package, the IsolatedAsyncioTestCase class is imported lazily.
+
+    I.E. only when the ``__getattr__`` method of the unittest module is called with
+    'IsolatedAsyncioTestCase' as argument. Thus the IsolatedAsyncioTestCase
+    is not imported statically (during import time).
     This function mocks a classical static import of the IsolatedAsyncioTestCase.
 
     (see https://github.com/PyCQA/pylint/issues/4060)

astroid/exceptions.py

@@ -400,9 +400,10 @@ def __init__(self, target: nodes.NodeNG) -> None:
 
 
 class StatementMissing(ParentMissingError):
-    """Raised when a call to node.statement() does not return a node. This is because
-    a node in the chain does not have a parent attribute and therefore does not
-    return a node for statement().
+    """Raised when a call to node.statement() does not return a node.
+
+    This is because a node in the chain does not have a parent attribute
+    and therefore does not return a node for statement().
 
     Standard attributes:
         target: The node for which the parent lookup failed.

astroid/modutils.py

@@ -339,9 +339,10 @@ def file_info_from_modpath(
     path: Sequence[str] | None = None,
     context_file: str | None = None,
 ) -> spec.ModuleSpec:
-    """given a mod path (i.e. split module / package name), return the
-    corresponding file, giving priority to source file over precompiled
-    file if it exists
+    """Given a mod path (i.e. split module / package name), return the
+    corresponding file.
+
+    Giving priority to source file over precompiled file if it exists.
 
     :param modpath:
       split module's name (i.e name of a module or package split

astroid/nodes/node_ng.py

@@ -126,13 +126,15 @@ def __init__(
 
         self.end_col_offset: int | None = end_col_offset
         """The end column this node appears on in the source code.
+
         Note: This is after the last symbol.
         """
 
         self.position: Position | None = None
-        """Position of keyword(s) and name. Used as fallback for block nodes
-        which might not provide good enough positional information.
-        E.g. ClassDef, FunctionDef.
+        """Position of keyword(s) and name.
+
+        Used as fallback for block nodes which might not provide good
+        enough positional information. E.g. ClassDef, FunctionDef.
         """
 
     def infer(
@@ -262,7 +264,7 @@ def get_children(self) -> Iterator[NodeNG]:
         yield from ()
 
     def last_child(self) -> NodeNG | None:
-        """An optimized version of list(get_children())[-1]"""
+        """An optimized version of list(get_children())[-1]."""
         for field in self._astroid_fields[::-1]:
             attr = getattr(self, field)
             if not attr:  # None or empty list / tuple
@@ -349,6 +351,7 @@ def frame(
 
     def scope(self) -> nodes.LocalsDictNodeNG:
         """The first parent node defining a new scope.
+
         These can be Module, FunctionDef, ClassDef, Lambda, or GeneratorExp nodes.
 
         :returns: The first parent scope node.
@@ -591,7 +594,7 @@ def _infer_name(self, frame, name):
     def _infer(
         self, context: InferenceContext | None = None, **kwargs: Any
     ) -> Generator[InferenceResult, None, InferenceErrorInfo | None]:
-        """we don't know how to resolve a statement by default"""
+        """We don't know how to resolve a statement by default."""
         # this method is overridden by most concrete classes
         raise InferenceError(
             "No inference function for {node!r}.", node=self, context=context
@@ -696,7 +699,9 @@ def _repr_tree(node, result, done, cur_indent="", depth=1):
         @_repr_tree.register(tuple)
         @_repr_tree.register(list)
         def _repr_seq(node, result, done, cur_indent="", depth=1):
-            """Outputs a representation of a sequence that's contained within an AST."""
+            """Outputs a representation of a sequence that's contained within an
+            AST.
+            """
             cur_indent += indent
             result.append("[")
             if not node:

astroid/objects.py

@@ -42,7 +42,7 @@
 
 
 class FrozenSet(node_classes.BaseContainer):
-    """class representing a FrozenSet composite node"""
+    """Class representing a FrozenSet composite node."""
 
     def pytype(self) -> Literal["builtins.frozenset"]:
         return "builtins.frozenset"
@@ -225,7 +225,7 @@ def getattr(self, name, context: InferenceContext | None = None):
 
 
 class ExceptionInstance(bases.Instance):
-    """Class for instances of exceptions
+    """Class for instances of exceptions.
 
     It has special treatment for some of the exceptions's attributes,
     which are transformed at runtime into certain concrete objects, such as
@@ -242,7 +242,7 @@ def special_attributes(self):
 
 
 class DictInstance(bases.Instance):
-    """Special kind of instances for dictionaries
+    """Special kind of instances for dictionaries.
 
     This instance knows the underlying object model of the dictionaries, which means
     that methods such as .values or .items can be properly inferred.
@@ -271,7 +271,7 @@ class DictValues(bases.Proxy):
 
 
 class PartialFunction(scoped_nodes.FunctionDef):
-    """A class representing partial function obtained via functools.partial"""
+    """A class representing partial function obtained via functools.partial."""
 
     @decorators.deprecate_arguments(doc="Use the postinit arg 'doc_node' instead")
     def __init__(
@@ -322,7 +322,7 @@ def qname(self) -> str:
 
 
 class Property(scoped_nodes.FunctionDef):
-    """Class representing a Python property"""
+    """Class representing a Python property."""
 
     @decorators.deprecate_arguments(doc="Use the postinit arg 'doc_node' instead")
     def __init__(

astroid/test_utils.py

@@ -18,9 +18,7 @@
 
 
 def require_version(minver: str = "0.0.0", maxver: str = "4.0.0") -> Callable:
-    """Compare version of python interpreter to the given one.
-    Skip the test if older.
-    """
+    """Compare version of python interpreter to the given one and skips the test if older."""
 
     def parse(python_version: str) -> tuple[int, ...]:
         try:

astroid/transforms.py

@@ -81,7 +81,7 @@ def unregister_transform(self, node_class, transform, predicate=None) -> None:
         self.transforms[node_class].remove((transform, predicate))
 
     def visit(self, module):
-        """Walk the given astroid *tree* and transform each encountered node
+        """Walk the given astroid *tree* and transform each encountered node.
 
         Only the nodes which have transforms registered will actually
         be replaced or changed.