docstringify 0.1.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.1.1
+Version: 0.3.0
 Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
 License: MIT License
@@ -28,7 +28,7 @@ License: MIT License
 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,numpydoc-style docstring,pre-commit
+Keywords: ast,docstring generation,google-style docstring,numpydoc-style docstring,pre-commit
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
@@ -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.1.1
+  rev: 0.3.0
   hooks:
     - id: docstringify
 ```
@@ -69,22 +69,34 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.1.1
+  rev: 0.3.0
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
 ```
 
-If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument. By default, these will be [numpydoc-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#); support for Google-style docstrings will come in a future release:
+If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google` and `numpydoc`). Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.1.1
+  rev: 0.3.0
   hooks:
     - id: docstringify
-      args: [--suggest-changes]
+      args: [--suggest-changes=numpydoc]
 ```
 
+Use `--make-changes` to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html):
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 0.3.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.*).
+
 Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
 
 ### Command line
@@ -124,10 +136,10 @@ test.say_hello is missing a docstring
 If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide a converter:
 
 ```pycon
->>> from docstringify.converters.numpydoc import NumpydocDocstringConverter
+>>> from docstringify.converters import NumpydocDocstringConverter
 >>> from docstringify.visitor import DocstringVisitor
->>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter())
->>> visitor.process_file()
+>>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)
+>>> _ = visitor.process_file()
 test is missing a docstring
 Hint:
 """__description__"""
@@ -144,3 +156,17 @@ name : str, default="World"
 """
 
 ```
+
+To make changes to your files, you will need to use the `DocstringTransformer` instead. With the `DocstringTransformer`, the converter is required:
+
+```pycon
+>>> from docstringify.converters import GoogleDocstringConverter
+>>> from docstringify.transformer import DocstringTransformer
+>>> transformer = DocstringTransformer('test.py', converter=GoogleDocstringConverter)
+>>> _ = transformer.process_file()
+test is missing a docstring
+test.say_hello is missing a docstring
+Docstring templates written to /.../test_docstringify.py
+```
+
+If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`.

{docstringify-0.1.1 → docstringify-0.3.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.1.1
+  rev: 0.3.0
   hooks:
     - id: docstringify
 ```
@@ -18,22 +18,34 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.1.1
+  rev: 0.3.0
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
 ```
 
-If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument. By default, these will be [numpydoc-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#); support for Google-style docstrings will come in a future release:
+If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google` and `numpydoc`). Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.1.1
+  rev: 0.3.0
   hooks:
     - id: docstringify
-      args: [--suggest-changes]
+      args: [--suggest-changes=numpydoc]
 ```
 
+Use `--make-changes` to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html):
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 0.3.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.*).
+
 Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
 
 ### Command line
@@ -73,10 +85,10 @@ test.say_hello is missing a docstring
 If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide a converter:
 
 ```pycon
->>> from docstringify.converters.numpydoc import NumpydocDocstringConverter
+>>> from docstringify.converters import NumpydocDocstringConverter
 >>> from docstringify.visitor import DocstringVisitor
->>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter())
->>> visitor.process_file()
+>>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)
+>>> _ = visitor.process_file()
 test is missing a docstring
 Hint:
 """__description__"""
