docstringify 0.6.0__tar.gz → 1.0.0__tar.gz

{docstringify-0.6.0 → docstringify-1.0.0}/.pre-commit-config.yaml

@@ -12,20 +12,20 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/stefmolin/docstringify
-    rev: 0.5.1
+    rev: 0.7.0
     hooks:
       - id: docstringify
         args: [--make-changes-inplace=numpydoc]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.9
+    rev: v0.11.10
     hooks:
-      - id: ruff
+      - id: ruff-check
         args: [--fix, --exit-non-zero-on-fix, --show-fixes]
       - id: ruff-format
 
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.5.1
+    rev: v2.6.0
     hooks:
       - id: pyproject-fmt
         args: [--keep-full-version, --no-print-diff]

{docstringify-0.6.0 → docstringify-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.6.0
+Version: 1.0.0
 Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
 License: MIT License
@@ -29,7 +29,7 @@ Project-URL: Documentation, https://github.com/stefmolin/docstringify
 Project-URL: Homepage, https://github.com/stefmolin/docstringify
 Project-URL: Source, https://github.com/stefmolin/docstringify
 Keywords: ast,docstring generation,google-style docstring,numpydoc-style docstring,pre-commit
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.9
@@ -103,11 +103,11 @@ You can use Docstringify in three modes:
 
 ### Pre-commit hook
 
-Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings:
+Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 1.0.0
   hooks:
     - id: docstringify
 ```
@@ -116,17 +116,17 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 1.0.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, 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:
+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`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`):
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 1.0.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -136,13 +136,21 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 1.0.0
   hooks:
     - id: docstringify
       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.*).
+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. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 1.0.0
+  hooks:
+    - id: docstringify
+      args: [--make-changes-inplace=numpydoc]
+```
 
 Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
 
@@ -216,7 +224,19 @@ 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()`.
+If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`:
+
+```pycon
+>>> from docstringify.converters import GoogleDocstringConverter
+>>> from docstringify.traversal import DocstringTransformer
+>>> transformer = DocstringTransformer(
+...     'test.py', converter=GoogleDocstringConverter, overwrite=True
+... )
+>>> transformer.process_file()
+test is missing a docstring
+test.say_hello is missing a docstring
+Docstring templates written to /.../test.py
+```
 
 ## Contributing
 

{docstringify-0.6.0 → docstringify-1.0.0}/README.md

@@ -54,11 +54,11 @@ You can use Docstringify in three modes:
 
 ### Pre-commit hook
 
-Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings:
+Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 1.0.0
   hooks:
     - id: docstringify
 ```
@@ -67,17 +67,17 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 1.0.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, 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:
+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`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`):
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 1.0.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -87,13 +87,21 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 1.0.0
   hooks:
     - id: docstringify
       args: [--make-changes=google]
 ```
 
-If you want the changes to be made in place, change `--make-changes` to `--make-changes-inplace` – 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.*).
+If you want the changes to be made in place, change `--make-changes` to `--make-changes-inplace` – make sure you only operate on files that are in version control with this setting. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 1.0.0
+  hooks:
+    - id: docstringify
+      args: [--make-changes-inplace=numpydoc]
+```
 
 Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
 
@@ -167,7 +175,19 @@ 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()`.
+If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`:
+
+```pycon
+>>> from docstringify.converters import GoogleDocstringConverter
+>>> from docstringify.traversal import DocstringTransformer
+>>> transformer = DocstringTransformer(
+...     'test.py', converter=GoogleDocstringConverter, overwrite=True
+... )
+>>> transformer.process_file()
+test is missing a docstring
+test.say_hello is missing a docstring
+Docstring templates written to /.../test.py
+```
 
 ## Contributing
 

{docstringify-0.6.0 → docstringify-1.0.0}/pyproject.toml

@@ -23,7 +23,7 @@ authors = [
 ]
 requires-python = ">=3.9"
 classifiers = [
-  "Development Status :: 3 - Alpha",
+  "Development Status :: 4 - Beta",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3 :: Only",
   "Programming Language :: Python :: 3.9",

{docstringify-0.6.0 → docstringify-1.0.0}/src/docstringify/__init__.py

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

{docstringify-0.6.0 → docstringify-1.0.0}/src/docstringify/cli.py

@@ -9,14 +9,28 @@ from typing import TYPE_CHECKING
 
 from . import __doc__ as pkg_description
 from . import __version__
-from .converters import GoogleDocstringConverter, NumpydocDocstringConverter
+from .converters import (
+    GoogleDocstringConverter,
+    NumpydocDocstringConverter,
+    StubDocstringConverter,
+)
 from .traversal import DocstringTransformer, DocstringVisitor
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
+
 PROG = __package__
-STYLES = {'google': GoogleDocstringConverter, 'numpydoc': NumpydocDocstringConverter}
+STYLES: dict[
+    str,
+    type[GoogleDocstringConverter]
+    | type[NumpydocDocstringConverter]
+    | type[StubDocstringConverter],
+] = {
+    'google': GoogleDocstringConverter,
+    'numpydoc': NumpydocDocstringConverter,
+    'stub': StubDocstringConverter,
+}
 CLI_DEFAULTS = {'threshold': 1.0}
 
 
@@ -74,22 +88,19 @@ def main(argv: Sequence[str] | None = None) -> int:
     )
     args = parser.parse_args(argv)
 
-    if style := (
-        args.make_changes or args.make_changes_inplace or args.suggest_changes
-    ):
-        converter = STYLES[style]
-    else:
-        converter = None
-
     get_docstring_processor = (
         partial(
             DocstringTransformer,
-            converter=converter,
+            converter=STYLES[style],
             overwrite=bool(args.make_changes_inplace),
             verbose=args.verbose,
         )
-        if args.make_changes or args.make_changes_inplace
-        else partial(DocstringVisitor, converter=converter, verbose=args.verbose)
+        if (style := args.make_changes or args.make_changes_inplace)
+        else partial(
+            DocstringVisitor,
+            converter=STYLES.get(args.suggest_changes),
+            verbose=args.verbose,
+        )
     )
 
     docstrings_processed = missing_docstrings = 0

{docstringify-0.6.0 → docstringify-1.0.0}/src/docstringify/converters/__init__.py

@@ -3,9 +3,11 @@
 from .base import DocstringConverter
 from .google import GoogleDocstringConverter
 from .numpydoc import NumpydocDocstringConverter
+from .stub import StubDocstringConverter
 
 __all__ = [
     'DocstringConverter',
     'GoogleDocstringConverter',
     'NumpydocDocstringConverter',
+    'StubDocstringConverter',
 ]

{docstringify-0.6.0 → docstringify-1.0.0}/src/docstringify/converters/base.py

@@ -8,11 +8,11 @@ from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING
 
 from ..exceptions import InvalidDocstringError
+from ..nodes.function import FunctionDocstringNode
 
 if TYPE_CHECKING:
     from ..components import Parameter
     from ..nodes.base import DocstringNode
-    from ..nodes.function import FunctionDocstringNode
 
 
 class DocstringConverter(ABC):
@@ -184,7 +184,9 @@ class DocstringConverter(ABC):
             return self._returns_section_template.format(returns=return_text)
         return ''
 
-    def format_docstring(self, docstring: str | list[str], indent: int) -> str:
+    def format_docstring(
+        self, docstring: str | list[str], indent: int, quote: bool | None = None
+    ) -> str:
         """
         Format the docstring with the requested level of indentation and surrounding
         triple quotes, if requested.
@@ -195,23 +197,28 @@ class DocstringConverter(ABC):
             The docstring as a string or list of strings that form lines in the docstring.
         indent : int
             The number of spaces by which to indent the docstring.
+        quote : bool | None, default=None
+            Whether to surround the docstring in triple quotes, passing this overrides
+            the ``quote`` setting specified upon initialization.
 
         Returns
         -------
         str
             The docstring indented to ``indent`` spaces will be returned either as a
-            quoted docstring if the converter was initialized with ``quote=True``, or an
-            unquoted docstring otherwise.
+            quoted docstring if the converter was initialized with ``quote=True`` or
+            ``quote=True`` was passed when calling this method, or an unquoted
+            docstring otherwise.
         """
-        quote = '"""' if self._quote else ''
+        quote_char = '"""' if quote or self._quote else ''
         prefix = sep = ''
+
         if isinstance(docstring, str):
-            docstring = [quote, docstring, quote]
+            docstring = [quote_char, docstring, quote_char]
         elif isinstance(docstring, list):
             if len(docstring) > 1:
                 prefix = ' ' * indent if indent else ''
                 sep = '\n'
-            docstring = [quote, *docstring, f'{prefix}{quote}']
+            docstring = [quote_char, *docstring, quote_char or f'{prefix}']
         else:
             raise InvalidDocstringError(type(docstring).__name__)
 
@@ -238,7 +245,7 @@ class DocstringConverter(ABC):
         str | None
             The suggested docstring.
         """
-        if isinstance(docstring_node.ast_node, ast.AsyncFunctionDef | ast.FunctionDef):
+        if isinstance(docstring_node, FunctionDocstringNode):
             return (
                 self.to_function_docstring(docstring_node, indent=indent)
                 if docstring_node.docstring_required

{docstringify-0.6.0 → docstringify-1.0.0}/src/docstringify/converters/google.py

@@ -81,7 +81,7 @@ class GoogleDocstringConverter(DocstringConverter):
         category = f'{f", {parameter.category}" if parameter.category else ""}'
         return (
             f'    {parameter.name} ({parameter.type_}{category}): {DESCRIPTION_PLACEHOLDER}'
-            f'{f" Defaults to {parameter.default}." if parameter.default != NO_DEFAULT else ""}'
+            f'{f" Defaults to {parameter.default}." if parameter.default is not NO_DEFAULT else ""}'
         )
 
     def format_return(self, return_type: str | None) -> str:

{docstringify-0.6.0 → docstringify-1.0.0}/src/docstringify/converters/numpydoc.py

@@ -81,7 +81,7 @@ class NumpydocDocstringConverter(DocstringConverter):
         return (
             f'{parameter.name} : {parameter.type_}'
             f'{f", {parameter.category}" if parameter.category else ""}'
-            f'{f", default={parameter.default}" if parameter.default != NO_DEFAULT else ""}'
+            f'{f", default={parameter.default}" if parameter.default is not NO_DEFAULT else ""}'
             f'\n    {DESCRIPTION_PLACEHOLDER}'
         )
 

docstringify-1.0.0/src/docstringify/converters/stub.py

@@ -0,0 +1,121 @@
+"""Stub docstring converter."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..components import DESCRIPTION_PLACEHOLDER, Parameter
+from .base import DocstringConverter
+
+if TYPE_CHECKING:
+    from ..nodes.base import DocstringNode
+    from ..nodes.function import FunctionDocstringNode
+
+
+class StubDocstringConverter(DocstringConverter):
+    """
+    Class defining the DocstringConverter API for injecting ``__description__`` stubs only.
+
+    Parameters
+    ----------
+    quote : bool
+        Whether to surround the generated docstrings in triple quotes.
+    """
+
+    def __init__(self, quote: bool) -> None:
+        super().__init__(
+            parameters_section_template='', returns_section_template='', quote=quote
+        )
+
+    def to_function_docstring(
+        self, docstring_node: FunctionDocstringNode, indent: int
+    ) -> str:
+        """
+        Convert an AST node into a function docstring.
+
+        Parameters
+        ----------
+        docstring_node : FunctionDocstringNode
+            An instance of :class:`.FunctionDocstringNode`, which wraps an instance of
+            :class:`ast.FunctionDef` or :class:`ast.AsyncFunctionDef`, adding additional
+            context relevant for Docstringify.
+        indent : int
+            The number of spaces by which to indent the docstring.
+
+        Returns
+        -------
+        str
+            The function docstring.
+        """
+        return self.format_docstring(DESCRIPTION_PLACEHOLDER, indent=indent)
+
+    def format_parameter(self, parameter: Parameter) -> str:
+        """
+        Convert a :class:`.Parameter` instance into an entry in the parameters section
+        of the docstring.
+
+        Parameters
+        ----------
+        parameter : Parameter
+            Information on the function parameter, including its name, type, and default
+            value (if it has one).
+
+        Returns
+        -------
+        str
+            An empty string.
+        """
+        return ''
+
+    def format_return(self, return_type: str | None) -> str:
+        """
+        Convert a return type into an entry in the returns section of the docstring.
+
+        Parameters
+        ----------
+        return_type : str | None
+            The return type name for the function. This will be either a string for the
+            name (e.g., ``list[str]``) or ``None``, if ``None`` is returned.
+
+        Returns
+        -------
+        str
+            An empty string.
+        """
+        return ''
+
+    def to_module_docstring(self, docstring_node: DocstringNode) -> str:
+        """
+        Convert an AST node into a module docstring.
+
+        Parameters
+        ----------
+        docstring_node : DocstringNode
+            An instance of :class:`.DocstringNode`, which wraps an instance of
+            :class:`ast.Module`, adding additional context relevant for Docstringify.
+
+        Returns
+        -------
+        str
+            The module docstring.
+        """
+        return self.format_docstring(DESCRIPTION_PLACEHOLDER, indent=0)
+
+    def to_class_docstring(self, docstring_node: DocstringNode, indent: int) -> str:
+        """
+        Convert an AST node into a class docstring.
+
+        Parameters
+        ----------
+        docstring_node : DocstringNode
+            An instance of :class:`.DocstringNode`, which wraps an instance of
+            :class:`ast.ClassDef`, adding additional context relevant for Docstringify.
+        indent : int
+            The number of spaces by which to indent the docstring.
+
+        Returns
+        -------
+        str
+            The class docstring.
+        """
+        return self.format_docstring(DESCRIPTION_PLACEHOLDER, indent=indent)

docstringify-1.0.0/src/docstringify/exceptions.py

@@ -0,0 +1,25 @@
+"""Docstringify exceptions."""
+
+
+class EmptyDocstringError(ValueError):
+    """
+    Raised when trying to write the modified source code back to a file if a docstring
+    is somehow empty.
+    """
+
+    def __init__(self) -> None:
+        super().__init__('Docstring is empty')
+
+
+class InvalidDocstringError(TypeError):
+    """
+    Raised when trying to create a docstring with invalid input.
+
+    Parameters
+    ----------
+    docstring_class : str
+        The class of the docstring object. This is used for the error message.
+    """
+
+    def __init__(self, docstring_class: str) -> None:
+        super().__init__(f'Expected str or list[str] docstring, got {docstring_class}')

{docstringify-0.6.0 → docstringify-1.0.0}/src/docstringify/nodes/base.py

@@ -40,13 +40,15 @@ class DocstringNode:
         ) = 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(
+        self.get_source_segment: Callable[[ast.AST], str | None] = partial(
             ast.get_source_segment, source_code
         )
 
+    @property
+    def docstring(self) -> str | None:
+        docstring = ast.get_docstring(self.ast_node)
+        return docstring if docstring is None else docstring.strip()
+
     @property
     def fully_qualified_name(self) -> str:
         return (

{docstringify-0.6.0 → docstringify-1.0.0}/src/docstringify/nodes/function.py

@@ -23,11 +23,17 @@ class FunctionDocstringNode(DocstringNode):
         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
+            decorator
+            for decorator_node in node.decorator_list
+            if (decorator := self.get_source_segment(decorator_node))
         ]
 
-        self.is_method: bool = self.parent and isinstance(
+        self.is_overload: bool = (
+            'overload' in self.decorators or 'typing.overload' in self.decorators
+        )
+        self.is_method: bool = self.parent is not None and isinstance(
             self.parent.ast_node, ast.ClassDef
         )
         self.is_abstract_method: bool = self.is_method and (
@@ -39,15 +45,26 @@ class FunctionDocstringNode(DocstringNode):
             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.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
+        # or if the function/method is just a typing.overload signature
+        self.docstring_required: bool = (
+            not (
+                self.is_method
+                and self.name == '__init__'
+                and self.parent is not None
+                and self.parent.docstring
+            )
+            and not self.is_overload
         )
 
-        self.arguments: ast.arguments | None = getattr(node, 'args', None)
+        self.arguments: ast.arguments = node.args
+
+        self.returns: ast.AST | None = node.returns
         self.return_annotation: str | None = self._extract_return_annotation()
         self.return_statements: list[ast.Return] = []
 
@@ -64,12 +81,23 @@ class FunctionDocstringNode(DocstringNode):
 
             return (
                 f'"{default_value}"'
-                if isinstance(default_value, str) and not default_value.startswith('`')
+                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]:
+    def _extract_star_args(self) -> list[Parameter | None]:
+        """
+        Extract the function's ``*args`` and ``**kwargs`` arguments.
+
+        Returns
+        -------
+        list[Parameter | None]
+            A list of the form ``[*args, **kwargs]``, where each entry is either a
+            :class:`.Parameter` instance, or ``None`` if that type of argument isn't
+            part of the function definition.
+        """
         return [
             Parameter(
                 name=f'*{arg.arg}' if arg_type == 'vararg' else f'**{arg.arg}',
@@ -83,10 +111,11 @@ class FunctionDocstringNode(DocstringNode):
             for arg in [getattr(self.arguments, arg_type)]
         ]
 
-    def _extract_positional_args(self) -> list[Parameter, ...]:
+    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_arguments_count := (
+                len(self.arguments.posonlyargs) + len(self.arguments.args)
+            )
         ):
             positional_defaults = [NO_DEFAULT] * (
                 positional_arguments_count - default_count
@@ -110,7 +139,7 @@ class FunctionDocstringNode(DocstringNode):
             )
         ]
 
