docstringify 0.1.0__py3-none-any.whl

docstringify/__init__.py

@@ -0,0 +1,6 @@
+"""
+Flag missing docstrings and, optionally, generate them from signatures and
+type annotations.
+"""
+
+__version__ = '0.1.0'

docstringify/__main__.py

@@ -0,0 +1,5 @@
+"""Enable running `python -m docstringify`."""
+
+from .cli import main
+
+raise SystemExit(main())

docstringify/cli.py

@@ -0,0 +1,71 @@
+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/components.py

@@ -0,0 +1,22 @@
+"""Docstring components."""
+
+from __future__ import annotations
+
+from typing import Final, NamedTuple
+
+NO_DEFAULT: Final = object()
+DESCRIPTION_PLACEHOLDER = '__description__'
+PARAMETER_TYPE_PLACEHOLDER = '__type__'
+RETURN_TYPE_PLACEHOLDER = '__return_type__'
+
+
+class Parameter(NamedTuple):
+    name: str
+    type_: str
+    category: str | None
+    default: str | NO_DEFAULT
+
+
+class Function(NamedTuple):
+    parameters: tuple[Parameter, ...]
+    return_type: str | None

docstringify/converters/__init__.py

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

docstringify/converters/base.py

@@ -0,0 +1,51 @@
+"""Base docstring converter."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..components import Function, Parameter
+
+
+class DocstringConverter(ABC):
+    def __init__(
+        self, parameters_section_template: str, returns_section_template: str
+    ) -> None:
+        self.parameters_section_template = parameters_section_template
+        self.returns_section_template = returns_section_template
+
+    @abstractmethod
+    def to_class_docstring(self, class_name: str) -> str:
+        pass
+
+    @abstractmethod
+    def to_function_docstring(self, function: Function) -> 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 ''

docstringify/converters/numpydoc.py

@@ -0,0 +1,47 @@
+"""Numpydoc-style docstring converter."""
+
+from __future__ import annotations
+
+from ..components import DESCRIPTION_PLACEHOLDER, NO_DEFAULT, Function, Parameter
+from .base import DocstringConverter
+
+
+class NumpydocDocstringConverter(DocstringConverter):
+    def __init__(self) -> None:
+        super().__init__(
+            parameters_section_template='Parameters\n----------\n{parameters}',
+            returns_section_template='Returns\n-------\n{returns}',
+        )
+
+    def to_function_docstring(self, function: Function) -> str:
+        # TODO: the visitor needs the triple quotes but the transformer does not
+        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])
+
+        sep = '' if len(docstring) == 2 else '\n'
+
+        return sep.join([*docstring, '"""'])
+
+    def format_parameter(self, parameter: Parameter) -> str:
+        return (
+            f'{parameter.name} : {parameter.type_}'
+            f'{f", {parameter.category}" if parameter.category else ""}'
+            f'{f", default={parameter.default}" if parameter.default != NO_DEFAULT else ""}'
+            f'\n    {DESCRIPTION_PLACEHOLDER}'
+        )
+
+    def format_return(self, return_type: str | None) -> str:
+        if return_type:
+            return f'{return_type}\n    {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/visitor.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+
+from .components import (
+    NO_DEFAULT,
+    PARAMETER_TYPE_PLACEHOLDER,
+    RETURN_TYPE_PLACEHOLDER,
+    Function,
+    Parameter,
+)
+
+if TYPE_CHECKING:
+    from .converters.base import DocstringConverter
+
+
+class DocstringVisitor(ast.NodeVisitor):
+    def __init__(
+        self, filename: str, converter: DocstringConverter | None = None
+    ) -> 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
+
+    def _extract_default_values(
+        self, default: ast.Constant | None | Literal[NO_DEFAULT], is_keyword_only: bool
+    ) -> str | Literal[NO_DEFAULT]:
+        if (not is_keyword_only and default is not NO_DEFAULT) or (
+            is_keyword_only and default
+        ):
+            try:
+                default_value = default.value
+            except AttributeError:
+                default_value = f'`{default.id}`'
+
+            return (
+                f'"{default_value}"'
+                if isinstance(default_value, str) and not default_value.startswith('`')
+                else default_value
+            )
+        return NO_DEFAULT
+
+    def extract_arguments(
+        self, node: ast.AsyncFunctionDef | ast.FunctionDef
+    ) -> tuple[Parameter, ...]:
+        modifiers = {
+            'posonlyargs': 'positional-only',
+            'kwonlyargs': 'keyword-only',
+        }
+        params = []
+
+        positional_arguments_count = len(node.args.posonlyargs) + len(node.args.args)
+        if (
+            default_count := len(positional_defaults := node.args.defaults)
+        ) < positional_arguments_count:
+            positional_defaults = [NO_DEFAULT] * (
+                positional_arguments_count - default_count
+            ) + positional_defaults
+
+        keyword_defaults = node.args.kw_defaults
+
+        processed_positional_args = 0
+        for arg_type, args in ast.iter_fields(node.args):
+            if arg_type.endswith('defaults'):
+                continue
+            modifier = modifiers.get(arg_type)
+            if arg_type in ['vararg', 'kwarg']:
+                if args:
+                    params.append(
+                        Parameter(
+                            name=f'*{args.arg}'
+                            if arg_type == 'vararg'
+                            else f'**{args.arg}',
+                            type_=getattr(
+                                args.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER
+                            ),
+                            category=modifier,
+                            default=NO_DEFAULT,
+                        )
+                    )
+            else:
+                is_keyword_only = arg_type.startswith('kw')
+                params.extend(
+                    [
+                        Parameter(
+                            name=arg.arg,
+                            type_=getattr(
+                                arg.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER
+                            ),
+                            category=modifier,
+                            default=self._extract_default_values(
+                                default, is_keyword_only
+                            ),
+                        )
+                        for arg, default in zip(
+                            args,
+                            keyword_defaults
+                            if is_keyword_only
+                            else positional_defaults[processed_positional_args:],
+                        )
+                    ]
+                )
+                if not is_keyword_only:
+                    processed_positional_args += len(args)
+
+        params = tuple(params)
+        if (
+            params
+            and isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef)
+            and params[0].name.startswith(('self', 'cls'))
+        ):
+            return params[1:]
+        return params
+
+    def extract_returns(
+        self, node: ast.AsyncFunctionDef | ast.FunctionDef
+    ) -> str | None:
+        if return_node := node.returns:
+            if isinstance(return_node, ast.Constant):
+                return return_node.value
+            if isinstance(return_node, ast.Name):
+                return return_node.id
+            return ast.get_source_segment(self.source_code, return_node)
+        if (
+            return_nodes := [
+                body_node
+                for body_node in node.body
+                if isinstance(body_node, ast.Return)
+            ]
+        ) and any(
+            not isinstance(return_value := body_return_node.value, ast.Constant)
+            or return_value.value
+            for body_return_node in return_nodes
+        ):
+            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
+    ) -> str:
+        if isinstance(node, ast.AsyncFunctionDef | ast.FunctionDef):
+            return self.converter.to_function_docstring(
+                Function(self.extract_arguments(node), self.extract_returns(node))
+            )
+
+        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))

