docstringify 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

docstringify/__init__.py

@@ -3,4 +3,4 @@ Flag missing docstrings and, optionally, generate them from signatures and
 type annotations.
 """
 
-__version__ = '0.2.0'
+__version__ = '0.4.0'

docstringify/cli.py

@@ -2,14 +2,21 @@ from __future__ import annotations
 
 import argparse
 import sys
+from functools import partial
 from typing import Sequence
 
 from . import __version__
 from .converters import GoogleDocstringConverter, NumpydocDocstringConverter
-from .visitor import DocstringVisitor
+from .traversal import DocstringTransformer, DocstringVisitor
 
 PROG = __package__
 
+STYLES = {
+    'google': GoogleDocstringConverter,
+    'numpydoc': NumpydocDocstringConverter,
+}
+CLI_DEFAULTS = {'threshold': 1.0}
+
 
 def main(argv: Sequence[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog=PROG)
@@ -22,40 +29,55 @@ def main(argv: Sequence[str] | None = None) -> int:
         '--version', action='version', version=f'%(prog)s {__version__}'
     )
 
-    parser.add_argument(
+    run_group = parser.add_argument_group('Run options')
+    handle_missing_docstring = run_group.add_mutually_exclusive_group(required=False)
+    handle_missing_docstring.add_argument(
+        '--make-changes',
+        choices=STYLES.keys(),
+        help='Whether to insert docstring templates for items missing docstrings',
+    )
+    handle_missing_docstring.add_argument(
+        '--make-changes-inplace',
+        choices=STYLES.keys(),
+        help=(
+            'Whether to insert docstring templates for items missing docstrings, '
+            'overwriting the original file'
+        ),
+    )
+    handle_missing_docstring.add_argument(
         '--suggest-changes',
-        action='store_true',
+        choices=STYLES.keys(),
         help='Whether to print out docstring templates for items missing docstrings',
     )
-    parser.add_argument(
-        '--style',
-        choices=['google', 'numpydoc'],
-        default='numpydoc',
-        help='The style of docstring to use (only used when --suggest-changes is passed)',
-    )
-    parser.add_argument(
+    run_group.add_argument(
         '--threshold',
         type=float,
-        default=1,
+        default=CLI_DEFAULTS['threshold'],
         help='The percentage of docstrings that must be present to pass',
     )
     args = parser.parse_args(argv)
 
-    if args.style is None or not args.suggest_changes:
-        converter = None
-    elif args.style == 'google':
-        converter = GoogleDocstringConverter()
-    elif args.style == 'numpydoc':
-        converter = NumpydocDocstringConverter()
+    if style := args.make_changes or args.make_changes_inplace or args.suggest_changes:
+        converter = STYLES[style]
     else:
-        raise NotImplementedError(f'{args.style} is not a supported option')
+        converter = None
+
+    get_docstring_processor = (
+        partial(
+            DocstringTransformer,
+            converter=converter,
+            **{'overwrite': bool(args.make_changes_inplace)},
+        )
+        if args.make_changes or args.make_changes_inplace
+        else partial(DocstringVisitor, converter=converter)
+    )
 
     docstrings_processed = missing_docstrings = 0
     for file in args.filenames:
-        visitor = DocstringVisitor(file, converter=converter)
-        visitor.process_file()
-        missing_docstrings += visitor.missing_docstrings
-        docstrings_processed += visitor.docstrings_inspected
+        processor = get_docstring_processor(file)
+        processor.process_file()
+        missing_docstrings += processor.missing_docstrings
+        docstrings_processed += processor.docstrings_inspected
 
     if docstrings_processed and (
         missing_percentage := (missing_docstrings / docstrings_processed)

docstringify/converters/base.py

@@ -2,26 +2,36 @@
 
 from __future__ import annotations
 
+import ast
+import textwrap
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING
 
+from ..components import Function
+from ..exceptions import InvalidDocstringError
+
 if TYPE_CHECKING:
-    from ..components import Function, Parameter
+    from ..components import Parameter
+    from ..nodes.base import DocstringNode
 
 
 class DocstringConverter(ABC):
     def __init__(
-        self, parameters_section_template: str, returns_section_template: str
+        self,
+        parameters_section_template: str,
+        returns_section_template: str,
+        quote: bool,
     ) -> None:
         self.parameters_section_template = parameters_section_template
         self.returns_section_template = returns_section_template
+        self._quote = quote
 
     @abstractmethod
-    def to_class_docstring(self, class_name: str) -> str:
+    def to_class_docstring(self, class_name: str, indent: int) -> str:
         pass
 
     @abstractmethod
-    def to_function_docstring(self, function: Function) -> str:
+    def to_function_docstring(self, function: Function, indent: int) -> str:
         pass
 
     @abstractmethod
@@ -49,3 +59,36 @@ class DocstringConverter(ABC):
         if return_text := self.format_return(return_type):
             return self.returns_section_template.format(returns=return_text)
         return ''
+
+    def quote_docstring(self, docstring: str | list[str], indent: int) -> str:
+        quote = '"""' if self._quote else ''
+        prefix = sep = ''
+        if isinstance(docstring, str):
+            docstring = [quote, docstring, quote]
+        elif isinstance(docstring, list):
+            if len(docstring) > 1:
+                prefix = ' ' * indent if indent else ''
+                sep = '\n'
+            docstring = [quote, *docstring, f'{prefix}{quote}']
+        else:
+            raise InvalidDocstringError(type(docstring).__name__)
+
+        return textwrap.indent(sep.join(docstring), prefix)
+
+    def suggest_docstring(
+        self,
+        docstring_node: DocstringNode,
+        indent: int = 0,
+    ) -> str:
+        if isinstance(docstring_node.ast_node, ast.AsyncFunctionDef | ast.FunctionDef):
+            return self.to_function_docstring(
+                Function(
+                    docstring_node.extract_arguments(), docstring_node.extract_returns()
+                ),
+                indent=indent,
+            )
+
+        if isinstance(docstring_node.ast_node, ast.Module):
+            return self.to_module_docstring(docstring_node.module_name)
+
+        return self.to_class_docstring(docstring_node.name, indent=indent)

