docstringify 0.1.1__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.1.1
+Version: 0.2.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.2.0
   hooks:
     - id: docstringify
 ```
@@ -69,22 +69,32 @@ 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.2.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. By default, these will be [numpydoc-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#):
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.1.1
+  rev: 0.2.0
   hooks:
     - id: docstringify
       args: [--suggest-changes]
 ```
 
+For [Google-style docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html), specify `--style google`:
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 0.2.0
+  hooks:
+    - id: docstringify
+      args: [--suggest-changes, --style=google]
+```
+
 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 +134,7 @@ 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()

{docstringify-0.1.1 → docstringify-0.2.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.2.0
   hooks:
     - id: docstringify
 ```
@@ -18,22 +18,32 @@ 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.2.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. By default, these will be [numpydoc-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#):
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.1.1
+  rev: 0.2.0
   hooks:
     - id: docstringify
       args: [--suggest-changes]
 ```
 
+For [Google-style docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html), specify `--style google`:
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 0.2.0
+  hooks:
+    - id: docstringify
+      args: [--suggest-changes, --style=google]
+```
+
 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 +83,7 @@ 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()

{docstringify-0.1.1 → docstringify-0.2.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.2.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.2.0'

{docstringify-0.1.1 → docstringify-0.2.0}/src/docstringify/cli.py

@@ -5,7 +5,7 @@ import sys
 from typing import Sequence
 
 from . import __version__
-from .converters.numpydoc import NumpydocDocstringConverter
+from .converters import GoogleDocstringConverter, NumpydocDocstringConverter
 from .visitor import DocstringVisitor
 
 PROG = __package__
@@ -25,11 +25,11 @@ def main(argv: Sequence[str] | None = None) -> int:
     parser.add_argument(
         '--suggest-changes',
         action='store_true',
-        help='Whether to provide docstring templates for items missing docstrings',
+        help='Whether to print out docstring templates for items missing docstrings',
     )
     parser.add_argument(
         '--style',
-        choices=['numpydoc'],
+        choices=['google', 'numpydoc'],
         default='numpydoc',
         help='The style of docstring to use (only used when --suggest-changes is passed)',
     )
@@ -43,6 +43,8 @@ def main(argv: Sequence[str] | None = None) -> int:
 
     if args.style is None or not args.suggest_changes:
         converter = None
+    elif args.style == 'google':
+        converter = GoogleDocstringConverter()
     elif args.style == 'numpydoc':
         converter = NumpydocDocstringConverter()
     else:

docstringify-0.2.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.2.0/src/docstringify/converters/google.py

@@ -0,0 +1,46 @@
+"""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) -> None:
+        super().__init__(
+            parameters_section_template='Args:\n{parameters}',
+            returns_section_template='Returns:\n    {returns}',
+        )
+
+    def to_function_docstring(self, function: Function) -> str:
+        # TODO: the visitor needs the triple quotes but the transformer does not
+        docstring = [f'"""{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])
+
+        sep = '' if len(docstring) == 1 else '\n'
+
+        return sep.join([*docstring, '"""'])
+
+    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 f'"""{DESCRIPTION_PLACEHOLDER}"""'
+
+    def to_class_docstring(self, class_name: str) -> str:
+        return f'"""{DESCRIPTION_PLACEHOLDER}"""'

{docstringify-0.1.1 → docstringify-0.2.0}/src/docstringify/visitor.py

@@ -14,7 +14,7 @@ from .components import (
 )
 
 if TYPE_CHECKING:
-    from .converters.base import DocstringConverter
+    from .converters import DocstringConverter
 
 
 class DocstringVisitor(ast.NodeVisitor):

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.1.1
+Version: 0.2.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.2.0
   hooks:
     - id: docstringify
 ```
@@ -69,22 +69,32 @@ 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.2.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. By default, these will be [numpydoc-style docstrings](https://numpydoc.readthedocs.io/en/latest/format.html#):
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.1.1
+  rev: 0.2.0
   hooks:
     - id: docstringify
       args: [--suggest-changes]
 ```
 
+For [Google-style docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html), specify `--style google`:
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 0.2.0
+  hooks:
+    - id: docstringify
+      args: [--suggest-changes, --style=google]
+```
+
 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 +134,7 @@ 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()

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

@@ -21,4 +21,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/converters/__init__.py

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