-    def _extract_keyword_args(self) -> list[Parameter, ...]:
+    def _extract_keyword_args(self) -> list[Parameter]:
         return [
             Parameter(
                 name=arg.arg,
@@ -145,23 +174,28 @@ class FunctionDocstringNode(DocstringNode):
         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
+        if self.returns is None:
+            return self.returns
+
+        if isinstance(self.returns, ast.Constant):
+            return self.returns.value
+
+        if isinstance(self.returns, ast.Name):
+            return self.returns.id
+
+        return self.get_source_segment(self.returns)
 
     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)
+            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:

{docstringify-0.6.0 → docstringify-1.0.0}/src/docstringify/traversal/transformer.py

@@ -6,8 +6,10 @@ on the source code.
 from __future__ import annotations
 
 import ast
+from textwrap import indent
 from typing import TYPE_CHECKING
 
+from ..exceptions import EmptyDocstringError
 from .visitor import DocstringVisitor
 
 if TYPE_CHECKING:
@@ -60,11 +62,80 @@ class DocstringTransformer(ast.NodeTransformer, DocstringVisitor):
                     + ''.join(self.source_file.suffixes)
                 )
             )
-            edited_code = ast.unparse(self.tree)
+            edited_code = self._convert_to_source_code()
             output.write_text(edited_code)
             print(f'Docstring templates written to {output}')
 
