docstringify 0.3.0__tar.gz → 0.5.0__tar.gz

docstringify-0.5.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Something isn't working
+title: "[BUG] "
+labels: bug
+assignees: ''
+
+---
+
+**Required attestation**
+- [ ] I have checked that this issue has not already been reported.
+- [ ] I have confirmed this bug exists on the latest version of docstringify.
+- [ ] I have confirmed this bug exists on the `main` branch of docstringify.
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment**
+- OS: [e.g. iOS]
+- Python Version [e.g. 3.12]
+
+**Additional context**
+Add any other context about the problem here.

docstringify-0.5.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

docstringify-0.5.0/.github/workflows/greetings.yml

@@ -0,0 +1,16 @@
+name: Greetings
+
+on: [pull_request_target, issues]
+
+jobs:
+  greeting:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+    - uses: actions/first-interaction@34f15e814fe48ac9312ccf29db4e74fa767cbab7  # v1.3.0
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        issue-message: "It looks like this is your first issue here – welcome! Please familiarize yourself with the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md), if you haven't already."
+        pr-message: "Congratulations on making your first pull request to `docstringify`! Please familiarize yourself with the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md), if you haven't already."

{docstringify-0.3.0 → docstringify-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.3.0
+Version: 0.5.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.3.0
+  rev: 0.5.0
   hooks:
     - id: docstringify
 ```
@@ -69,7 +69,7 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.3.0
+  rev: 0.5.0
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
@@ -79,7 +79,7 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.3.0
+  rev: 0.5.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -89,7 +89,7 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.3.0
+  rev: 0.5.0
   hooks:
     - id: docstringify
       args: [--make-changes=google]
@@ -126,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
@@ -137,9 +137,9 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```pycon
 >>> from docstringify.converters import NumpydocDocstringConverter
->>> from docstringify.visitor import DocstringVisitor
+>>> from docstringify.traversal import DocstringVisitor
 >>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)
->>> _ = visitor.process_file()
+>>> visitor.process_file()
 test is missing a docstring
 Hint:
 """__description__"""
@@ -161,9 +161,9 @@ To make changes to your files, you will need to use the `DocstringTransformer` i
 
 ```pycon
 >>> from docstringify.converters import GoogleDocstringConverter
->>> from docstringify.transformer import DocstringTransformer
+>>> from docstringify.traversal import DocstringTransformer
 >>> transformer = DocstringTransformer('test.py', converter=GoogleDocstringConverter)
->>> _ = transformer.process_file()
+>>> transformer.process_file()
 test is missing a docstring
 test.say_hello is missing a docstring
 Docstring templates written to /.../test_docstringify.py

{docstringify-0.3.0 → docstringify-0.5.0}/README.md

@@ -9,7 +9,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.3.0
+  rev: 0.5.0
   hooks:
     - id: docstringify
 ```
@@ -18,7 +18,7 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.3.0
+  rev: 0.5.0
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
@@ -28,7 +28,7 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.3.0
+  rev: 0.5.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -38,7 +38,7 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.3.0
+  rev: 0.5.0
   hooks:
     - id: docstringify
       args: [--make-changes=google]
@@ -75,7 +75,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
@@ -86,9 +86,9 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```pycon
 >>> from docstringify.converters import NumpydocDocstringConverter
->>> from docstringify.visitor import DocstringVisitor
+>>> from docstringify.traversal import DocstringVisitor
 >>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)
->>> _ = visitor.process_file()
+>>> visitor.process_file()
 test is missing a docstring
 Hint:
 """__description__"""
@@ -110,9 +110,9 @@ To make changes to your files, you will need to use the `DocstringTransformer` i
 
 ```pycon
 >>> from docstringify.converters import GoogleDocstringConverter
->>> from docstringify.transformer import DocstringTransformer
+>>> from docstringify.traversal import DocstringTransformer
 >>> transformer = DocstringTransformer('test.py', converter=GoogleDocstringConverter)
->>> _ = transformer.process_file()
+>>> transformer.process_file()
 test is missing a docstring
 test.say_hello is missing a docstring
 Docstring templates written to /.../test_docstringify.py

{docstringify-0.3.0 → docstringify-0.5.0}/src/docstringify/__init__.py

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

{docstringify-0.3.0 → docstringify-0.5.0}/src/docstringify/cli.py

@@ -7,8 +7,7 @@ from typing import Sequence
 
 from . import __version__
 from .converters import GoogleDocstringConverter, NumpydocDocstringConverter
-from .transformer import DocstringTransformer
-from .visitor import DocstringVisitor
+from .traversal import DocstringTransformer, DocstringVisitor
 
 PROG = __package__
 
@@ -77,13 +76,13 @@ def main(argv: Sequence[str] | None = None) -> int:
     for file in args.filenames:
         processor = get_docstring_processor(file)
         processor.process_file()