docstringify/converters/google.py

@@ -7,15 +7,15 @@ from .base import DocstringConverter
 
 
 class GoogleDocstringConverter(DocstringConverter):
-    def __init__(self) -> None:
+    def __init__(self, quote: bool) -> None:
         super().__init__(
             parameters_section_template='Args:\n{parameters}',
             returns_section_template='Returns:\n    {returns}',
+            quote=quote,
         )
 
-    def to_function_docstring(self, function: Function) -> str:
-        # TODO: the visitor needs the triple quotes but the transformer does not
-        docstring = [f'"""{DESCRIPTION_PLACEHOLDER}']
+    def to_function_docstring(self, function: Function, indent: int) -> str:
+        docstring = [DESCRIPTION_PLACEHOLDER]
 
         if parameters_section := self.parameters_section(function.parameters):
             docstring.extend(['', parameters_section])
@@ -23,14 +23,12 @@ class GoogleDocstringConverter(DocstringConverter):
         if returns_section := self.returns_section(function.return_type):
             docstring.extend(['', returns_section])
 
-        sep = '' if len(docstring) == 1 else '\n'
-
-        return sep.join([*docstring, '"""'])
+        return self.quote_docstring(docstring, indent=indent)
 
     def format_parameter(self, parameter: Parameter) -> str:
         category = f'{f", {parameter.category}" if parameter.category else ""}'
         return (
-            f'    {parameter.name} ({parameter.type_}{category}): {DESCRIPTION_PLACEHOLDER} '
+            f'    {parameter.name} ({parameter.type_}{category}): {DESCRIPTION_PLACEHOLDER}'
             f'{f" Defaults to {parameter.default}." if parameter.default != NO_DEFAULT else ""}'
         )
 
@@ -40,7 +38,7 @@ class GoogleDocstringConverter(DocstringConverter):
         return ''
 
     def to_module_docstring(self, module_name: str) -> str:
-        return f'"""{DESCRIPTION_PLACEHOLDER}"""'
+        return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=0)
 
-    def to_class_docstring(self, class_name: str) -> str:
-        return f'"""{DESCRIPTION_PLACEHOLDER}"""'
+    def to_class_docstring(self, class_name: str, indent: int) -> str:
+        return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=indent)

docstringify/converters/numpydoc.py

@@ -7,15 +7,15 @@ from .base import DocstringConverter
 
 
 class NumpydocDocstringConverter(DocstringConverter):
-    def __init__(self) -> None:
+    def __init__(self, quote: bool) -> None:
         super().__init__(
             parameters_section_template='Parameters\n----------\n{parameters}',
             returns_section_template='Returns\n-------\n{returns}',
+            quote=quote,
         )
 
-    def to_function_docstring(self, function: Function) -> str:
-        # TODO: the visitor needs the triple quotes but the transformer does not
-        docstring = ['"""', DESCRIPTION_PLACEHOLDER]
+    def to_function_docstring(self, function: Function, indent: int) -> str:
+        docstring = [DESCRIPTION_PLACEHOLDER]
 
         if parameters_section := self.parameters_section(function.parameters):
             docstring.extend(['', parameters_section])