-    def handle_missing_docstring(self, docstring_node: DocstringNode) -> DocstringNode:
+    def _convert_to_source_code(self) -> str:
+        """
+        Convert the modified AST back to source code, preserving the original format and
+        any comments.
+
+        Returns
+        -------
+        str
+            The original source code with the docstrings injected.
+        """
+        source_code = self.source_code.splitlines()
+        output_lines = []
+        write_line = start_line = 0
+
+        for missing_docstring in self.missing_docstrings:
+            docstring_node = missing_docstring.ast_node.body[0]
+            prefix = docstring_node.col_offset
+            suffix = ''
+
+            # write everything before docstring
+            if not isinstance(missing_docstring.ast_node, ast.Module):
+                # line before a code node
+                start_line = missing_docstring.ast_node.body[1].lineno - 1
+
+                if isinstance(missing_docstring.ast_node, ast.ClassDef):
+                    start_line = docstring_node.lineno
+
+                if len(body := missing_docstring.ast_node.body) == 2:
+                    code_node = body[1]
+                    line_number = code_node.lineno - 1
+                    line = source_code[line_number]
+
+                    if line.strip() != (function_body := line[code_node.col_offset :]):
+                        # if the function body is on the same line as the signature, cut it out
+                        # in order to inject the docstring in the right spot
+                        source_code[line_number] = source_code[line_number][
+                            : code_node.col_offset
+                        ].rstrip()
+
+                        # add the logic under the docstring
+                        start_line = missing_docstring.ast_node.body[1].lineno
+                        suffix = function_body
+
+            output_lines += source_code[write_line:start_line]
+
+            # write docstring
+            if not (docstring := missing_docstring.docstring):
+                raise EmptyDocstringError
+
+            output_lines.append(
+                indent(
+                    self.docstring_converter.format_docstring(
+                        docstring.splitlines(),
+                        indent=0,
+                        quote=True,
+                    )
+                    + (f'\n{suffix}' if suffix else ''),
+                    ' ' * prefix,
+                )
+            )
+
+            # update current location in file
+            write_line = start_line
+
+        # write the rest of the file
+        output_lines += source_code[write_line:]
+
+        return '\n'.join(output_lines) + '\n'
+
+    def handle_missing_docstring(self, docstring_node: DocstringNode) -> None:
         """
         Handle missing docstrings by injecting a suggested docstring template based on
         the source code into the AST.
@@ -74,19 +145,16 @@ class DocstringTransformer(ast.NodeTransformer, DocstringVisitor):
         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.
         """