@@ -93,3 +105,17 @@ name : str, default="World"
 """
 
 ```
+
+To make changes to your files, you will need to use the `DocstringTransformer` instead. With the `DocstringTransformer`, the converter is required:
+
+```pycon
+>>> from docstringify.converters import GoogleDocstringConverter
+>>> from docstringify.transformer import DocstringTransformer
+>>> transformer = DocstringTransformer('test.py', converter=GoogleDocstringConverter)
+>>> _ = transformer.process_file()
+test is missing a docstring
+test.say_hello is missing a docstring
+Docstring templates written to /.../test_docstringify.py
+```
+
+If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`.

{docstringify-0.1.1 → docstringify-0.3.0}/pyproject.toml

@@ -13,6 +13,7 @@ readme = "README.md"
 keywords = [
   "ast",
   "docstring generation",
+  "google-style docstring",
   "numpydoc-style docstring",
   "pre-commit",
 ]

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

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

docstringify-0.3.0/src/docstringify/cli.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from functools import partial
+from typing import Sequence
+
+from . import __version__
+from .converters import GoogleDocstringConverter, NumpydocDocstringConverter
+from .transformer import DocstringTransformer
+from .visitor import DocstringVisitor
+
+PROG = __package__
+
+STYLES = {
+    'google': GoogleDocstringConverter,
+    'numpydoc': NumpydocDocstringConverter,
+}
+CLI_DEFAULTS = {'threshold': 1.0}
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog=PROG)
+    parser.add_argument(
+        'filenames',
+        nargs='*',
+        help='Filenames to process',
+    )
+    parser.add_argument(
+        '--version', action='version', version=f'%(prog)s {__version__}'
+    )
+
+    run_group = parser.add_argument_group('Run options')
+    handle_missing_docstring = run_group.add_mutually_exclusive_group(required=False)
+    handle_missing_docstring.add_argument(
+        '--make-changes',
+        choices=STYLES.keys(),
+        help='Whether to insert docstring templates for items missing docstrings',
+    )
+    handle_missing_docstring.add_argument(
+        '--make-changes-inplace',
+        choices=STYLES.keys(),
+        help=(
+            'Whether to insert docstring templates for items missing docstrings, '
+            'overwriting the original file'
+        ),
+    )
+    handle_missing_docstring.add_argument(
+        '--suggest-changes',
+        choices=STYLES.keys(),
+        help='Whether to print out docstring templates for items missing docstrings',
+    )
+    run_group.add_argument(
+        '--threshold',
+        type=float,
+        default=CLI_DEFAULTS['threshold'],
+        help='The percentage of docstrings that must be present to pass',
+    )
+    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,
+            **{'overwrite': bool(args.make_changes_inplace)},
+        )
+        if args.make_changes or args.make_changes_inplace
+        else partial(DocstringVisitor, converter=converter)
+    )
+
+    docstrings_processed = missing_docstrings = 0
+    for file in args.filenames:
+        processor = get_docstring_processor(file)
+        processor.process_file()
+        missing_docstrings += processor.missing_docstrings
+        docstrings_processed += processor.docstrings_inspected
+
+    if docstrings_processed and (
+        missing_percentage := (missing_docstrings / docstrings_processed)
+    ) > (1 - args.threshold):
+        print(f'\nMissing {missing_percentage:.0%} of docstrings', file=sys.stderr)
+        print(
+            f'Your settings require {args.threshold:.0%} of docstrings to be present',
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

docstringify-0.3.0/src/docstringify/converters/__init__.py

@@ -0,0 +1,11 @@
+"""Docstring converters."""
+
+from .base import DocstringConverter
+from .google import GoogleDocstringConverter
+from .numpydoc import NumpydocDocstringConverter
+
+__all__ = [
+    'DocstringConverter',
+    'GoogleDocstringConverter',
+    'NumpydocDocstringConverter',
+]

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

@@ -2,26 +2,33 @@
 
 from __future__ import annotations
 
+import textwrap
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING
 
+from ..exceptions import InvalidDocstringError
+
 if TYPE_CHECKING:
     from ..components import Function, Parameter
 
 
 class DocstringConverter(ABC):
     def __init__(
-        self, parameters_section_template: str, returns_section_template: str
+        self,
+        parameters_section_template: str,
+        returns_section_template: str,
+        quote: bool,
     ) -> None:
         self.parameters_section_template = parameters_section_template
         self.returns_section_template = returns_section_template
+        self._quote = quote
 
     @abstractmethod
-    def to_class_docstring(self, class_name: str) -> str:
+    def to_class_docstring(self, class_name: str, indent: int) -> str:
         pass
 
     @abstractmethod
-    def to_function_docstring(self, function: Function) -> str:
+    def to_function_docstring(self, function: Function, indent: int) -> str:
         pass
 
     @abstractmethod
@@ -49,3 +56,18 @@ class DocstringConverter(ABC):
         if return_text := self.format_return(return_type):
             return self.returns_section_template.format(returns=return_text)
         return ''
+
+    def quote_docstring(self, docstring: str | list[str], indent: int) -> str:
+        quote = '"""' if self._quote else ''
+        prefix = sep = ''
+        if isinstance(docstring, str):
+            docstring = [quote, docstring, quote]
+        elif isinstance(docstring, list):
+            if len(docstring) > 1:
+                prefix = ' ' * indent if indent else ''
+                sep = '\n'
+            docstring = [quote, *docstring, f'{prefix}{quote}']
+        else:
+            raise InvalidDocstringError(type(docstring).__name__)
+
+        return textwrap.indent(sep.join(docstring), prefix)

docstringify-0.3.0/src/docstringify/converters/google.py