@@ -23,9 +23,7 @@ class NumpydocDocstringConverter(DocstringConverter):
         if returns_section := self.returns_section(function.return_type):
             docstring.extend(['', returns_section])
 
-        sep = '' if len(docstring) == 2 else '\n'
-
-        return sep.join([*docstring, '"""'])
+        return self.quote_docstring(docstring, indent=indent)
 
     def format_parameter(self, parameter: Parameter) -> str:
         return (
@@ -41,7 +39,7 @@ class NumpydocDocstringConverter(DocstringConverter):
         return ''
 
     def to_module_docstring(self, module_name: str) -> str:
-        return f'"""{DESCRIPTION_PLACEHOLDER}"""'
+        return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=0)
 
-    def to_class_docstring(self, class_name: str) -> str:
-        return f'"""{DESCRIPTION_PLACEHOLDER}"""'
+    def to_class_docstring(self, class_name: str, indent: int) -> str:
+        return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=indent)

docstringify/exceptions.py

@@ -0,0 +1,6 @@
+"""Docstringify exceptions."""
+
+
+class InvalidDocstringError(ValueError):
+    def __init__(self, docstring_class: str) -> None:
+        super().__init__(f'Expected str or list[str] docstring, got {docstring_class}')

docstringify/nodes/__init__.py

@@ -0,0 +1 @@
+"""Docstringify nodes."""

docstringify/nodes/base.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import ast
+from functools import partial
+from typing import Callable, overload
+
+
+class DocstringNode:
+    @overload
+    def __init__(
+        self,
+        node: ast.Module,
+        module_name: str,
+        source_code: str,
+        parent: None = None,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        node: ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef,
+        module_name: str,
+        source_code: str,
+        parent: DocstringNode,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        node: ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef,
+        module_name: str,
+        source_code: str,
+        parent: DocstringNode | None = None,
+    ) -> None:
+        self.module_name: str = module_name
+        self.parent: DocstringNode | None = parent
+
+        self.ast_node: (
+            ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef
+        ) = node
+        self.name: str = getattr(node, 'name', self.module_name)
+
+        self.docstring = ast.get_docstring(node)
+        self.get_source_segment: Callable[[ast.AST], str] = partial(
+            ast.get_source_segment, source_code
+        )
+
+    @property
+    def fully_qualified_name(self) -> str:
+        return (
+            f'{self.parent.fully_qualified_name}.{self.name}'
+            if self.parent
+            else self.name
+        )