-        missing_docstrings += processor.missing_docstrings
+        missing_docstrings += len(processor.missing_docstrings)
         docstrings_processed += processor.docstrings_inspected
 
     if docstrings_processed and (
         missing_percentage := (missing_docstrings / docstrings_processed)
     ) > (1 - args.threshold):
-        print(f'\nMissing {missing_percentage:.0%} of docstrings', file=sys.stderr)
+        print(f'Missing {missing_percentage:.0%} of docstrings', file=sys.stderr)
         print(
             f'Your settings require {args.threshold:.0%} of docstrings to be present',
             file=sys.stderr,

{docstringify-0.3.0 → docstringify-0.5.0}/src/docstringify/converters/base.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import ast
 import textwrap
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING
@@ -9,7 +10,8 @@ from typing import TYPE_CHECKING
 from ..exceptions import InvalidDocstringError
 
 if TYPE_CHECKING:
-    from ..components import Function, Parameter
+    from ..components import Parameter
+    from ..nodes.base import DocstringNode
 
 
 class DocstringConverter(ABC):
@@ -24,15 +26,15 @@ class DocstringConverter(ABC):
         self._quote = quote
 
     @abstractmethod
-    def to_class_docstring(self, class_name: str, indent: int) -> str:
+    def to_class_docstring(self, docstring_node: DocstringNode, indent: int) -> str:
         pass
 
     @abstractmethod
-    def to_function_docstring(self, function: Function, indent: int) -> str:
+    def to_function_docstring(self, docstring_node: DocstringNode, indent: int) -> str:
         pass
 
     @abstractmethod
-    def to_module_docstring(self, module_name: str) -> str:
+    def to_module_docstring(self, docstring_node: DocstringNode) -> str:
         pass
 
     @abstractmethod
@@ -71,3 +73,20 @@ class DocstringConverter(ABC):
             raise InvalidDocstringError(type(docstring).__name__)
 
         return textwrap.indent(sep.join(docstring), prefix)
+
+    def suggest_docstring(
+        self,
+        docstring_node: DocstringNode,
+        indent: int = 0,
+    ) -> str | None:
+        if isinstance(docstring_node.ast_node, ast.AsyncFunctionDef | ast.FunctionDef):
+            return (
+                self.to_function_docstring(docstring_node, indent=indent)
+                if docstring_node.docstring_required
+                else None
+            )
+
+        if isinstance(docstring_node.ast_node, ast.Module):
+            return self.to_module_docstring(docstring_node)
+
+        return self.to_class_docstring(docstring_node, indent=indent)

{docstringify-0.3.0 → docstringify-0.5.0}/src/docstringify/converters/google.py

@@ -2,9 +2,15 @@
 
 from __future__ import annotations
 
-from ..components import DESCRIPTION_PLACEHOLDER, NO_DEFAULT, Function, Parameter
+from typing import TYPE_CHECKING
+
+from ..components import DESCRIPTION_PLACEHOLDER, NO_DEFAULT, Parameter
 from .base import DocstringConverter
 
+if TYPE_CHECKING:
+    from ..nodes.base import DocstringNode
+    from ..nodes.function import FunctionDocstringNode
+
 
 class GoogleDocstringConverter(DocstringConverter):
     def __init__(self, quote: bool) -> None:
@@ -14,7 +20,11 @@ class GoogleDocstringConverter(DocstringConverter):
             quote=quote,
         )
 
-    def to_function_docstring(self, function: Function, indent: int) -> str:
+    def to_function_docstring(
+        self, docstring_node: FunctionDocstringNode, indent: int
+    ) -> str:
+        function = docstring_node.to_function()
+
         docstring = [DESCRIPTION_PLACEHOLDER]
 
         if parameters_section := self.parameters_section(function.parameters):
@@ -37,8 +47,8 @@ class GoogleDocstringConverter(DocstringConverter):
             return f'{return_type}: {DESCRIPTION_PLACEHOLDER}'
         return ''
 
-    def to_module_docstring(self, module_name: str) -> str:
+    def to_module_docstring(self, docstring_node: DocstringNode) -> str:
         return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=0)
 
-    def to_class_docstring(self, class_name: str, indent: int) -> str:
+    def to_class_docstring(self, docstring_node: DocstringNode, indent: int) -> str:
         return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=indent)

{docstringify-0.3.0 → docstringify-0.5.0}/src/docstringify/converters/numpydoc.py

@@ -2,9 +2,15 @@
 
 from __future__ import annotations
 
-from ..components import DESCRIPTION_PLACEHOLDER, NO_DEFAULT, Function, Parameter
+from typing import TYPE_CHECKING
+
+from ..components import DESCRIPTION_PLACEHOLDER, NO_DEFAULT, Parameter
 from .base import DocstringConverter
 
