docstringify 1.0.0__tar.gz → 1.1.0__tar.gz

{docstringify-1.0.0 → docstringify-1.1.0}/.github/dependabot.yml

@@ -9,3 +9,7 @@ updates:
     schedule:
       # Check for updates to GitHub Actions every month
       interval: "monthly"
+    groups:
+      actions:
+        patterns:
+          - "*"

{docstringify-1.0.0 → docstringify-1.1.0}/.github/workflows/ci.yml

@@ -22,6 +22,8 @@ on:
       - '!.github/**'
       - '.github/workflows/ci.yml'
 
+  workflow_dispatch:
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
@@ -60,8 +62,8 @@ jobs:
       - name: Check entry point
         run: docstringify --version
 
-      - name: Install testing dependencies
-        run: python -m pip install '.[dev]'
+      - name: Install dev dependencies
+        run: python -m pip install --group dev
 
       - name: Validate pre-commit hook
         run: pre-commit try-repo . docstringify

{docstringify-1.0.0 → docstringify-1.1.0}/.pre-commit-config.yaml

@@ -11,14 +11,20 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
 
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.9.0
+    hooks:
+      - id: numpydoc-validation
+        exclude: (tests|docs)/.*
+
   - repo: https://github.com/stefmolin/docstringify
-    rev: 0.7.0
+    rev: 1.0.0
     hooks:
       - id: docstringify
         args: [--make-changes-inplace=numpydoc]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.10
+    rev: v0.12.2
     hooks:
       - id: ruff-check
         args: [--fix, --exit-non-zero-on-fix, --show-fixes]
@@ -29,9 +35,3 @@ repos:
     hooks:
       - id: pyproject-fmt
         args: [--keep-full-version, --no-print-diff]
-
-  - repo: https://github.com/numpy/numpydoc
-    rev: v1.8.0
-    hooks:
-      - id: numpydoc-validation
-        exclude: (tests|docs)/.*

docstringify-1.1.0/.python-version

@@ -0,0 +1 @@
+3.13

{docstringify-1.0.0 → docstringify-1.1.0}/CONTRIBUTING.md

@@ -9,7 +9,7 @@ Open up an issue describing in detail the bug or feature request you are proposi
 Once you have been given the go ahead, you can start working on the code. Start by forking the project, cloning locally, and then creating a branch to work on. You will need to then install main dependencies as well as the `dev` dependencies, which can be done by running the following command:
 
 ```shell
-$ pip install -e '.[dev]'
+$ pip install -e . --group dev
 ```
 
 Set up the pre-commit hooks to make sure you can pass the CI checks:

{docstringify-1.0.0 → docstringify-1.1.0}/PKG-INFO

@@ -1,33 +1,13 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 1.0.0
+Version: 1.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
+Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
+License-Expression: MIT
+License-File: LICENSE
 Keywords: ast,docstring generation,google-style docstring,numpydoc-style docstring,pre-commit
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
@@ -39,13 +19,6 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.9
 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.
@@ -107,7 +80,7 @@ Add the following to your `.pre-commit-config.yaml` file to block commits with m
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 1.0.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
 ```
@@ -116,7 +89,7 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 1.0.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
@@ -126,7 +99,7 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 1.0.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -136,7 +109,7 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 1.0.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
       args: [--make-changes=google]
@@ -146,7 +119,7 @@ If you want the changes to be made in place, change `--make-changes` to `--make-
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 1.0.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
       args: [--make-changes-inplace=numpydoc]

{docstringify-1.0.0 → docstringify-1.1.0}/README.md

@@ -58,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: 1.0.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
 ```
@@ -67,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: 1.0.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
@@ -77,7 +77,7 @@ If you would like to see suggested docstring templates (inferred from type annot
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 1.0.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -87,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: 1.0.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
       args: [--make-changes=google]
@@ -97,7 +97,7 @@ If you want the changes to be made in place, change `--make-changes` to `--make-
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 1.0.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
       args: [--make-changes-inplace=numpydoc]