docstringify/nodes/function.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import ast
+import itertools
+from typing import Literal
+
+from ..components import (
+    NO_DEFAULT,
+    PARAMETER_TYPE_PLACEHOLDER,
+    RETURN_TYPE_PLACEHOLDER,
+    Parameter,
+)
+from .base import DocstringNode
+
+
+class FunctionDocstringNode(DocstringNode):
+    def __init__(
+        self,
+        node: ast.FunctionDef | ast.AsyncFunctionDef,
+        module_name: str,
+        source_code: str,
+        parent: DocstringNode,
+    ) -> None:
+        super().__init__(node, module_name, source_code, parent)
+        self.decorators: list[str] = [
+            self.get_source_segment(decorator) for decorator in node.decorator_list
+        ]
+
+        self.is_method: bool = self.parent and isinstance(
+            self.parent.ast_node, ast.ClassDef
+        )
+        self.is_abstract_method: bool = self.is_method and (
+            'abstractmethod' in self.decorators
+            or 'abc.abstractmethod' in self.decorators
+        )
+        self.is_class_method: bool = self.is_method and 'classmethod' in self.decorators
+        self.is_static_method: bool = (
+            self.is_method and 'staticmethod' in self.decorators
+        )
+        self.is_instance_method: bool = (
+            self.is_method and not self.is_class_method and not self.is_static_method
+        )
+
+        self.arguments: ast.arguments | None = getattr(node, 'args', None)
+        self.return_annotation: str | None = self._extract_return_annotation()
+        self.return_statements: list[ast.Return] = []
+
+    def _extract_default_values(
+        self, default: ast.Constant | None | Literal[NO_DEFAULT], is_keyword_only: bool
+    ) -> str | Literal[NO_DEFAULT]:
+        if (not is_keyword_only and default is not NO_DEFAULT) or (
+            is_keyword_only and default
+        ):
+            try:
+                default_value = default.value
+            except AttributeError:
+                default_value = f'`{default.id}`'
+
+            return (
+                f'"{default_value}"'
+                if isinstance(default_value, str) and not default_value.startswith('`')
+                else default_value
+            )
+        return NO_DEFAULT
+
+    def _extract_star_args(self) -> list[Parameter | None, Parameter | None]:
+        return [
+            Parameter(
+                name=f'*{arg.arg}' if arg_type == 'vararg' else f'**{arg.arg}',
+                type_=getattr(arg.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER),
+                category=None,
+                default=NO_DEFAULT,
+            )
+            if arg
+            else None
+            for arg_type in ['vararg', 'kwarg']
+            for arg in [getattr(self.arguments, arg_type)]
+        ]
+
+    def _extract_positional_args(self) -> list[Parameter, ...]:
+        if (default_count := len(positional_defaults := self.arguments.defaults)) < (
+            positional_arguments_count := len(self.arguments.posonlyargs)
+            + len(self.arguments.args)
+        ):
+            positional_defaults = [NO_DEFAULT] * (
+                positional_arguments_count - default_count
+            ) + positional_defaults
+
+        return [
+            Parameter(
+                name=arg.arg,
+                type_=getattr(arg.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER),
+                category=category,
+                default=self._extract_default_values(default, False),
+            )
+            for (arg, category), default in zip(
+                itertools.chain(
+                    zip(
+                        self.arguments.posonlyargs, itertools.repeat('positional-only')
+                    ),
+                    zip(self.arguments.args, itertools.repeat(None)),
+                ),
+                positional_defaults,
+            )
+        ]
+
+    def _extract_keyword_args(self) -> list[Parameter, ...]:
+        return [
+            Parameter(
+                name=arg.arg,
+                type_=getattr(arg.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER),
+                category='keyword-only',
+                default=self._extract_default_values(default, True),
+            )
+            for arg, default in zip(
+                self.arguments.kwonlyargs, self.arguments.kw_defaults
+            )
+        ]
+
+    def extract_arguments(self) -> tuple[Parameter, ...]:
+        params = self._extract_positional_args()
+
+        varargs, kwargs = self._extract_star_args()
+
+        if varargs:
+            params.append(varargs)
+
+        params.extend(self._extract_keyword_args())
+
+        if kwargs:
+            params.append(kwargs)
+
+        params = tuple(params)
+        if params and (
+            (self.is_class_method and params[0].name == 'cls')
+            or (self.is_instance_method and params[0].name == 'self')
+        ):
+            return params[1:]
+        return params
+
+    def _extract_return_annotation(self) -> str | None:
+        if return_annotation_node := self.ast_node.returns:
+            if isinstance(return_annotation_node, ast.Constant):
+                return return_annotation_node.value
+            if isinstance(return_annotation_node, ast.Name):
+                return return_annotation_node.id
+            return self.get_source_segment(return_annotation_node)
+        return None
+
+    def extract_returns(self) -> str | None:
+        if self.return_annotation:
+            return self.return_annotation
+        if any(
+            not isinstance(return_value := return_node.value, ast.Constant)
+            or return_value.value
+            for return_node in self.return_statements
+        ):
+            return RETURN_TYPE_PLACEHOLDER
+        return None

docstringify/traversal/__init__.py

@@ -0,0 +1,9 @@
+"""AST traversal for docstrings."""
+
+from .transformer import DocstringTransformer
+from .visitor import DocstringVisitor
+
+__all__ = [
+    'DocstringTransformer',
+    'DocstringVisitor',
+]

docstringify/traversal/transformer.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING
+
+from .visitor import DocstringVisitor
+
+if TYPE_CHECKING:
+    from ..converters import DocstringConverter
+    from ..nodes.base import DocstringNode
+
+
+class DocstringTransformer(ast.NodeTransformer, DocstringVisitor):
+    def __init__(
+        self,
+        filename: str,
+        converter: type[DocstringConverter],
+        overwrite: bool = False,
+    ) -> None:
+        super().__init__(filename, converter)
+        self.overwrite = overwrite
+
+    def save(self) -> None:
+        if self.missing_docstrings:
+            output = (
+                self.source_file
+                if self.overwrite
+                else self.source_file.parent
+                / (
+                    self.source_file.stem
+                    + '_docstringify'
+                    + ''.join(self.source_file.suffixes)
+                )
+            )
+            edited_code = ast.unparse(self.tree)
+            output.write_text(edited_code)
+            print(f'Docstring templates written to {output}')
+
+    def handle_missing_docstring(self, docstring_node: DocstringNode) -> DocstringNode:
+        suggested_docstring = self.docstring_converter.suggest_docstring(
+            docstring_node,
+            indent=0
+            if isinstance(docstring_node.ast_node, ast.Module)
+            else docstring_node.ast_node.col_offset + 4,
+        )
+        docstring_ast_node = ast.Expr(ast.Constant(suggested_docstring))
+
+        if (
+            docstring_node.docstring is not None
+            and docstring_node.docstring.strip() == ''
+        ):
+            # If the docstring is empty, we replace it with the suggested docstring
+            docstring_node.ast_node.body[0] = docstring_ast_node
+        else:
+            # If the docstring is missing, we insert the suggested docstring
+            docstring_node.ast_node.body.insert(0, docstring_ast_node)
+
+        docstring_node.ast_node = ast.fix_missing_locations(docstring_node.ast_node)
+
+        return docstring_node
+
+    def process_file(self) -> None:
+        super().process_file()
+        self.save()