+if TYPE_CHECKING:
+    from ..nodes.base import DocstringNode
+    from ..nodes.function import FunctionDocstringNode
+
 
 class NumpydocDocstringConverter(DocstringConverter):
     def __init__(self, quote: bool) -> None:
@@ -14,7 +20,11 @@ class NumpydocDocstringConverter(DocstringConverter):
             quote=quote,
         )
 
-    def to_function_docstring(self, function: Function, indent: int) -> str:
+    def to_function_docstring(
+        self, docstring_node: FunctionDocstringNode, indent: int
+    ) -> str:
+        function = docstring_node.to_function()
+
         docstring = [DESCRIPTION_PLACEHOLDER]
 
         if parameters_section := self.parameters_section(function.parameters):
@@ -38,8 +48,8 @@ class NumpydocDocstringConverter(DocstringConverter):
             return f'{return_type}\n    {DESCRIPTION_PLACEHOLDER}'
         return ''
 
-    def to_module_docstring(self, module_name: str) -> str:
+    def to_module_docstring(self, docstring_node: DocstringNode) -> str:
         return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=0)
 
-    def to_class_docstring(self, class_name: str, indent: int) -> str:
+    def to_class_docstring(self, docstring_node: DocstringNode, indent: int) -> str:
         return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=indent)

docstringify-0.5.0/src/docstringify/nodes/__init__.py

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

docstringify-0.5.0/src/docstringify/nodes/base.py

@@ -0,0 +1,56 @@
+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.docstring_required: bool = True
+
+        self.ast_node: (
+            ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef
+        ) = node
+        self.name: str = getattr(node, 'name', self.module_name)
+
+        docstring = ast.get_docstring(node)
+        self.docstring = docstring if docstring is None else docstring.strip()
+
+        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-0.5.0/src/docstringify/nodes/function.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import ast
+import itertools
+from typing import Literal
+
+from ..components import (
+    NO_DEFAULT,
+    PARAMETER_TYPE_PLACEHOLDER,
+    RETURN_TYPE_PLACEHOLDER,
+    Function,
+    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
+        )
+
+        # don't require docstring for the __init__ method if the class has a docstring
+        self.docstring_required: bool = not (
+            self.is_method and self.name == '__init__' and self.parent.docstring
+        )
+
+        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
+
+    def to_function(self) -> Function:
+        return Function(self.extract_arguments(), self.extract_returns())

docstringify-0.5.0/src/docstringify/traversal/__init__.py

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

docstringify-0.5.0/src/docstringify/traversal/transformer.py

@@ -0,0 +1,61 @@
+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:
+            # 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-0.5.0/src/docstringify/traversal/visitor.py

@@ -0,0 +1,99 @@
+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:
+                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_required and not docstring_node.docstring:
+            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.3.0 → docstringify-0.5.0}/src/docstringify.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.3.0
+Version: 0.5.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.3.0
+  rev: 0.5.0
   hooks:
     - id: docstringify
 ```
@@ -69,7 +69,7 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.3.0
+  rev: 0.5.0
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
@@ -79,7 +79,7 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.3.0
+  rev: 0.5.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -89,7 +89,7 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.3.0
+  rev: 0.5.0
   hooks:
     - id: docstringify
       args: [--make-changes=google]
@@ -126,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
@@ -137,9 +137,9 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```pycon
 >>> from docstringify.converters import NumpydocDocstringConverter
->>> from docstringify.visitor import DocstringVisitor
+>>> from docstringify.traversal import DocstringVisitor
 >>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)
->>> _ = visitor.process_file()
+>>> visitor.process_file()
 test is missing a docstring
 Hint:
 """__description__"""