{docstringify-1.0.0 → docstringify-1.1.0}/pyproject.toml

@@ -1,13 +1,11 @@
 [build-system]
-build-backend = "setuptools.build_meta"
+build-backend = "hatchling.build"
 
-requires = [
-  "setuptools",
-  "setuptools-scm",
-]
+requires = [ "hatchling" ]
 
 [project]
 name = "docstringify"
+version = "1.1.0"
 description = "Flag missing docstrings and, optionally, generate them from signatures and type annotations."
 readme = "README.md"
 keywords = [
@@ -17,7 +15,8 @@ keywords = [
   "numpydoc-style docstring",
   "pre-commit",
 ]
-license = { file = "LICENSE" }
+license = "MIT"
+license-files = [ "LICENSE" ]
 authors = [
   { name = "Stefanie Molin", email = "docstringify@stefaniemolin.com" },
 ]
@@ -32,29 +31,21 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
 ]
-dynamic = [
-  "version",
-]
 
 dependencies = [  ]
-optional-dependencies.dev = [
-  "pre-commit",
-  "pytest",
-  "pytest-cov",
-  "pytest-randomly",
-]
 urls.Documentation = "https://github.com/stefmolin/docstringify"
 urls.Homepage = "https://github.com/stefmolin/docstringify"
 urls.Source = "https://github.com/stefmolin/docstringify"
 scripts.docstringify = "docstringify.cli:main"
 
-[tool.setuptools.packages.find]
-where = [
-  "src",
-]
+[dependency-groups]
+dev = [ "pre-commit", { include-group = "test" } ]
 
-[tool.setuptools.dynamic]
-version = { attr = "docstringify.__version__" }
+test = [
+  "pytest>=8.3.4",
+  "pytest-cov>=4.1.0",
+  "pytest-randomly>=3.12.0",
+]
 
 [tool.ruff]
 line-length = 88
