Add verbose mode (#29)

stefmolin · web-flow · commit fccba31c5d7d · 2025-05-11T20:27:17.000-04:00
* Add verbose mode
* Add docstrings for traversal classes
diff --git a/pyproject.toml b/pyproject.toml
@@ -106,3 +106,6 @@ exclude = [ # don't report on checks for these
   '\.__repr__$',
   '\.__str__$',
 ]
+override_SS05 = [ # override SS05 to allow docstrings starting with these words
+  '^Process ',
+]
diff --git a/src/docstringify/cli.py b/src/docstringify/cli.py
@@ -5,13 +5,16 @@
 import argparse
 import sys
 from functools import partial
-from typing import Sequence
+from typing import TYPE_CHECKING
 
 from . import __doc__ as pkg_description
 from . import __version__
 from .converters import GoogleDocstringConverter, NumpydocDocstringConverter
 from .traversal import DocstringTransformer, DocstringVisitor
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
 PROG = __package__
 STYLES = {'google': GoogleDocstringConverter, 'numpydoc': NumpydocDocstringConverter}
 CLI_DEFAULTS = {'threshold': 1.0}
@@ -36,6 +39,9 @@ def main(argv: Sequence[str] | None = None) -> int:
 
     parser = argparse.ArgumentParser(prog=PROG, description=pkg_description)
     parser.add_argument('filenames', nargs='*', help='Filenames to process')
+    parser.add_argument(
+        '-v', '--verbose', action='store_true', help='Run in verbose mode'
+    )
     parser.add_argument(
         '--version', action='version', version=f'%(prog)s {__version__}'
     )
@@ -79,10 +85,11 @@ def main(argv: Sequence[str] | None = None) -> int:
         partial(
             DocstringTransformer,
             converter=converter,
-            **{'overwrite': bool(args.make_changes_inplace)},
+            overwrite=bool(args.make_changes_inplace),
+            verbose=args.verbose,
         )
         if args.make_changes or args.make_changes_inplace
-        else partial(DocstringVisitor, converter=converter)
+        else partial(DocstringVisitor, converter=converter, verbose=args.verbose)
     )
 
     docstrings_processed = missing_docstrings = 0
diff --git a/src/docstringify/traversal/transformer.py b/src/docstringify/traversal/transformer.py
@@ -1,3 +1,8 @@
+"""
+Traverse the AST with the ability to transform it to add templates for docstrings based
+on the source code.
+"""
+
 from __future__ import annotations
 
 import ast
@@ -11,16 +16,39 @@
 
 
 class DocstringTransformer(ast.NodeTransformer, DocstringVisitor):
+    """
+    A class for indicating where docstrings are missing in a single module of source code
+    and injecting suggested docstring templates based on the AST representation into the
+    source code.
+
+    Parameters
+    ----------
+    filename : str
+        The file to process.
+    converter : type[DocstringConverter]
+        The converter class determines the docstring style to use for generating the
+        suggested docstring templates.
+    overwrite : bool, keyword-only, default=False
+        Whether to save the modified source code back to the original file.
+    verbose : bool, keyword-only, default=False
+        Whether to run in verbose mode.
+    """
+
     def __init__(
         self,
         filename: str,
         converter: type[DocstringConverter],
+        *,
         overwrite: bool = False,
+        verbose: bool = False,
     ) -> None:
-        super().__init__(filename, converter)
-        self.overwrite = overwrite
+        super().__init__(filename, converter, verbose=verbose)
+
+        self.overwrite: bool = overwrite
+        """Whether to save the modified source code back to the original file."""
 
     def save(self) -> None:
+        """Save the modified AST to a file as source code."""
         if self.missing_docstrings:
             output = (
                 self.source_file
@@ -37,6 +65,23 @@ def save(self) -> None:
             print(f'Docstring templates written to {output}')
 
     def handle_missing_docstring(self, docstring_node: DocstringNode) -> DocstringNode:
+        """
+        Handle missing docstrings by injecting a suggested docstring template based on
+        the source code into the AST.
+
+        Parameters
+        ----------
+        docstring_node : DocstringNode
+            An instance of :class:`.DocstringNode`, which wraps an AST node and adds
+            additional context relevant for Docstringify.
+
+        Returns
+        -------
+        DocstringNode
+            An instance of :class:`.DocstringNode`, which wraps an AST node and adds
+            additional context relevant for Docstringify. The AST node it contains will
+            have a new node for the docstring template added to its body.
+        """
         suggested_docstring = self.docstring_converter.suggest_docstring(
             docstring_node,
             indent=0
@@ -57,5 +102,9 @@ def handle_missing_docstring(self, docstring_node: DocstringNode) -> DocstringNo
         return docstring_node
 
     def process_file(self) -> None:
+        """
+        Process a source code file, handling missing docstrings and saving the modified
+        AST to a file.
+        """
         super().process_file()
         self.save()
diff --git a/src/docstringify/traversal/visitor.py b/src/docstringify/traversal/visitor.py
@@ -1,3 +1,8 @@
+"""
+Traverse the AST, indicating where docstrings are missing and suggesting templates
+based on the AST.
+"""
+
 from __future__ import annotations
 
 import ast
@@ -13,37 +18,90 @@
 
 
 class DocstringVisitor(ast.NodeVisitor):
+    """
+    A class for indicating where docstrings are missing in a single module of source code
+    and suggesting templates based on the AST representation.
+
+    Parameters
+    ----------
+    filename : str
+        The file to process.
+    converter : type[DocstringConverter] | None, optional
+        When this is ``None``, docstrings will be reported as missing, but when this is
+        a converter, docstring templates will be generated.
+    verbose : bool, keyword-only, default=False
+        Whether to run in verbose mode.
+    """
+
     def __init__(
-        self, filename: str, converter: type[DocstringConverter] | None = None
+        self,
+        filename: str,
+        converter: type[DocstringConverter] | None = None,
+        *,
+        verbose: bool = False,
     ) -> None:
         self.source_file: Path = Path(filename).expanduser().resolve()
+        """The ``Path`` object for the source file."""
+
         self.source_code: str = self.source_file.read_text()
+        """The source code in :attr:`.source_file` as a string."""
+
         self.tree: ast.Module = ast.parse(self.source_code)
+        """The AST for the source code in :attr:`.source_code`."""
 
         self.docstrings_inspected: int = 0
+        """The number of docstrings inspected."""
+
         self.missing_docstrings: list[DocstringNode] = []
+        """The list of docstrings that are missing, each represented as a :class:`.DocstringNode` instance."""
 
         self.module_name: str = self.source_file.stem
+        """The name of the module, derived from the source file name (see :attr:`.source_file`)."""
+
         self.stack: list[DocstringNode] = []
+        """The stack of docstring nodes, used to track the current context in the AST."""
 
         self.docstring_converter: DocstringConverter | None = (
             converter(quote=not issubclass(self.__class__, ast.NodeTransformer))
             if converter
             else None
         )
+        """The docstring converter, if templates are to be generated, otherwise ``None``."""
+
+        self.verbose: bool = verbose
+        """Whether to run in verbose mode."""
 
     def report_missing_docstrings(self) -> None:
-        if not self.missing_docstrings:
-            print(f'No missing docstrings found in {self.source_file}.')
-        else:
+        """
+        Report missing docstrings.
+
+        See Also
+        --------
+        :meth:`.handle_missing_docstring`
+            This method is called for each missing docstring, and it defines any actions
+            that should be taken upon nodes with missing docstrings, such as, suggesting
+            a docstring template based on the source code.
+        """
+        if self.missing_docstrings:
             for docstring_node in self.missing_docstrings:
                 print(
                     f'{docstring_node.fully_qualified_name} is missing a docstring',
                     file=sys.stderr,
                 )
                 self.handle_missing_docstring(docstring_node)
+        elif self.verbose:
+            print(f'No missing docstrings found in {self.source_file}.')
+
+    def handle_missing_docstring(self, docstring_node: DocstringNode) -> None:
+        """
+        Handle missing docstrings by suggesting a template for them when a converter is provided.
 
-    def handle_missing_docstring(self, docstring_node: DocstringNode) -> DocstringNode:
+        Parameters
+        ----------
+        docstring_node : DocstringNode
+            An instance of :class:`.DocstringNode`, which wraps an AST node and adds
+            additional context relevant for Docstringify.
+        """
         if self.docstring_converter:
             print(
                 'Hint:',
@@ -53,7 +111,23 @@ def handle_missing_docstring(self, docstring_node: DocstringNode) -> DocstringNo
             )
 
     def process_docstring(self, docstring_node: DocstringNode) -> DocstringNode:
-        if docstring_node.docstring_required and not docstring_node.docstring:
+        """
+        Process a docstring node, appending it to :attr:`.missing_docstrings` if a docstring
+        is required, but there isn't one.
+
+        Parameters
+        ----------
+        docstring_node : DocstringNode
+            An instance of :class:`.DocstringNode`, which wraps an AST node and adds
+            additional context relevant for Docstringify.
+
+        Returns
+        -------
+        DocstringNode
+            An instance of :class:`.DocstringNode`, which wraps an AST node and adds
+            additional context relevant for Docstringify.
+        """
+        if docstring_node.docstring_required and (not docstring_node.docstring):
             self.missing_docstrings.append(docstring_node)
 
         self.docstrings_inspected += 1
@@ -64,6 +138,21 @@ def visit_docstring(
         node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module,
         docstring_class: type[DocstringNode],
     ) -> ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module:
+        """
+        Visit an AST node by updating the stack and processing the docstring.
+
+        Parameters
+        ----------
+        node : ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
+            The AST node to visit.
+        docstring_class : type[DocstringNode]
+            The class to use for creating the docstring node.
+
+        Returns
+        -------
+        ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
+            The AST node that was visited.
+        """
         docstring_node = docstring_class(
             node,
             self.module_name,
@@ -79,24 +168,90 @@ def visit_docstring(
         return docstring_node.ast_node
 
     def visit_Module(self, node: ast.Module) -> ast.Module:  # noqa: N802
+        """
+        Visit an :class:`ast.Module` node.
+
+        Parameters
+        ----------
+        node : ast.Module
+            The AST node to visit.
+
+        Returns
+        -------
+        ast.Module
+            The visited AST node.
+        """
         return self.visit_docstring(node, DocstringNode)
 
     def visit_ClassDef(self, node: ast.ClassDef) -> ast.ClassDef:  # noqa: N802
+        """
+        Visit an :class:`ast.ClassDef` node.
+
+        Parameters
+        ----------
+        node : ast.ClassDef
+            The AST node to visit.
+
+        Returns
+        -------
+        ast.ClassDef
+            The visited AST node.
+        """
         return self.visit_docstring(node, DocstringNode)
 
     def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef:  # noqa: N802
+        """
+        Visit an :class:`ast.FunctionDef` node.
+
+        Parameters
+        ----------
+        node : ast.FunctionDef
+            The AST node to visit.
+
+        Returns
+        -------
+        ast.FunctionDef
+            The visited AST node.
+        """
         return self.visit_docstring(node, FunctionDocstringNode)
 
     def visit_AsyncFunctionDef(  # noqa: N802
         self, node: ast.AsyncFunctionDef
     ) -> ast.AsyncFunctionDef:
+        """
+        Visit an :class:`ast.AsyncFunctionDef` node.
+
+        Parameters
+        ----------
+        node : ast.AsyncFunctionDef
+            The AST node to visit.
+
+        Returns
+        -------
+        ast.AsyncFunctionDef
+            The visited AST node.
+        """
         return self.visit_docstring(node, FunctionDocstringNode)
 
     def visit_Return(self, node: ast.Return) -> ast.Return:  # noqa: N802
+        """
+        Visit an :class:`ast.Return` node.
+
+        Parameters
+        ----------
+        node : ast.Return
+            The AST node to visit.
+
+        Returns
+        -------
+        ast.Return
+            The visited AST node.
+        """
         if isinstance(self.stack[-1], FunctionDocstringNode):
             self.stack[-1].return_statements.append(node)
         return node
 
     def process_file(self) -> None:
+        """Process a source code file, reporting on the missing docstrings."""
         self.visit(self.tree)
         self.report_missing_docstrings()

Original file line number	Diff line number	Diff line change
`@@ -106,3 +106,6 @@ exclude = [ # don't report on checks for these`
`106`	`106`	`'\.__repr__$',`
`107`	`107`	`'\.__str__$',`
`108`	`108`	`]`
	`109`	`+override_SS05 = [ # override SS05 to allow docstrings starting with these words`
	`110`	`+ '^Process ',`
	`111`	`+]`