docstringify 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -12,7 +12,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/stefmolin/docstringify
-    rev: 0.5.1
+    rev: 0.6.0
     hooks:
       - id: docstringify
         args: [--make-changes-inplace=numpydoc]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.6.0
+Version: 0.7.0
 Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
 License: MIT License
@@ -107,7 +107,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.6.0
+  rev: 0.7.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: 0.7.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 [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 0.7.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -136,7 +136,7 @@ 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: 0.7.0
   hooks:
     - id: docstringify
       args: [--make-changes=google]

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

@@ -58,7 +58,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.6.0
+  rev: 0.7.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: 0.7.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 [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 0.7.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -87,7 +87,7 @@ 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: 0.7.0
   hooks:
     - id: docstringify
       args: [--make-changes=google]

{docstringify-0.6.0 → docstringify-0.7.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__ = '0.7.0'

{docstringify-0.6.0 → docstringify-0.7.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-0.7.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-0.7.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):
@@ -238,7 +238,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-0.7.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-0.7.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-0.7.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-0.6.0 → docstringify-0.7.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-0.7.0}/src/docstringify/nodes/function.py

@@ -69,7 +69,17 @@ class FunctionDocstringNode(DocstringNode):
             )
         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,7 +93,7 @@ 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)
@@ -110,7 +120,7 @@ class FunctionDocstringNode(DocstringNode):
             )
         ]
 
-    def _extract_keyword_args(self) -> list[Parameter, ...]:
+    def _extract_keyword_args(self) -> list[Parameter]:
         return [
             Parameter(
                 name=arg.arg,

{docstringify-0.6.0 → docstringify-0.7.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
@@ -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,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.6.0
+Version: 0.7.0
 Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
 License: MIT License
@@ -107,7 +107,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.6.0
+  rev: 0.7.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: 0.7.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 [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.6.0
+  rev: 0.7.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -136,7 +136,7 @@ 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: 0.7.0
   hooks:
     - id: docstringify
       args: [--make-changes=google]

{docstringify-0.6.0 → docstringify-0.7.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