docstringify-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: docstringify
+Version: 0.1.0
+Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
+Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
+License: MIT License
+        
+        Copyright (c) 2025 Stefanie Molin
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+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
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-randomly; extra == "dev"
+Dynamic: license-file
+
+# docstringify
+Flag missing docstrings and, optionally, generate them from signatures and type annotations.
+
+## Usage
+
+### Pre-commit hook
+
+Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings:
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 0.1.0
+  hooks:
+    - id: docstringify
+```
+
+By default, all docstrings are required. If you want to be more lenient, you can set the threshold, which is the percentage of docstrings that must be present:
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 0.1.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:
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 0.1.0
+  hooks:
+    - id: docstringify
+      args: [--suggest-changes]
+```
+
+Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
+
+### Command line
+
+First, install the `docstringify` package from PyPI:
+
+```shell
+$ python -m pip install docstringify
+```
+
+Then, use the `docstringify` entry point on the file(s) of your choice:
+
+```shell
+$ docstringify /path/to/file [/path/to/another/file]
+```
+
+Run `docstringify --help` for more information.
+
+### Python
+
+First, install the `docstringify` package from PyPI:
+
+```shell
+$ 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
+>>> visitor = DocstringVisitor('test.py')
+>>> visitor.process_file()
+test is missing a docstring
+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.visitor import DocstringVisitor
+>>> visitor = DocstringVisitor('test.py', converter=NumpydocDocstringConverter())
+>>> visitor.process_file()
+test is missing a docstring
+Hint:
+"""__description__"""
+
+test.say_hello is missing a docstring
+Hint:
+"""
+__description__
+
+Parameters
+----------
+name : str, default="World"
+    __description__
+"""
+
+```

docstringify-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+docstringify/__init__.py,sha256=uXJ3o6quBR5skKRbCl3u8jRzjsmj6tGr1qb-3QdFf5Q,124
+docstringify/__main__.py,sha256=A5Xq9jCZwHnQVVGklF9ueL-ad-hInsceHQNgze3Yq6E,96
+docstringify/cli.py,sha256=QrEkav5pGGyCRx6w3cI4SOj4CcBx6YIRT48RVfOgFNo,2121
+docstringify/components.py,sha256=7Q__cuBTWNAqLDTil_91Q7T-zIzr7YpbX2TcmXrfph0,471
+docstringify/visitor.py,sha256=zY0nSAwVyIP1Qa0jkfCKLrKEKlIA0xQ6VtBB5R96V00,7024
+docstringify/converters/__init__.py,sha256=vZE16UrOdY29rAkIH0HcFfr_FDhApua24CJoYM-xL6I,28
+docstringify/converters/base.py,sha256=1QWFE5ckS_Rbwi9TyRM-rKCA7MCwHgZ4Ok8ugMyvMgA,1507
+docstringify/converters/numpydoc.py,sha256=iv5smFrHFBc0rHvLhgh66PaV2OEI3va_piRZ3_y2Ig8,1773
+docstringify-0.1.0.dist-info/licenses/LICENSE,sha256=E5RHv_qfCZPwnlJ_ZQb-WKOOy07LaJBA2a160OGtT3U,1071
+docstringify-0.1.0.dist-info/METADATA,sha256=fsJmCbMOiorPafl732Vwa3y6czXWSdGHmL997u_jsBI,5142
+docstringify-0.1.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+docstringify-0.1.0.dist-info/entry_points.txt,sha256=dJVPsbclB7stLE8g0d4WbO2NaZQLJXSLEVl6oeROAqI,55
+docstringify-0.1.0.dist-info/top_level.txt,sha256=3RFmaFG0rYs4HkqRljatGQtY4BcNN7mqjK4tSznYdnQ,13
+docstringify-0.1.0.dist-info/RECORD,,

docstringify-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

docstringify-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+docstringify = docstringify.cli:main

docstringify-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Stefanie Molin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docstringify-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+docstringify