docstringify 1.0.0__tar.gz → 1.1.1__tar.gz

{docstringify-1.0.0 → docstringify-1.1.1}/.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.1}/.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.1}/.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.1/.python-version

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

{docstringify-1.0.0 → docstringify-1.1.1}/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.1}/PKG-INFO

@@ -1,33 +1,13 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 1.0.0
+Version: 1.1.1
 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.1}/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.1}/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.1"
 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.1/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.1/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.1.1/src/docstringify/nodes/base.py

@@ -0,0 +1,110 @@
+"""Base Docstringify traversal node."""
+
+from __future__ import annotations
+
+import ast
+from functools import partial
+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,
+        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
+        """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`)."""
+
+        self.original_docstring_location: tuple[int, int] | None = (
+            None
+            if self.docstring is None
+            else (self.ast_node.body[0].lineno, self.ast_node.body[0].end_lineno)
+        )
+        """Start and end line of the docstring in the original file, if there was one,
+        otherwise, ``None``. This is necessary for the rewriting algorithm to exclude
+        lines containing "empty" docstrings from the file. Empty docstrings are empty
+        strings or strings containing only whitespace characters."""
+
+    @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
+            else self.name
+        )