docstringify 0.4.0__tar.gz → 0.5.1__tar.gz

{docstringify-0.4.0 → docstringify-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.4.0
+Version: 0.5.1
 Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
 License: MIT License
@@ -49,9 +49,58 @@ Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-randomly; extra == "dev"
 Dynamic: license-file
 
-# docstringify
+# Docstringify
 Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 
+## About
+
+Given a file, `test.py`, with the following contents:
+
+```python
+def say_hello(name: str = 'World') -> None:
+    print(f'Hello, {name}!')
+```
+
+You can use Docstringify in three modes:
+
+1. Flag missing docstrings:
+    ```
+    test is missing a docstring
+    test.say_hello is missing a docstring
+    ```
+2. Suggest docstring templates based on type annotations:
+    ```
+    test is missing a docstring
+    Hint:
+    """__description__"""
+
+    test.say_hello is missing a docstring
+    Hint:
+    """
+    __description__
+
+    Parameters
+    ----------
+    name : str, default="World"
+        __description__
+    """
+    ```
+3. Add docstring templates to source code files:
+    ```python
+    """__description__"""
+
+    def say_hello(name: str = 'World') -> None:
+        """
+        __description__
+
+        Parameters
+        ----------
+        name : str, default="World"
+            __description__
+        """
+        print(f'Hello, {name}!')
+    ```
+
 ## Usage
 
 ### Pre-commit hook
@@ -60,7 +109,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.4.0
+  rev: 0.5.1
   hooks:
     - id: docstringify
 ```
@@ -69,7 +118,7 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.4.0
+  rev: 0.5.1
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
@@ -79,7 +128,7 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.4.0
+  rev: 0.5.1
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -89,7 +138,7 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.4.0
+  rev: 0.5.1
   hooks:
     - id: docstringify
       args: [--make-changes=google]
@@ -170,3 +219,7 @@ Docstring templates written to /.../test_docstringify.py
 ```
 
 If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`.
+
+## Contributing
+
+Please consult the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md).

{docstringify-0.4.0 → docstringify-0.5.1}/README.md

@@ -1,6 +1,55 @@
-# docstringify
+# Docstringify
 Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 
+## About
+
+Given a file, `test.py`, with the following contents:
+
+```python
+def say_hello(name: str = 'World') -> None:
+    print(f'Hello, {name}!')
+```
+
+You can use Docstringify in three modes:
+
+1. Flag missing docstrings:
+    ```
+    test is missing a docstring
+    test.say_hello is missing a docstring
+    ```
+2. Suggest docstring templates based on type annotations:
+    ```
+    test is missing a docstring
+    Hint:
+    """__description__"""
+
+    test.say_hello is missing a docstring
+    Hint:
+    """
+    __description__
+
+    Parameters
+    ----------
+    name : str, default="World"
+        __description__
+    """
+    ```
+3. Add docstring templates to source code files:
+    ```python
+    """__description__"""
+
+    def say_hello(name: str = 'World') -> None:
+        """
+        __description__
+
+        Parameters
+        ----------
+        name : str, default="World"
+            __description__
+        """
+        print(f'Hello, {name}!')
+    ```
+
 ## Usage
 
 ### Pre-commit hook
@@ -9,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.4.0
+  rev: 0.5.1
   hooks:
     - id: docstringify
 ```
@@ -18,7 +67,7 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.4.0
+  rev: 0.5.1
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
@@ -28,7 +77,7 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.4.0
+  rev: 0.5.1
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -38,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.4.0
+  rev: 0.5.1
   hooks:
     - id: docstringify
       args: [--make-changes=google]
@@ -119,3 +168,7 @@ Docstring templates written to /.../test_docstringify.py
 ```
 
 If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`.
+
+## Contributing
+
+Please consult the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md).

{docstringify-0.4.0 → docstringify-0.5.1}/src/docstringify/__init__.py

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

{docstringify-0.4.0 → docstringify-0.5.1}/src/docstringify/cli.py