+        indent = (
+            0
+            if isinstance(docstring_node.ast_node, ast.Module)
+            else docstring_node.ast_node.col_offset + 4
+        )
+
         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,
+            indent=indent,
         )
         docstring_ast_node = ast.Expr(ast.Constant(suggested_docstring))
 
@@ -98,8 +166,7 @@ class DocstringTransformer(ast.NodeTransformer, DocstringVisitor):
             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
+        docstring_ast_node.col_offset = indent
 
     def process_file(self) -> None:
         """

{docstringify-0.6.0 → docstringify-1.0.0}/src/docstringify/traversal/visitor.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 import ast
 import sys
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, overload
 
 from ..nodes.base import DocstringNode
 from ..nodes.function import FunctionDocstringNode
@@ -112,8 +112,8 @@ class DocstringVisitor(ast.NodeVisitor):
 
     def process_docstring(self, docstring_node: DocstringNode) -> DocstringNode:
         """
-        Process a docstring node, appending it to :attr:`.missing_docstrings` if a docstring
-        is required, but there isn't one.
+        Process a docstring node, appending it to :attr:`.missing_docstrings` if a
+        docstring is required, but there isn't one.
 
         Parameters
         ----------
@@ -133,6 +133,34 @@ class DocstringVisitor(ast.NodeVisitor):
         self.docstrings_inspected += 1
         return docstring_node
 
