docstringify 0.2.0__tar.gz → 0.4.0__tar.gz

docstringify-0.4.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Something isn't working
+title: "[BUG] "
+labels: bug
+assignees: ''
+
+---
+
+**Required attestation**
+- [ ] I have checked that this issue has not already been reported.
+- [ ] I have confirmed this bug exists on the latest version of docstringify.
+- [ ] I have confirmed this bug exists on the `main` branch of docstringify.
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment**
+- OS: [e.g. iOS]
+- Python Version [e.g. 3.12]
+
+**Additional context**
+Add any other context about the problem here.

docstringify-0.4.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

docstringify-0.4.0/.github/workflows/greetings.yml

@@ -0,0 +1,16 @@
+name: Greetings
+
+on: [pull_request_target, issues]
+
+jobs:
+  greeting:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+    - uses: actions/first-interaction@34f15e814fe48ac9312ccf29db4e74fa767cbab7  # v1.3.0
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        issue-message: "It looks like this is your first issue here – welcome! Please familiarize yourself with the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md), if you haven't already."
+        pr-message: "Congratulations on making your first pull request to `docstringify`! Please familiarize yourself with the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md), if you haven't already."

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.2.0
+Version: 0.4.0
 Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
 License: MIT License
@@ -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.2.0
+  rev: 0.4.0
   hooks:
     - id: docstringify
 ```
@@ -69,32 +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.2.0
+  rev: 0.4.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#):
+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.2.0
+  rev: 0.4.0
   hooks:
     - id: docstringify
-      args: [--suggest-changes]
+      args: [--suggest-changes=numpydoc]
 ```
 
-For [Google-style docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html), specify `--style google`:
+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.2.0
+  rev: 0.4.0
   hooks:
     - id: docstringify
-      args: [--suggest-changes, --style=google]
+      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,7 +126,7 @@ $ python -m pip install docstringify
 Then, use the `DocstringVisitor()` class on individual files to see spots where docstrings are missing:
 
 ```pycon
->>> from docstringify.visitor import DocstringVisitor
+>>> from docstringify.traversal import DocstringVisitor
 >>> visitor = DocstringVisitor('test.py')
 >>> visitor.process_file()
 test is missing a docstring
@@ -135,8 +137,8 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```pycon
 >>> from docstringify.converters import NumpydocDocstringConverter
->>> from docstringify.visitor import DocstringVisitor
->>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter())
+>>> from docstringify.traversal import DocstringVisitor
+>>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)
 >>> visitor.process_file()
 test is missing a docstring
 Hint:
@@ -154,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.traversal 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.2.0 → docstringify-0.4.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.2.0
+  rev: 0.4.0
   hooks:
     - id: docstringify
 ```
@@ -18,32 +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.2.0
+  rev: 0.4.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#):
+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.2.0
+  rev: 0.4.0
   hooks:
     - id: docstringify
-      args: [--suggest-changes]
+      args: [--suggest-changes=numpydoc]
 ```
 
-For [Google-style docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html), specify `--style google`:
+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.2.0
+  rev: 0.4.0
   hooks:
     - id: docstringify
-      args: [--suggest-changes, --style=google]
+      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,7 +75,7 @@ $ python -m pip install docstringify
 Then, use the `DocstringVisitor()` class on individual files to see spots where docstrings are missing:
 
 ```pycon
->>> from docstringify.visitor import DocstringVisitor
+>>> from docstringify.traversal import DocstringVisitor
 >>> visitor = DocstringVisitor('test.py')
 >>> visitor.process_file()
 test is missing a docstring
@@ -84,8 +86,8 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```pycon
 >>> from docstringify.converters import NumpydocDocstringConverter
->>> from docstringify.visitor import DocstringVisitor
->>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter())
+>>> from docstringify.traversal import DocstringVisitor
+>>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter)
 >>> visitor.process_file()
 test is missing a docstring
 Hint:
@@ -103,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.traversal 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.2.0 → docstringify-0.4.0}/src/docstringify/__init__.py

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

docstringify-0.4.0/src/docstringify/cli.py

@@ -0,0 +1,95 @@
+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 .traversal import DocstringTransformer, 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'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.4.0/src/docstringify/converters/base.py

@@ -0,0 +1,94 @@
+"""Base docstring converter."""
+
+from __future__ import annotations
+
+import ast
+import textwrap
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from ..components import Function
+from ..exceptions import InvalidDocstringError
+
+if TYPE_CHECKING:
+    from ..components import Parameter
+    from ..nodes.base import DocstringNode
+
+
+class DocstringConverter(ABC):
+    def __init__(
+        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, indent: int) -> str:
+        pass
+
+    @abstractmethod
+    def to_function_docstring(self, function: Function, indent: int) -> str:
+        pass
+
+    @abstractmethod
+    def to_module_docstring(self, module_name: str) -> str:
+        pass
+
+    @abstractmethod
+    def format_parameter(self, parameter: Parameter) -> str:
+        pass
+
+    def parameters_section(self, parameters: tuple[Parameter, ...]) -> str:
+        if parameters:
+            return self.parameters_section_template.format(
+                parameters='\n'.join(
+                    self.format_parameter(parameter) for parameter in parameters
+                )
+            )
+        return ''
+
+    @abstractmethod
+    def format_return(self, return_type: str | None) -> str:
+        pass
+
+    def returns_section(self, return_type: str | None) -> str:
+        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)
+
+    def suggest_docstring(
+        self,
+        docstring_node: DocstringNode,
+        indent: int = 0,
+    ) -> str:
+        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,
+            )
+
+        if isinstance(docstring_node.ast_node, ast.Module):
+            return self.to_module_docstring(docstring_node.module_name)
+
+        return self.to_class_docstring(docstring_node.name, indent=indent)

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

@@ -7,15 +7,15 @@ from .base import DocstringConverter
 
 
 class GoogleDocstringConverter(DocstringConverter):
-    def __init__(self) -> None:
+    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) -> str:
-        # TODO: the visitor needs the triple quotes but the transformer does not
-        docstring = [f'"""{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,14 +23,12 @@ class GoogleDocstringConverter(DocstringConverter):
         if returns_section := self.returns_section(function.return_type):
             docstring.extend(['', returns_section])
 
-        sep = '' if len(docstring) == 1 else '\n'
-
-        return sep.join([*docstring, '"""'])
+        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'    {parameter.name} ({parameter.type_}{category}): {DESCRIPTION_PLACEHOLDER}'
             f'{f" Defaults to {parameter.default}." if parameter.default != NO_DEFAULT else ""}'
         )
 
@@ -40,7 +38,7 @@ class GoogleDocstringConverter(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.2.0 → docstringify-0.4.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.4.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.4.0/src/docstringify/nodes/__init__.py

@@ -0,0 +1 @@
+"""Docstringify nodes."""

docstringify-0.4.0/src/docstringify/nodes/base.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import ast
+from functools import partial
+from typing import Callable, overload
+
+
+class DocstringNode:
+    @overload
+    def __init__(
+        self,
+        node: ast.Module,
+        module_name: str,
+        source_code: str,
+        parent: None = None,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        node: ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef,
+        module_name: str,
+        source_code: str,
+        parent: DocstringNode,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        node: ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef,
+        module_name: str,
+        source_code: str,
+        parent: DocstringNode | None = None,
+    ) -> None:
+        self.module_name: str = module_name
+        self.parent: DocstringNode | None = parent
+
+        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)
+        self.get_source_segment: Callable[[ast.AST], str] = partial(
+            ast.get_source_segment, source_code
+        )
+
+    @property
+    def fully_qualified_name(self) -> str:
+        return (
+            f'{self.parent.fully_qualified_name}.{self.name}'
+            if self.parent
+            else self.name
+        )