docstringify 0.7.0__tar.gz → 1.0.0__tar.gz

{docstringify-0.7.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.6.0
+    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.7.0 → docstringify-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.7.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.7.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.7.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`, `numpydoc`, and `stub`). 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.7.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.7.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.7.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.7.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.7.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`, `numpydoc`, and `stub`). 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.7.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.7.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.7.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.7.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.7.0'
+__version__ = '1.0.0'

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

@@ -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__)
 

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.7.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,7 +81,8 @@ 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
@@ -95,8 +113,9 @@ class FunctionDocstringNode(DocstringNode):
 
     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
@@ -155,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.7.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.7.0 → docstringify-1.0.0}/src/docstringify/traversal/visitor.py

@@ -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
         ----------
@@ -181,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.7.0 → docstringify-1.0.0}/src/docstringify.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.7.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.7.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.7.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`, `numpydoc`, and `stub`). 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.7.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.7.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.7.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}')