@@ -0,0 +1,44 @@
+"""Google-style docstring converter."""
+
+from __future__ import annotations
+
+from ..components import DESCRIPTION_PLACEHOLDER, NO_DEFAULT, Function, Parameter
+from .base import DocstringConverter
+
+
+class GoogleDocstringConverter(DocstringConverter):
+    def __init__(self, quote: bool) -> None:
+        super().__init__(
+            parameters_section_template='Args:\n{parameters}',
+            returns_section_template='Returns:\n    {returns}',
+            quote=quote,
+        )
+
+    def to_function_docstring(self, function: Function, indent: int) -> str:
+        docstring = [DESCRIPTION_PLACEHOLDER]
+
+        if parameters_section := self.parameters_section(function.parameters):
+            docstring.extend(['', parameters_section])
+
+        if returns_section := self.returns_section(function.return_type):
+            docstring.extend(['', returns_section])
+
+        return self.quote_docstring(docstring, indent=indent)
+
+    def format_parameter(self, parameter: Parameter) -> str:
+        category = f'{f", {parameter.category}" if parameter.category else ""}'
+        return (
+            f'    {parameter.name} ({parameter.type_}{category}): {DESCRIPTION_PLACEHOLDER}'
+            f'{f" Defaults to {parameter.default}." if parameter.default != NO_DEFAULT else ""}'
+        )
+
+    def format_return(self, return_type: str | None) -> str:
+        if return_type:
+            return f'{return_type}: {DESCRIPTION_PLACEHOLDER}'
+        return ''
+
+    def to_module_docstring(self, module_name: str) -> str:
+        return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=0)
+
+    def to_class_docstring(self, class_name: str, indent: int) -> str:
+        return self.quote_docstring(DESCRIPTION_PLACEHOLDER, indent=indent)

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

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

docstringify-0.1.1/src/docstringify/visitor.py → docstringify-0.3.0/src/docstringify/docstring_generator.py

@@ -1,8 +1,6 @@
 from __future__ import annotations
 
 import ast
-import sys
-from pathlib import Path
 from typing import TYPE_CHECKING, Literal
 
 from .components import (
@@ -14,25 +12,20 @@ from .components import (
 )
 
 if TYPE_CHECKING:
-    from .converters.base import DocstringConverter
+    from .converters import DocstringConverter
 
 
-class DocstringVisitor(ast.NodeVisitor):
+class DocstringGenerator:
     def __init__(
-        self, filename: str, converter: DocstringConverter | None = None
+        self,
+        converter: type[DocstringConverter],
+        module_name: str,
+        source_code: str,
+        quote: bool,
     ) -> None:
-        self.source_file: Path = Path(filename)
-        self.source_code: str = self.source_file.read_text()
-
-        self.docstrings_inspected: int = 0
-        self.missing_docstrings: int = 0
-
-        self.module_name: str = self.source_file.stem
-        self.stack: list[str] = []
-
-        self.provide_hints: bool = converter is not None
-        if self.provide_hints:
-            self.converter: DocstringVisitor = converter  # TODO: consider whether this should be instantiated here instead of outside
+        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
@@ -147,50 +140,18 @@ class DocstringVisitor(ast.NodeVisitor):
             return RETURN_TYPE_PLACEHOLDER
         return return_node
 
-    def report_missing_docstring(self) -> None:
-        self.missing_docstrings += 1
-        print(f'{".".join(self.stack)} is missing a docstring', file=sys.stderr)
-
     def suggest_docstring(
-        self, node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
+        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))
+                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)
 
-        # TODO: with the stack, I should be able to let __init__() not have a docstring
-        # and suggest those parameters as the docstring for the class
-        # (may need to keep the class node in another stack)
-        return self.converter.to_class_docstring(node.name)
-
-    def process_docstring(
-        self, node: ast.AsyncFunctionDef | ast.ClassDef | ast.FunctionDef | ast.Module
-    ) -> None:
-        if not ast.get_docstring(node):
-            self.report_missing_docstring()
-            if self.provide_hints:
-                print('Hint:')
-                print(self.suggest_docstring(node))
-                print()
-
-        self.docstrings_inspected += 1
-
-    def visit(self, node: ast.AST) -> None:
-        if isinstance(
-            node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
-        ):
-            self.stack.append(
-                self.module_name if isinstance(node, ast.Module) else node.name
-            )
-
-            self.process_docstring(node)
-
-            self.generic_visit(node)
-            _ = self.stack.pop()
-
-    def process_file(self) -> None:
-        self.visit(ast.parse(self.source_code))
+        return self.converter.to_class_docstring(node.name, indent=indent)