+    @overload
+    def visit_docstring(
+        self,
+        node: ast.Module,
+        docstring_class: type[DocstringNode],
+    ) -> ast.Module: ...
+
+    @overload
+    def visit_docstring(
+        self,
+        node: ast.ClassDef,
+        docstring_class: type[DocstringNode],
+    ) -> ast.ClassDef: ...
+
+    @overload
+    def visit_docstring(
+        self,
+        node: ast.FunctionDef,
+        docstring_class: type[FunctionDocstringNode],
+    ) -> ast.FunctionDef: ...
+
+    @overload
+    def visit_docstring(
+        self,
+        node: ast.AsyncFunctionDef,
+        docstring_class: type[FunctionDocstringNode],
+    ) -> ast.AsyncFunctionDef: ...
+
     def visit_docstring(
         self,
         node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module,
@@ -153,12 +181,12 @@ class DocstringVisitor(ast.NodeVisitor):
         ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
             The AST node that was visited.
         """
-        docstring_node = docstring_class(
-            node,
-            self.module_name,
-            self.source_code,
-            parent=self.stack[-1] if self.stack else None,
-        )
+        if isinstance(node, ast.Module):
+            docstring_node = docstring_class(node, self.module_name, self.source_code)
+        else:
+            docstring_node = docstring_class(
+                node, self.module_name, self.source_code, parent=self.stack[-1]
+            )
 
         self.stack.append(docstring_node)
 

{docstringify-0.6.0 → docstringify-1.0.0}/src/docstringify.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.6.0
+Version: 1.0.0
 Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
 License: MIT License
@@ -29,7 +29,7 @@ Project-URL: Documentation, https://github.com/stefmolin/docstringify
 Project-URL: Homepage, https://github.com/stefmolin/docstringify
 Project-URL: Source, https://github.com/stefmolin/docstringify
 Keywords: ast,docstring generation,google-style docstring,numpydoc-style docstring,pre-commit
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.9
@@ -103,11 +103,11 @@ You can use Docstringify in three modes:
 
 ### Pre-commit hook
 
-Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings:
+Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 1.0.0
   hooks:
     - id: docstringify
 ```
@@ -116,17 +116,17 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 1.0.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, 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:
+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`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`):
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 1.0.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -136,13 +136,21 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 1.0.0
   hooks:
     - id: docstringify
       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.*).
+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. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 1.0.0
+  hooks:
+    - id: docstringify
+      args: [--make-changes-inplace=numpydoc]
+```
 
 Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
 
@@ -216,7 +224,19 @@ 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()`.
+If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`:
+
+```pycon
+>>> from docstringify.converters import GoogleDocstringConverter
+>>> from docstringify.traversal import DocstringTransformer
+>>> transformer = DocstringTransformer(
+...     'test.py', converter=GoogleDocstringConverter, overwrite=True
+... )
+>>> transformer.process_file()
+test is missing a docstring
+test.say_hello is missing a docstring
+Docstring templates written to /.../test.py
+```
 
 ## Contributing
 

{docstringify-0.6.0 → docstringify-1.0.0}/src/docstringify.egg-info/SOURCES.txt

@@ -29,6 +29,7 @@ src/docstringify/converters/__init__.py
 src/docstringify/converters/base.py
 src/docstringify/converters/google.py
 src/docstringify/converters/numpydoc.py
+src/docstringify/converters/stub.py
 src/docstringify/nodes/__init__.py
 src/docstringify/nodes/base.py
 src/docstringify/nodes/function.py

docstringify-0.6.0/src/docstringify/exceptions.py

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