@@ -96,6 +87,7 @@ lint.isort.known-first-party = [
 [tool.numpydoc_validation]
 checks = [
   "all",  # report on all checks
+  "GL08", # use Docstringify to test for docstring presence instead
   "ES01", # but don't require an extended summary
   "EX01", # or examples
   "SA01", # or a see also section
@@ -106,6 +98,6 @@ exclude = [ # don't report on checks for these
   '\.__repr__$',
   '\.__str__$',
 ]
-override_SS05 = [ # override SS05 to allow docstrings starting with these words
-  '^Process ',
+override_SS05 = [ # allow docstrings to start with these words
+  '^Unambiguous ',
 ]

docstringify-1.1.0/src/docstringify/__init__.py

@@ -0,0 +1,10 @@
+"""
+Flag missing docstrings and, optionally, generate them from signatures and
+type annotations.
+"""
+
+import importlib.metadata
+
+__version__ = importlib.metadata.version(__name__)
+
+__all__ = ['__version__']

docstringify-1.1.0/src/docstringify/components.py

@@ -0,0 +1,47 @@
+"""Docstring components."""
+
+from __future__ import annotations
+
+from typing import Final, NamedTuple
+
+NO_DEFAULT: Final = object()
+"""Sentinel value indicating that there is no default value. This is necessary because
+``None`` has a different meaning in certain contexts of the AST traversal."""
+
+DESCRIPTION_PLACEHOLDER: Final[str] = '__description__'
+"""Docstring placeholder for description fields."""
+
+PARAMETER_TYPE_PLACEHOLDER: Final[str] = '__type__'
+"""Docstring placeholder for the parameter type, when Docstringify can't determine it."""
+
+RETURN_TYPE_PLACEHOLDER: Final[str] = '__return_type__'
+"""Docstring placeholder for the return type, when Docstringify can't determine it."""
+
+
+class Parameter(NamedTuple):
+    """Information about an individual parameter to a function."""
+
+    name: str
+    """The name of the parameter."""
+
+    type_: str
+    """The parameter's data type."""
+
+    category: str | None
+    """The parameter's category, if there is one. This is used to pass additional
+    information, for example, to indicate that an argument is positional-only."""
+
+    default: str | NO_DEFAULT
+    """A string specifying the default value, if there is one, otherwise,
+    :const:`.NO_DEFAULT`."""
+
+
+class Function(NamedTuple):
+    """Information about a function."""
+
+    parameters: tuple[Parameter, ...]
+    """Information about the function's parameters stored as :class:`.Parameter`
+    instances."""
+
+    return_type: str | None
+    """The return type for the function as a string, if present, otherwise, ``None``."""

{docstringify-1.0.0 → docstringify-1.1.0}/src/docstringify/nodes/base.py

@@ -1,3 +1,5 @@
+"""Base Docstringify traversal node."""
+
 from __future__ import annotations
 
 import ast
@@ -6,6 +8,21 @@ from typing import Callable, overload
 
 
 class DocstringNode:
+    """
+    Base class for Docstringify traversal nodes.
+
+    Parameters
+    ----------
+    node : ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef
+        AST node representing a module, class, or function.
+    module_name : str
+        The name of the module to which the node belongs.
+    source_code : str
+        The source code for the module from which ``node`` originates.
+    parent : DocstringNode | None, default=None
+        The parent node, if there is one.
+    """
+
     @overload
     def __init__(
         self,
@@ -32,25 +49,50 @@ class DocstringNode:
         parent: DocstringNode | None = None,
     ) -> None:
         self.module_name: str = module_name
+        """The name of the module to which the node belongs."""
+
         self.parent: DocstringNode | None = parent
+        """The parent node, if there is one."""
+
         self.docstring_required: bool = True
+        """Whether the node requires a docstring."""
 
         self.ast_node: (
             ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef
         ) = node
+        """The AST node that represents the source code."""
+
         self.name: str = getattr(node, 'name', self.module_name)
+        """The name of the node."""
 
         self.get_source_segment: Callable[[ast.AST], str | None] = partial(
             ast.get_source_segment, source_code
         )
+        """Callable to get the source code for the AST node (:attr:`.ast_node`)."""
 
     @property
     def docstring(self) -> str | None:
+        """
+        Get the docstring from the AST node.
+
+        Returns
+        -------
+        str | None
+            The docstring, if it exists.
+        """
         docstring = ast.get_docstring(self.ast_node)
         return docstring if docstring is None else docstring.strip()
 
     @property
     def fully_qualified_name(self) -> str:
+        """
+        Unambiguous name for the node.
+
+        Returns
+        -------
+        str
+            The fully-qualified name.
+        """
         return (
             f'{self.parent.fully_qualified_name}.{self.name}'
             if self.parent

{docstringify-1.0.0 → docstringify-1.1.0}/src/docstringify/nodes/function.py

@@ -1,3 +1,5 @@
+"""Docstringify traversal node for functions."""
+
 from __future__ import annotations
 
 import ast
@@ -15,6 +17,21 @@ from .base import DocstringNode
 
 
 class FunctionDocstringNode(DocstringNode):
+    """
+    Class for Docstringify function traversal nodes.
+
+    Parameters
+    ----------
+    node : ast.FunctionDef | ast.AsyncFunctionDef
+        AST node representing a function.
+    module_name : str
+        The name of the module to which the node belongs.
+    source_code : str
+        The source code for the module from which ``node`` originates.
+    parent : DocstringNode
+        The parent node.
+    """
+
     def __init__(
         self,
         node: ast.FunctionDef | ast.AsyncFunctionDef,
@@ -29,26 +46,45 @@ class FunctionDocstringNode(DocstringNode):
             for decorator_node in node.decorator_list
             if (decorator := self.get_source_segment(decorator_node))
         ]
+        """List of decorators applied to this function."""
 
         self.is_overload: bool = (
             'overload' in self.decorators or 'typing.overload' in self.decorators
         )
+        """Whether this function definition is actually just a typing overload
+        definition, and, therefore, doesn't need a docstring."""
+
         self.is_method: bool = self.parent is not None and isinstance(
             self.parent.ast_node, ast.ClassDef
         )
+        """Whether this function is actually a method, meaning that its parent node
+        is a class."""
+
         self.is_abstract_method: bool = self.is_method and (
             'abstractmethod' in self.decorators
             or 'abc.abstractmethod' in self.decorators
         )
+        """Whether this function is an abstract method, meaning it is a method
+        (:attr:`.is_method`) and has an ``abstractmethod`` decorator."""
+
         self.is_class_method: bool = self.is_method and 'classmethod' in self.decorators
+        """Whether this function is a class method, meaning it is a method
+        (:attr:`.is_method`) and has a ``classmethod`` decorator."""
+
         self.is_static_method: bool = (
             self.is_method and 'staticmethod' in self.decorators
         )
+        """Whether this function is a static method, meaning it is a method
+        (:attr:`.is_method`) and has a ``staticmethod`` decorator."""
+
         self.is_instance_method: bool = (
             self.is_method
             and (not self.is_class_method)
             and (not self.is_static_method)
         )
+        """Whether this function is an instance method, meaning it is a method
+        (:attr:`.is_method`), but it is not a class method (:attr:`.is_class_method`)
+        or static method (:attr:`.is_static_method`)."""
 
         # don't require docstring for the __init__ method if the class has a docstring
         # or if the function/method is just a typing.overload signature
@@ -61,16 +97,69 @@ class FunctionDocstringNode(DocstringNode):
             )
             and not self.is_overload
         )
+        """Whether this node should have a docstring. Docstrings are currently required
+        for all functions unless they are a typing overload. Note that ``__init__()``
+        methods don't require a docstring if the parent (the class) has a docstring."""
 
         self.arguments: ast.arguments = node.args
+        """The function arguments in their AST representation."""
 
         self.returns: ast.AST | None = node.returns
+        """The function's return annotation, as an AST node, if there is a return
+        annotation, otherwise ``None``."""
+
         self.return_annotation: str | None = self._extract_return_annotation()
+        """The function's return annotation, as a string, if there is a return
+        annotation, otherwise ``None``."""
+
         self.return_statements: list[ast.Return] = []
+        """All ``return`` calls in the function itself (not any inner functions, for
+        example), represented as AST nodes. Note that this will be populated by the
+        traversal logic when those nodes are visited."""
+
+    def _extract_parameter_type(self, arg: ast.arg) -> str:
+        """
+        Extract the parameter's type.
+
+        Parameters
+        ----------
+        arg : ast.arg
+            The AST node for the function argument.
+
+        Returns
+        -------
+        str
+            The parameter type for use in the docstring.
+        """
+        if arg.annotation is None:
+            return PARAMETER_TYPE_PLACEHOLDER
+
+        try:
+            # if `arg.annotation` is of type `ast.Name`, we can just get the `id`
+            return arg.annotation.id
+        except AttributeError:
+            return self.get_source_segment(arg.annotation) or PARAMETER_TYPE_PLACEHOLDER
 
     def _extract_default_values(
         self, default: ast.Constant | None | Literal[NO_DEFAULT], is_keyword_only: bool
     ) -> str | Literal[NO_DEFAULT]:
+        """
+        Extract the argument's default value.
+
+        Parameters
+        ----------
+        default : ast.Constant | None | Literal[NO_DEFAULT]
+            The representation of the default value for further processing.
+        is_keyword_only : bool
+            Whether the default value being extracted corresponds to a keyword-only
+            argument.
+
+        Returns
+        -------
+        str | Literal[NO_DEFAULT]
+            The default value as a string, if there is one, otherwise,
+            :const:`.NO_DEFAULT`.
+        """
         if (not is_keyword_only and default is not NO_DEFAULT) or (
             is_keyword_only and default
         ):
@@ -101,7 +190,7 @@ class FunctionDocstringNode(DocstringNode):
         return [
             Parameter(
                 name=f'*{arg.arg}' if arg_type == 'vararg' else f'**{arg.arg}',
-                type_=getattr(arg.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER),
+                type_=self._extract_parameter_type(arg),
                 category=None,
                 default=NO_DEFAULT,
             )
@@ -112,6 +201,15 @@ class FunctionDocstringNode(DocstringNode):
         ]
 
     def _extract_positional_args(self) -> list[Parameter]:
+        """
+        Extract the function's positional arguments.
+
+        Returns
+        -------
+        list[Parameter]
+            A list of :class:`.Parameter` instances, representing the function's
+            positional arguments.
+        """
         if (default_count := len(positional_defaults := self.arguments.defaults)) < (
             positional_arguments_count := (
                 len(self.arguments.posonlyargs) + len(self.arguments.args)
@@ -124,7 +222,7 @@ class FunctionDocstringNode(DocstringNode):
         return [
             Parameter(
                 name=arg.arg,
-                type_=getattr(arg.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER),
+                type_=self._extract_parameter_type(arg),
                 category=category,
                 default=self._extract_default_values(default, False),
             )
@@ -140,10 +238,19 @@ class FunctionDocstringNode(DocstringNode):
         ]
 
     def _extract_keyword_args(self) -> list[Parameter]:
+        """
+        Extract the function's keyword arguments.
+
+        Returns
+        -------
+        list[Parameter]
+            A list of :class:`.Parameter` instances, representing the function's
+            keyword arguments.
+        """
         return [
             Parameter(
                 name=arg.arg,
-                type_=getattr(arg.annotation, 'id', PARAMETER_TYPE_PLACEHOLDER),
+                type_=self._extract_parameter_type(arg),
                 category='keyword-only',
                 default=self._extract_default_values(default, True),
             )
@@ -153,6 +260,15 @@ class FunctionDocstringNode(DocstringNode):
         ]
 
     def extract_arguments(self) -> tuple[Parameter, ...]:
+        """
+        Extract the function's arguments.
+
+        Returns
+        -------
+        tuple[Parameter, ...]
+            A tuple of :class:`.Parameter` instances, representing all of the
+            function's arguments.
+        """
         params = self._extract_positional_args()
 
         varargs, kwargs = self._extract_star_args()
@@ -174,6 +290,14 @@ class FunctionDocstringNode(DocstringNode):
         return params
 
     def _extract_return_annotation(self) -> str | None:
+        """
+        Extract the function's return annotation, if present.
+
+        Returns
+        -------
+        str | None
+            The return annotation as a string, if present, otherwise, ``None``.
+        """
         if self.returns is None:
             return self.returns
 
@@ -186,6 +310,16 @@ class FunctionDocstringNode(DocstringNode):
         return self.get_source_segment(self.returns)
 
     def extract_returns(self) -> str | None:
+        """
+        Extract the function's return type for use in the docstring.
+
+        Returns
+        -------
+        str | None
+            The return type as a string, if present. Otherwise, the function will
+            be checked for ``return`` calls, and, if present, a placeholder for the
+            type will be returned; if it isn't present, ``None``, will be returned.
+        """
         if self.return_annotation:
             return self.return_annotation
 
@@ -199,4 +333,12 @@ class FunctionDocstringNode(DocstringNode):
         return None
 
     def to_function(self) -> Function:
+        """
+        Convert node into a :class:`.Function` instance.
+
+        Returns
+        -------
+        Function
+            The :class:`.Function` instance.
+        """
         return Function(self.extract_arguments(), self.extract_returns())