@@ -76,7 +76,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     for file in args.filenames:
         processor = get_docstring_processor(file)
         processor.process_file()
-        missing_docstrings += processor.missing_docstrings
+        missing_docstrings += len(processor.missing_docstrings)
         docstrings_processed += processor.docstrings_inspected
 
     if docstrings_processed and (

{docstringify-0.4.0 → docstringify-0.5.1}/src/docstringify/converters/base.py

@@ -7,7 +7,6 @@ import textwrap
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING
 
-from ..components import Function
 from ..exceptions import InvalidDocstringError
 
 if TYPE_CHECKING:
@@ -27,15 +26,15 @@ class DocstringConverter(ABC):
         self._quote = quote
 
     @abstractmethod
-    def to_class_docstring(self, class_name: str, indent: int) -> str:
+    def to_class_docstring(self, docstring_node: DocstringNode, indent: int) -> str:
         pass
 
     @abstractmethod
-    def to_function_docstring(self, function: Function, indent: int) -> str:
+    def to_function_docstring(self, docstring_node: DocstringNode, indent: int) -> str:
         pass
 
     @abstractmethod
-    def to_module_docstring(self, module_name: str) -> str:
+    def to_module_docstring(self, docstring_node: DocstringNode) -> str:
         pass
 
     @abstractmethod
@@ -79,16 +78,15 @@ class DocstringConverter(ABC):
         self,
         docstring_node: DocstringNode,
         indent: int = 0,
-    ) -> str:
+    ) -> str | None:
         if isinstance(docstring_node.ast_node, ast.AsyncFunctionDef | ast.FunctionDef):
-            return self.to_function_docstring(
-                Function(
-                    docstring_node.extract_arguments(), docstring_node.extract_returns()
-                ),
-                indent=indent,
+            return (
+                self.to_function_docstring(docstring_node, indent=indent)
+                if docstring_node.docstring_required
+                else None
             )
 
         if isinstance(docstring_node.ast_node, ast.Module):
-            return self.to_module_docstring(docstring_node.module_name)
+            return self.to_module_docstring(docstring_node)
 
-        return self.to_class_docstring(docstring_node.name, indent=indent)
+        return self.to_class_docstring(docstring_node, indent=indent)

{docstringify-0.4.0 → docstringify-0.5.1}/src/docstringify/converters/google.py

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

{docstringify-0.4.0 → docstringify-0.5.1}/src/docstringify/converters/numpydoc.py

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

{docstringify-0.4.0 → docstringify-0.5.1}/src/docstringify/nodes/base.py

@@ -33,13 +33,16 @@ class DocstringNode:
     ) -> None:
         self.module_name: str = module_name
         self.parent: DocstringNode | None = parent
+        self.docstring_required: bool = True
 
         self.ast_node: (
             ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef
         ) = node
         self.name: str = getattr(node, 'name', self.module_name)
 
-        self.docstring = ast.get_docstring(node)
+        docstring = ast.get_docstring(node)
+        self.docstring = docstring if docstring is None else docstring.strip()
+
         self.get_source_segment: Callable[[ast.AST], str] = partial(
             ast.get_source_segment, source_code
         )

{docstringify-0.4.0 → docstringify-0.5.1}/src/docstringify/nodes/function.py

@@ -8,6 +8,7 @@ from ..components import (
     NO_DEFAULT,
     PARAMETER_TYPE_PLACEHOLDER,
     RETURN_TYPE_PLACEHOLDER,
+    Function,
     Parameter,
 )
 from .base import DocstringNode
@@ -41,6 +42,11 @@ class FunctionDocstringNode(DocstringNode):
             self.is_method and not self.is_class_method and not self.is_static_method
         )
 
+        # don't require docstring for the __init__ method if the class has a docstring
+        self.docstring_required: bool = not (
+            self.is_method and self.name == '__init__' and self.parent.docstring
+        )
+
         self.arguments: ast.arguments | None = getattr(node, 'args', None)
         self.return_annotation: str | None = self._extract_return_annotation()
         self.return_statements: list[ast.Return] = []