@@ -161,9 +161,9 @@ To make changes to your files, you will need to use the `DocstringTransformer` i
 
 ```pycon
 >>> from docstringify.converters import GoogleDocstringConverter
->>> from docstringify.transformer import DocstringTransformer
+>>> from docstringify.traversal import DocstringTransformer
 >>> transformer = DocstringTransformer('test.py', converter=GoogleDocstringConverter)
->>> _ = transformer.process_file()
+>>> transformer.process_file()
 test is missing a docstring
 test.say_hello is missing a docstring
 Docstring templates written to /.../test_docstringify.py

{docstringify-0.3.0 → docstringify-0.5.0}/src/docstringify.egg-info/SOURCES.txt

@@ -6,16 +6,16 @@ README.md
 pyproject.toml
 .github/dependabot.yml
 .github/release.yml
+.github/ISSUE_TEMPLATE/bug_report.md
+.github/ISSUE_TEMPLATE/feature_request.md
 .github/workflows/ci.yml
+.github/workflows/greetings.yml
 .github/workflows/pypi-publish.yml
 src/docstringify/__init__.py
 src/docstringify/__main__.py
 src/docstringify/cli.py
 src/docstringify/components.py
-src/docstringify/docstring_generator.py
 src/docstringify/exceptions.py
-src/docstringify/transformer.py
-src/docstringify/visitor.py
 src/docstringify.egg-info/PKG-INFO
 src/docstringify.egg-info/SOURCES.txt
 src/docstringify.egg-info/dependency_links.txt
@@ -25,4 +25,10 @@ src/docstringify.egg-info/top_level.txt
 src/docstringify/converters/__init__.py
 src/docstringify/converters/base.py
 src/docstringify/converters/google.py
-src/docstringify/converters/numpydoc.py
+src/docstringify/converters/numpydoc.py
+src/docstringify/nodes/__init__.py
+src/docstringify/nodes/base.py
+src/docstringify/nodes/function.py
+src/docstringify/traversal/__init__.py
+src/docstringify/traversal/transformer.py
+src/docstringify/traversal/visitor.py

docstringify-0.3.0/src/docstringify/docstring_generator.py

@@ -1,157 +0,0 @@
-from __future__ import annotations
-
-import ast
-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 DocstringGenerator:
-    def __init__(
-        self,
-        converter: type[DocstringConverter],
-        module_name: str,
-        source_code: str,
-        quote: bool,
-    ) -> None:
-        self.converter = converter(quote=quote)
-        self.module_name = module_name
-        self.source_code = source_code
-
-    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 suggest_docstring(
-        self,
-        node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module,
-        indent: int = 0,
-    ) -> str:
-        if isinstance(node, ast.AsyncFunctionDef | ast.FunctionDef):
-            return self.converter.to_function_docstring(
-                Function(self.extract_arguments(node), self.extract_returns(node)),
-                indent=indent,
-            )
-
-        if isinstance(node, ast.Module):
-            return self.converter.to_module_docstring(self.module_name)
-
-        return self.converter.to_class_docstring(node.name, indent=indent)

docstringify-0.3.0/src/docstringify/transformer.py

@@ -1,53 +0,0 @@
-from __future__ import annotations
-
-import ast
-from typing import TYPE_CHECKING
-
-from .visitor import DocstringVisitor
-
-if TYPE_CHECKING:
-    from .converters import DocstringConverter
-
-
-class DocstringTransformer(ast.NodeTransformer, DocstringVisitor):
-    def __init__(
-        self, filename: str, converter: DocstringConverter, overwrite: bool = False
-    ) -> None:
-        super().__init__(filename, converter)
-        self.overwrite = overwrite
-
-    def save(self, new_ast: ast.Module) -> 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(new_ast)
-            output.write_text(edited_code)
-            print(f'Docstring templates written to {output}')
-        else:
-            print(
-                f'No missing docstrings found in {self.source_file}; no changes made.'
-            )
-
-    def handle_missing_docstring(
-        self, node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
-    ) -> ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module:
-        suggested_docstring = self.docstring_generator.suggest_docstring(
-            node, indent=0 if isinstance(node, ast.Module) else node.col_offset + 4
-        )
-        docstring = ast.Expr(ast.Constant(suggested_docstring))
-        node.body.insert(0, docstring)
-        return ast.fix_missing_locations(node)
-
-    def process_file(self) -> ast.Module:
-        root = ast.parse(self.source_code)
-        new_ast = self.visit(root)
-        self.save(new_ast)
-        return new_ast

docstringify-0.3.0/src/docstringify/visitor.py

@@ -1,79 +0,0 @@
-from __future__ import annotations
-
-import ast
-import sys
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-from .docstring_generator import DocstringGenerator
-
-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).expanduser().resolve()
-        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.docstring_generator = DocstringGenerator(
-                converter,
-                self.module_name,
-                self.source_code,
-                quote=not issubclass(self.__class__, ast.NodeTransformer),
-            )
-
-    def report_missing_docstring(self) -> None:
-        self.missing_docstrings += 1
-        print(f'{".".join(self.stack)} is missing a docstring', file=sys.stderr)
-
-    def handle_missing_docstring(
-        self, node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
-    ) -> ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module:
-        if self.provide_hints:
-            print('Hint:')
-            print(self.docstring_generator.suggest_docstring(node))
-            print()
-        return node
-
-    def process_docstring(
-        self, node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
-    ) -> ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module:
-        if not ast.get_docstring(node):
-            self.report_missing_docstring()
-            node = self.handle_missing_docstring(node)
-
-        self.docstrings_inspected += 1
-        return node
-
-    def visit(self, node: ast.AST) -> ast.AST:
-        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
-            )
-
-            node = self.process_docstring(node)
-
-            self.generic_visit(node)
-            _ = self.stack.pop()
-        return node
-
-    def process_file(self) -> ast.Module:
-        root = self.visit(ast.parse(self.source_code))
-
-        if not self.missing_docstrings:
-            print(f'No missing docstrings found in {self.source_file}.')
-
-        return root