docstringify-0.3.0/src/docstringify/exceptions.py

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

docstringify-0.3.0/src/docstringify/transformer.py

@@ -0,0 +1,53 @@
+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

@@ -0,0 +1,79 @@
+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

{docstringify-0.1.1 → docstringify-0.3.0}/src/docstringify.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.1.1
+Version: 0.3.0
 Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
 License: MIT License
@@ -28,7 +28,7 @@ License: MIT License
 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,numpydoc-style docstring,pre-commit
+Keywords: ast,docstring generation,google-style docstring,numpydoc-style docstring,pre-commit
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
@@ -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.1.1
+  rev: 0.3.0
   hooks:
     - id: docstringify
 ```
@@ -69,22 +69,34 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.1.1
+  rev: 0.3.0
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
 ```
 
-If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument. By default, these will be [numpydoc-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#); support for Google-style docstrings will come in a future release:
+If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google` and `numpydoc`). Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.1.1
+  rev: 0.3.0
   hooks:
     - id: docstringify
-      args: [--suggest-changes]
+      args: [--suggest-changes=numpydoc]
 ```
 
+Use `--make-changes` to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html):
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 0.3.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.*).
+
 Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
 
 ### Command line
@@ -124,10 +136,10 @@ test.say_hello is missing a docstring
 If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide a converter:
 
 ```pycon
->>> from docstringify.converters.numpydoc import NumpydocDocstringConverter
+>>> from docstringify.converters import NumpydocDocstringConverter
 >>> from docstringify.visitor import DocstringVisitor
->>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter())
->>> visitor.process_file()
+>>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)
+>>> _ = visitor.process_file()
 test is missing a docstring
 Hint:
 """__description__"""
@@ -144,3 +156,17 @@ name : str, default="World"
 """
 
 ```
+
+To make changes to your files, you will need to use the `DocstringTransformer` instead. With the `DocstringTransformer`, the converter is required:
+
+```pycon
+>>> from docstringify.converters import GoogleDocstringConverter
+>>> from docstringify.transformer import DocstringTransformer
+>>> transformer = DocstringTransformer('test.py', converter=GoogleDocstringConverter)
+>>> _ = transformer.process_file()
+test is missing a docstring
+test.say_hello is missing a docstring
+Docstring templates written to /.../test_docstringify.py
+```
+
+If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`.

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

@@ -12,6 +12,9 @@ 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
@@ -21,4 +24,5 @@ src/docstringify.egg-info/requires.txt
 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

docstringify-0.1.1/src/docstringify/cli.py

@@ -1,71 +0,0 @@
-from __future__ import annotations
-
-import argparse
-import sys
-from typing import Sequence
-
-from . import __version__
-from .converters.numpydoc import NumpydocDocstringConverter
-from .visitor import DocstringVisitor
-
-PROG = __package__
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog=PROG)
-    parser.add_argument(
-        'filenames',
-        nargs='*',
-        help='Filenames to process',
-    )
-    parser.add_argument(
-        '--version', action='version', version=f'%(prog)s {__version__}'
-    )
-
-    parser.add_argument(
-        '--suggest-changes',
-        action='store_true',
-        help='Whether to provide docstring templates for items missing docstrings',
-    )
-    parser.add_argument(
-        '--style',
-        choices=['numpydoc'],
-        default='numpydoc',
-        help='The style of docstring to use (only used when --suggest-changes is passed)',
-    )
-    parser.add_argument(
-        '--threshold',
-        type=float,
-        default=1,
-        help='The percentage of docstrings that must be present to pass',
-    )
-    args = parser.parse_args(argv)
-
-    if args.style is None or not args.suggest_changes:
-        converter = None
-    elif args.style == 'numpydoc':
-        converter = NumpydocDocstringConverter()
-    else:
-        raise NotImplementedError(f'{args.style} is not a supported option')
-
-    docstrings_processed = missing_docstrings = 0
-    for file in args.filenames:
-        visitor = DocstringVisitor(file, converter=converter)
-        visitor.process_file()
-        missing_docstrings += visitor.missing_docstrings
-        docstrings_processed += visitor.docstrings_inspected
-
-    if docstrings_processed and (
-        missing_percentage := (missing_docstrings / docstrings_processed)
-    ) > (1 - args.threshold):
-        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,
-        )
-        return 1
-    return 0
-
-
-if __name__ == '__main__':
-    raise SystemExit(main())

docstringify-0.1.1/src/docstringify/converters/__init__.py

@@ -1 +0,0 @@
-"""Docstring converters."""