@@ -157,3 +163,6 @@ class FunctionDocstringNode(DocstringNode):
         ):
             return RETURN_TYPE_PLACEHOLDER
         return None
+
+    def to_function(self) -> Function:
+        return Function(self.extract_arguments(), self.extract_returns())

{docstringify-0.4.0 → docstringify-0.5.1}/src/docstringify/traversal/transformer.py

@@ -45,10 +45,7 @@ class DocstringTransformer(ast.NodeTransformer, DocstringVisitor):
         )
         docstring_ast_node = ast.Expr(ast.Constant(suggested_docstring))
 
-        if (
-            docstring_node.docstring is not None
-            and docstring_node.docstring.strip() == ''
-        ):
+        if docstring_node.docstring is not None:
             # If the docstring is empty, we replace it with the suggested docstring
             docstring_node.ast_node.body[0] = docstring_ast_node
         else:

{docstringify-0.4.0 → docstringify-0.5.1}/src/docstringify/traversal/visitor.py

@@ -37,7 +37,6 @@ class DocstringVisitor(ast.NodeVisitor):
             print(f'No missing docstrings found in {self.source_file}.')
         else:
             for docstring_node in self.missing_docstrings:
-                # TODO: need to print full path for node name
                 print(
                     f'{docstring_node.fully_qualified_name} is missing a docstring',
                     file=sys.stderr,
@@ -51,7 +50,7 @@ class DocstringVisitor(ast.NodeVisitor):
             print()
 
     def process_docstring(self, docstring_node: DocstringNode) -> DocstringNode:
-        if docstring_node.docstring is None or docstring_node.docstring.strip() == '':
+        if docstring_node.docstring_required and not docstring_node.docstring:
             self.missing_docstrings.append(docstring_node)
 
         self.docstrings_inspected += 1

{docstringify-0.4.0 → docstringify-0.5.1}/src/docstringify.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.4.0
+Version: 0.5.1
 Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
 License: MIT License
@@ -49,9 +49,58 @@ Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-randomly; extra == "dev"
 Dynamic: license-file
 
-# docstringify
+# Docstringify
 Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 
+## About
+
+Given a file, `test.py`, with the following contents:
+
+```python
+def say_hello(name: str = 'World') -> None:
+    print(f'Hello, {name}!')
+```
+
+You can use Docstringify in three modes:
+
+1. Flag missing docstrings:
+    ```
+    test is missing a docstring
+    test.say_hello is missing a docstring
+    ```
+2. Suggest docstring templates based on type annotations:
+    ```
+    test is missing a docstring
+    Hint:
+    """__description__"""
+
+    test.say_hello is missing a docstring
+    Hint:
+    """
+    __description__
+
+    Parameters
+    ----------
+    name : str, default="World"
+        __description__
+    """
+    ```
+3. Add docstring templates to source code files:
+    ```python
+    """__description__"""
+
+    def say_hello(name: str = 'World') -> None:
+        """
+        __description__
+
+        Parameters
+        ----------
+        name : str, default="World"
+            __description__
+        """
+        print(f'Hello, {name}!')
+    ```
+
 ## Usage
 
 ### Pre-commit hook
@@ -60,7 +109,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.4.0
+  rev: 0.5.1
   hooks:
     - id: docstringify
 ```
@@ -69,7 +118,7 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.4.0
+  rev: 0.5.1
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
@@ -79,7 +128,7 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.4.0
+  rev: 0.5.1
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -89,7 +138,7 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.4.0
+  rev: 0.5.1
   hooks:
     - id: docstringify
       args: [--make-changes=google]
@@ -170,3 +219,7 @@ Docstring templates written to /.../test_docstringify.py
 ```
 
 If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`.
+
+## Contributing
+
+Please consult the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md).