docstringify/traversal/visitor.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ..nodes.base import DocstringNode
+from ..nodes.function import FunctionDocstringNode
+
+if TYPE_CHECKING:
+    from ..converters import DocstringConverter
+
+
+class DocstringVisitor(ast.NodeVisitor):
+    def __init__(
+        self, filename: str, converter: type[DocstringConverter] | None = None
+    ) -> None:
+        self.source_file: Path = Path(filename).expanduser().resolve()
+        self.source_code: str = self.source_file.read_text()
+        self.tree: ast.Module = ast.parse(self.source_code)
+
+        self.docstrings_inspected: int = 0
+        self.missing_docstrings: list[DocstringNode] = []
+
+        self.module_name: str = self.source_file.stem
+        self.stack: list[DocstringNode] = []
+
+        self.docstring_converter: DocstringConverter | None = (
+            converter(quote=not issubclass(self.__class__, ast.NodeTransformer))
+            if converter
+            else None
+        )
+
+    def report_missing_docstrings(self) -> None:
+        if not self.missing_docstrings:
+            print(f'No missing docstrings found in {self.source_file}.')
+        else:
+            for docstring_node in self.missing_docstrings:
+                # TODO: need to print full path for node name
+                print(
+                    f'{docstring_node.fully_qualified_name} is missing a docstring',
+                    file=sys.stderr,
+                )
+                self.handle_missing_docstring(docstring_node)
+
+    def handle_missing_docstring(self, docstring_node: DocstringNode) -> DocstringNode:
+        if self.docstring_converter:
+            print('Hint:')
+            print(self.docstring_converter.suggest_docstring(docstring_node))
+            print()
+
+    def process_docstring(self, docstring_node: DocstringNode) -> DocstringNode:
+        if docstring_node.docstring is None or docstring_node.docstring.strip() == '':
+            self.missing_docstrings.append(docstring_node)
+
+        self.docstrings_inspected += 1
+        return docstring_node
+
+    def visit_docstring(
+        self,
+        node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module,
+        docstring_class: type[DocstringNode],
+    ) -> ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module:
+        docstring_node = docstring_class(
+            node,
+            self.module_name,
+            self.source_code,
+            parent=self.stack[-1] if self.stack else None,
+        )
+
+        self.stack.append(docstring_node)
+
+        docstring_node = self.process_docstring(docstring_node)
+        self.generic_visit(docstring_node.ast_node)
+        self.stack.pop()
+        return docstring_node.ast_node
+
+    def visit_Module(self, node: ast.Module) -> ast.Module:  # noqa: N802
+        return self.visit_docstring(node, DocstringNode)
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> ast.ClassDef:  # noqa: N802
+        return self.visit_docstring(node, DocstringNode)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef:  # noqa: N802
+        return self.visit_docstring(node, FunctionDocstringNode)
+
+    def visit_AsyncFunctionDef(  # noqa: N802
+        self, node: ast.AsyncFunctionDef
+    ) -> ast.AsyncFunctionDef:
+        return self.visit_docstring(node, FunctionDocstringNode)
+
+    def visit_Return(self, node: ast.Return) -> ast.Return:  # noqa: N802
+        if isinstance(self.stack[-1], FunctionDocstringNode):
+            self.stack[-1].return_statements.append(node)
+        return node
+
+    def process_file(self) -> None:
+        self.visit(self.tree)
+        self.report_missing_docstrings()

