docstringify 0.7.0__tar.gz → 1.1.0__tar.gz

{docstringify-0.7.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-0.7.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-0.7.0 → docstringify-1.1.0}/.pre-commit-config.yaml

@@ -11,27 +11,27 @@ 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.6.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.9
+    rev: v0.12.2
     hooks:
-      - id: ruff
+      - id: ruff-check
         args: [--fix, --exit-non-zero-on-fix, --show-fixes]
       - id: ruff-format
 
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.5.1
+    rev: v2.6.0
     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-0.7.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-0.7.0 → docstringify-1.1.0}/PKG-INFO

@@ -1,35 +1,15 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.7.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 :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.9
@@ -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.
@@ -103,11 +76,11 @@ You can use Docstringify in three modes:
 
 ### Pre-commit hook
 
-Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings:
+Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.7.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
 ```
@@ -116,17 +89,17 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.7.0
+  rev: 1.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, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
+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`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`):
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.7.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -136,13 +109,21 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.7.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
       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.*).
+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. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 1.1.0
+  hooks:
+    - id: docstringify
+      args: [--make-changes-inplace=numpydoc]
+```
 
 Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
 
@@ -216,7 +197,19 @@ 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()`.
+If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`:
+
+```pycon
+>>> from docstringify.converters import GoogleDocstringConverter
+>>> from docstringify.traversal import DocstringTransformer
+>>> transformer = DocstringTransformer(
+...     'test.py', converter=GoogleDocstringConverter, overwrite=True
+... )
+>>> transformer.process_file()
+test is missing a docstring
+test.say_hello is missing a docstring
+Docstring templates written to /.../test.py
+```
 
 ## Contributing
 

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

@@ -54,11 +54,11 @@ You can use Docstringify in three modes:
 
 ### Pre-commit hook
 
-Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings:
+Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.7.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
 ```
@@ -67,17 +67,17 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.7.0
+  rev: 1.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, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
+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`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`):
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.7.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -87,13 +87,21 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.7.0
+  rev: 1.1.0
   hooks:
     - id: docstringify
       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.*).
+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. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
+
+```yaml
+- repo: https://github.com/stefmolin/docstringify
+  rev: 1.1.0
+  hooks:
+    - id: docstringify
+      args: [--make-changes-inplace=numpydoc]
+```
 
 Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
 
@@ -167,7 +175,19 @@ 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()`.
+If you want to overwrite the file with the edits, pass `overwrite=True` to `DocstringTransformer()`:
+
+```pycon
+>>> from docstringify.converters import GoogleDocstringConverter
+>>> from docstringify.traversal import DocstringTransformer
+>>> transformer = DocstringTransformer(
+...     'test.py', converter=GoogleDocstringConverter, overwrite=True
+... )
+>>> transformer.process_file()
+test is missing a docstring
+test.say_hello is missing a docstring
+Docstring templates written to /.../test.py
+```
 
 ## Contributing
 

{docstringify-0.7.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,13 +15,14 @@ keywords = [
   "numpydoc-style docstring",
   "pre-commit",
 ]
-license = { file = "LICENSE" }
+license = "MIT"
+license-files = [ "LICENSE" ]
 authors = [
   { name = "Stefanie Molin", email = "docstringify@stefaniemolin.com" },
 ]
 requires-python = ">=3.9"
 classifiers = [
-  "Development Status :: 3 - Alpha",
+  "Development Status :: 4 - Beta",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3 :: Only",
   "Programming Language :: Python :: 3.9",
@@ -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-0.7.0 → docstringify-1.1.0}/src/docstringify/converters/base.py

@@ -184,7 +184,9 @@ class DocstringConverter(ABC):
             return self._returns_section_template.format(returns=return_text)
         return ''
 
-    def format_docstring(self, docstring: str | list[str], indent: int) -> str:
+    def format_docstring(
+        self, docstring: str | list[str], indent: int, quote: bool | None = None
+    ) -> str:
         """
         Format the docstring with the requested level of indentation and surrounding
         triple quotes, if requested.
@@ -195,23 +197,28 @@ class DocstringConverter(ABC):
             The docstring as a string or list of strings that form lines in the docstring.
         indent : int
             The number of spaces by which to indent the docstring.
+        quote : bool | None, default=None
+            Whether to surround the docstring in triple quotes, passing this overrides
+            the ``quote`` setting specified upon initialization.
 
         Returns
         -------
         str
             The docstring indented to ``indent`` spaces will be returned either as a
-            quoted docstring if the converter was initialized with ``quote=True``, or an
-            unquoted docstring otherwise.
+            quoted docstring if the converter was initialized with ``quote=True`` or
+            ``quote=True`` was passed when calling this method, or an unquoted
+            docstring otherwise.
         """
-        quote = '"""' if self._quote else ''
+        quote_char = '"""' if quote or self._quote else ''
         prefix = sep = ''
+
         if isinstance(docstring, str):
-            docstring = [quote, docstring, quote]
+            docstring = [quote_char, docstring, quote_char]
         elif isinstance(docstring, list):
             if len(docstring) > 1:
                 prefix = ' ' * indent if indent else ''
                 sep = '\n'
-            docstring = [quote, *docstring, f'{prefix}{quote}']
+            docstring = [quote_char, *docstring, quote_char or f'{prefix}']
         else:
             raise InvalidDocstringError(type(docstring).__name__)
 

docstringify-1.1.0/src/docstringify/exceptions.py

@@ -0,0 +1,25 @@
+"""Docstringify exceptions."""
+
+
+class EmptyDocstringError(ValueError):
+    """
+    Raised when trying to write the modified source code back to a file if a docstring
+    is somehow empty.
+    """
+
+    def __init__(self) -> None:
+        super().__init__('Docstring is empty')
+
+
+class InvalidDocstringError(TypeError):
+    """
+    Raised when trying to create a docstring with invalid input.
+
+    Parameters
+    ----------
+    docstring_class : str
+        The class of the docstring object. This is used for the error message.
+    """
+
+    def __init__(self, docstring_class: str) -> None:
+        super().__init__(f'Expected str or list[str] docstring, got {docstring_class}')

{docstringify-0.7.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