{docstringify-0.2.0.dist-info → docstringify-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.2.0
+Version: 0.4.0
 Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
 License: MIT License
@@ -60,7 +60,7 @@ Add the following to your `.pre-commit-config.yaml` file to block commits with m
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.2.0
+  rev: 0.4.0
   hooks:
     - id: docstringify
 ```
@@ -69,32 +69,34 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.2.0
+  rev: 0.4.0
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
 ```
 
-If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument. By default, these will be [numpydoc-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#):
+If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google` and `numpydoc`). Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.2.0
+  rev: 0.4.0
   hooks:
     - id: docstringify
-      args: [--suggest-changes]
+      args: [--suggest-changes=numpydoc]
 ```
 
-For [Google-style docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html), specify `--style google`:
+Use `--make-changes` to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html):
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.2.0
+  rev: 0.4.0
   hooks:
     - id: docstringify
-      args: [--suggest-changes, --style=google]
+      args: [--make-changes=google]
 ```
 
+If you want the changes to be made in place, change `--make-changes` to `--make-changes-inplace` &ndash; make sure you only operate on files that are in version control with this setting. Note that the resulting format of your file may be a little different (spacing, newlines, *etc.*).
+
 Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
 
 ### Command line
@@ -124,7 +126,7 @@ $ python -m pip install docstringify
 Then, use the `DocstringVisitor()` class on individual files to see spots where docstrings are missing:
 
 ```pycon
->>> from docstringify.visitor import DocstringVisitor
+>>> from docstringify.traversal import DocstringVisitor
 >>> visitor = DocstringVisitor('test.py')
 >>> visitor.process_file()
 test is missing a docstring
@@ -135,8 +137,8 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```pycon
 >>> from docstringify.converters import NumpydocDocstringConverter
->>> from docstringify.visitor import DocstringVisitor
->>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter())
+>>> from docstringify.traversal import DocstringVisitor
+>>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)
 >>> visitor.process_file()
 test is missing a docstring
 Hint:
@@ -154,3 +156,17 @@ name : str, default="World"
 """
 
 ```
+
+To make changes to your files, you will need to use the `DocstringTransformer` instead. With the `DocstringTransformer`, the converter is required:
+
+```pycon
+>>> from docstringify.converters import GoogleDocstringConverter
+>>> from docstringify.traversal import DocstringTransformer
+>>> transformer = DocstringTransformer('test.py', converter=GoogleDocstringConverter)
+>>> transformer.process_file()
+test is missing a docstring
+test.say_hello is missing a docstring
+Docstring templates written to /.../test_docstringify.py
+```
+
+If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`.

docstringify-0.4.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+docstringify/__init__.py,sha256=ORdK5paDVN7Lbf_kfyo-3tlnIQvFidCXMqyn70WhisI,124
+docstringify/__main__.py,sha256=A5Xq9jCZwHnQVVGklF9ueL-ad-hInsceHQNgze3Yq6E,96
+docstringify/cli.py,sha256=0zUoDDj8f60NDw5cnL_otSiymorMIwq5XfaJbRCrEHQ,2986
+docstringify/components.py,sha256=7Q__cuBTWNAqLDTil_91Q7T-zIzr7YpbX2TcmXrfph0,471
+docstringify/exceptions.py,sha256=lt9p6bUGGqwsKCBk0hv4LrMqOLzNuk-E_3rXgjVKGpc,216
+docstringify/converters/__init__.py,sha256=iZXA6m689j3yqpfZjkoAcONXxAR7s-4GUQFEYxDPAyc,267
+docstringify/converters/base.py,sha256=nIUgfGTjwFSXqcGHfEm3iljo4YcsteCs7iL5o5BNceY,2989
+docstringify/converters/google.py,sha256=puOCpmCK4InimfjR8TAcvCT_ZdpF_U0z_4E8a5l1UWk,1738
+docstringify/converters/numpydoc.py,sha256=VDQGvknBJMP9o6D9wh3cKsL7-uGNuDP4Ow7C3-Tf08c,1762
+docstringify/nodes/__init__.py,sha256=nNCajaWkQJGRv5cKdWyo43JDfSsBUrlnCL8JRTaW4cI,26
+docstringify/nodes/base.py,sha256=JMAHvJm7FRl-NmP6hbO8QzgTMHqT-5DnVo8C5-xSLeo,1415
+docstringify/nodes/function.py,sha256=HfkAHy5Mb6--mxtR-6Swpd9iw_qfdzdH-wkN2lJy5T0,5593
+docstringify/traversal/__init__.py,sha256=fy9DEvmXm4sJyf4dAJI-patQPoL8_zPgPpda84q0a-4,188
+docstringify/traversal/transformer.py,sha256=SvyLQsQ3WrOKFSzIPYegA6vacp7Tp1gjNdPAFwoH8jg,2130
+docstringify/traversal/visitor.py,sha256=Uewzh4esB9XY5tQ9QfRt1TbwDEpIq4kW7Kdqm8E4IDA,3688
+docstringify-0.4.0.dist-info/licenses/LICENSE,sha256=E5RHv_qfCZPwnlJ_ZQb-WKOOy07LaJBA2a160OGtT3U,1071
+docstringify-0.4.0.dist-info/METADATA,sha256=wUOlXNPNwUyszzYWhPvtZZqn7thccQvN77PIjiVrlzA,6448
+docstringify-0.4.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+docstringify-0.4.0.dist-info/entry_points.txt,sha256=dJVPsbclB7stLE8g0d4WbO2NaZQLJXSLEVl6oeROAqI,55
+docstringify-0.4.0.dist-info/top_level.txt,sha256=3RFmaFG0rYs4HkqRljatGQtY4BcNN7mqjK4tSznYdnQ,13
+docstringify-0.4.0.dist-info/RECORD,,

docstringify/visitor.py

@@ -1,196 +0,0 @@
-from __future__ import annotations
-
-import ast
-import sys
-from pathlib import Path
-from typing import TYPE_CHECKING, Literal
-
-from .components import (
-    NO_DEFAULT,
-    PARAMETER_TYPE_PLACEHOLDER,
-    RETURN_TYPE_PLACEHOLDER,
-    Function,
-    Parameter,
-)
-
-if TYPE_CHECKING:
-    from .converters import DocstringConverter
-
-
-class DocstringVisitor(ast.NodeVisitor):
-    def __init__(
-        self, filename: str, converter: DocstringConverter | None = None
-    ) -> None:
-        self.source_file: Path = Path(filename)
-        self.source_code: str = self.source_file.read_text()
-
-        self.docstrings_inspected: int = 0
-        self.missing_docstrings: int = 0
-
-        self.module_name: str = self.source_file.stem
-        self.stack: list[str] = []
-
-        self.provide_hints: bool = converter is not None
-        if self.provide_hints:
-            self.converter: DocstringVisitor = converter  # TODO: consider whether this should be instantiated here instead of outside
-
-    def _extract_default_values(
-        self, default: ast.Constant | None | Literal[NO_DEFAULT], is_keyword_only: bool
-    ) -> str | Literal[NO_DEFAULT]:
-        if (not is_keyword_only and default is not NO_DEFAULT) or (
-            is_keyword_only and default
-        ):
-            try:
-                default_value = default.value
-            except AttributeError:
-                default_value = f'`{default.id}`'
-
-            return (
-                f'"{default_value}"'
-                if isinstance(default_value, str) and not default_value.startswith('`')
-                else default_value
-            )
-        return NO_DEFAULT
-
-    def extract_arguments(
-        self, node: ast.AsyncFunctionDef | ast.FunctionDef
-    ) -> tuple[Parameter, ...]:
-        modifiers = {
-            'posonlyargs': 'positional-only',
-            'kwonlyargs': 'keyword-only',
-        }
-        params = []
-
-        positional_arguments_count = len(node.args.posonlyargs) + len(node.args.args)
-        if (
-            default_count := len(positional_defaults := node.args.defaults)
-        ) < positional_arguments_count:
-            positional_defaults = [NO_DEFAULT] * (
-                positional_arguments_count - default_count
-            ) + positional_defaults
-
-        keyword_defaults = node.args.kw_defaults
-
-        processed_positional_args = 0
-        for arg_type, args in ast.iter_fields(node.args):
-            if arg_type.endswith('defaults'):
-                continue
-            modifier = modifiers.get(arg_type)
-            if arg_type in ['vararg', 'kwarg']:
-                if args:
-                    params.append(
-                        Parameter(
-                            name=f'*{args.arg}'
-                            if arg_type == 'vararg'
-                            else f'**{args.arg}',
-                            type_=getattr(
-                                args.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER
-                            ),
-                            category=modifier,
-                            default=NO_DEFAULT,
-                        )
-                    )
-            else:
-                is_keyword_only = arg_type.startswith('kw')
-                params.extend(
-                    [
-                        Parameter(
-                            name=arg.arg,
-                            type_=getattr(
-                                arg.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER
-                            ),
-                            category=modifier,
-                            default=self._extract_default_values(
-                                default, is_keyword_only
-                            ),
-                        )
-                        for arg, default in zip(
-                            args,
-                            keyword_defaults
-                            if is_keyword_only
-                            else positional_defaults[processed_positional_args:],
-                        )
-                    ]
-                )
-                if not is_keyword_only:
-                    processed_positional_args += len(args)
-
-        params = tuple(params)
-        if (
-            params
-            and isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef)
-            and params[0].name.startswith(('self', 'cls'))
-        ):
-            return params[1:]
-        return params
-
-    def extract_returns(
-        self, node: ast.AsyncFunctionDef | ast.FunctionDef
-    ) -> str | None:
-        if return_node := node.returns:
-            if isinstance(return_node, ast.Constant):
-                return return_node.value
-            if isinstance(return_node, ast.Name):
-                return return_node.id
-            return ast.get_source_segment(self.source_code, return_node)
-        if (
-            return_nodes := [
-                body_node
-                for body_node in node.body
-                if isinstance(body_node, ast.Return)
-            ]
-        ) and any(
-            not isinstance(return_value := body_return_node.value, ast.Constant)
-            or return_value.value
-            for body_return_node in return_nodes
-        ):
-            return RETURN_TYPE_PLACEHOLDER
-        return return_node
-
-    def report_missing_docstring(self) -> None:
-        self.missing_docstrings += 1
-        print(f'{".".join(self.stack)} is missing a docstring', file=sys.stderr)
-
-    def suggest_docstring(
-        self, node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
-    ) -> str:
-        if isinstance(node, ast.AsyncFunctionDef | ast.FunctionDef):
-            return self.converter.to_function_docstring(
-                Function(self.extract_arguments(node), self.extract_returns(node))
-            )
-
-        if isinstance(node, ast.Module):
-            return self.converter.to_module_docstring(self.module_name)
-
-        # TODO: with the stack, I should be able to let __init__() not have a docstring
-        # and suggest those parameters as the docstring for the class
-        # (may need to keep the class node in another stack)
-        return self.converter.to_class_docstring(node.name)
-
-    def process_docstring(
-        self, node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
-    ) -> None:
-        if not ast.get_docstring(node):
-            self.report_missing_docstring()
-            if self.provide_hints:
-                print('Hint:')
-                print(self.suggest_docstring(node))
-                print()
-
-        self.docstrings_inspected += 1
-
-    def visit(self, node: ast.AST) -> None:
-        if isinstance(
-            node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
-        ):
-            self.stack.append(
-                self.module_name if isinstance(node, ast.Module) else node.name
-            )
-
-            self.process_docstring(node)
-
-            self.generic_visit(node)
-            _ = self.stack.pop()
-
-    def process_file(self) -> None:
-        self.visit(ast.parse(self.source_code))

docstringify-0.2.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-docstringify/__init__.py,sha256=F8wAs3yjndnNfOVnCZIiCk86BQIwxiAGx7fXe15mxNE,124
-docstringify/__main__.py,sha256=A5Xq9jCZwHnQVVGklF9ueL-ad-hInsceHQNgze3Yq6E,96
-docstringify/cli.py,sha256=U2G97RihJC2HMR2MCWDNadcU5erBuFDlIDrIOQ4lJSM,2230
-docstringify/components.py,sha256=7Q__cuBTWNAqLDTil_91Q7T-zIzr7YpbX2TcmXrfph0,471
-docstringify/visitor.py,sha256=qF6T6lqbK93RArbkDhqZYOQNAuvi6miMehO0U9tdNJM,7019
-docstringify/converters/__init__.py,sha256=iZXA6m689j3yqpfZjkoAcONXxAR7s-4GUQFEYxDPAyc,267
-docstringify/converters/base.py,sha256=1QWFE5ckS_Rbwi9TyRM-rKCA7MCwHgZ4Ok8ugMyvMgA,1507
-docstringify/converters/google.py,sha256=ytel_pqqUNV5wR8nVV1F8yczFA3Tj1f9_nkfJA4Kq04,1751
-docstringify/converters/numpydoc.py,sha256=iv5smFrHFBc0rHvLhgh66PaV2OEI3va_piRZ3_y2Ig8,1773
-docstringify-0.2.0.dist-info/licenses/LICENSE,sha256=E5RHv_qfCZPwnlJ_ZQb-WKOOy07LaJBA2a160OGtT3U,1071
-docstringify-0.2.0.dist-info/METADATA,sha256=QvPrAwX5TnbG6y7XpK6grHqohENJ2doN3i0WiHipECk,5362
-docstringify-0.2.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-docstringify-0.2.0.dist-info/entry_points.txt,sha256=dJVPsbclB7stLE8g0d4WbO2NaZQLJXSLEVl6oeROAqI,55
-docstringify-0.2.0.dist-info/top_level.txt,sha256=3RFmaFG0rYs4HkqRljatGQtY4BcNN7mqjK4tSznYdnQ,13
-docstringify-0.2.0.dist-info/RECORD,,