docstring-tailor 0.4.0__tar.gz → 0.4.1__tar.gz

{docstring_tailor-0.4.0 → docstring_tailor-0.4.1}/.gitignore

@@ -55,6 +55,4 @@ Desktop.ini
 *.swo
 
 # Project-specific
-bitmaps/.~lock*
-bitmaps/.~lock.*#
 **/readme.todo

docstring_tailor-0.4.1/.pre-commit-hooks.yaml

@@ -0,0 +1,8 @@
+# Hook definition consumed via `repo: https://github.com/AukeB/docstring-tailor`.
+# Consumers must supply the style through `args`, e.g. args: ["style", "google"].
+- id: docstring-tailor
+  name: docstring-tailor
+  description: Format Python docstrings to a configurable line length and style.
+  entry: docstring_tailor format
+  language: python
+  types: [python]

{docstring_tailor-0.4.0 → docstring_tailor-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: docstring-tailor
-Version: 0.4.0
+Version: 0.4.1
 Summary: Formats Python docstrings to PEP 257 style with configurable line length.
 Author-email: Auke Bruinsma <afbruinsma@gmail.com>
 License: MIT License
@@ -44,16 +44,17 @@ Formats Python docstrings to PEP 257 style with configurable line length.
 ## Table of Contents
 1. [Demo](#demo)
 2. [Installation](#Installation)
-3. [Quick start](#quick_start)
+3. [Quick start](#quick-start)
 4. [API Overview](#api-overview)
     - [Command](#command)
     - [Options](#options)
     - [Examples](#examples)
-5. [Example docstrings](#example-docstrings)
-6. [What Your Line Length Says About You!](#what-your-line-length-says-about-you)
-7. [Resources](#resources)
-8. [Release Notes](#release_notes)
-9. [Roadmap](#roadmap)
+5. [Pre-commit and prek hook](#pre-commit-and-prek-hook)
+6. [Example docstrings](#example-docstrings)
+7. [What Your Line Length Says About You!](#what-your-line-length-says-about-you)
+8. [Resources](#resources)
+9. [Release Notes](#release-notes)
+10. [Roadmap](#roadmap)
 
 ## Demo
 
@@ -135,6 +136,8 @@ To convert existing docstrings from one style to another, use the `convert` comm
 uv run docstring_tailor convert my_file.py --from-style google --to-style numpy
 ```
 
+`docstring-tailor` can also run as a [pre-commit](https://pre-commit.com/) / [prek](https://github.com/j178/prek) hook so docstrings stay formatted on every commit, see [Pre-commit and prek hook](#pre-commit-and-prek-hook).
+
 ## API Overview
 
 ### Commands
@@ -217,6 +220,56 @@ style = "google"
 exclude = ["tests", "src/generated/*.py"]
 ```
 
+## Pre-commit and prek hook
+
+`docstring-tailor` can run as a [pre-commit](https://pre-commit.com/) hook, and works unchanged with [prek](https://github.com/j178/prek), the drop-in reimplementation, so docstrings stay formatted automatically on every commit. When the hook reformats a file it rewrites it in place and stops the commit so you can review and re-stage the change, exactly like the Ruff or Black hooks.
+
+### Hosted hook
+
+Add the following to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/AukeB/docstring-tailor
+    rev: 0.4.1
+    hooks:
+      - id: docstring-tailor
+        args: ["--style", "google"]
+```
+
+- `--style` is required, use `google`, `numpy` or `sphinx`. Pass any other option (`--line-length`, `--exclude`) through `args`, or set them in a `[tool.docstring_tailor]` config block instead. `args` is a single flat list where every flag and every value is its own quoted element (e.g. `["--style", "google", "--line-length", "88"]`, with numbers quoted). Install the hook once with `pre-commit install` (or `prek install`).
+
+Prefer TOML? prek also reads a native `prek.toml`, a drop-in alternative to `.pre-commit-config.yaml` (upstream `pre-commit` ignores it). The same hook in `prek.toml`
+
+```toml
+[[repos]]
+repo = "https://github.com/AukeB/docstring-tailor"
+rev = "v0.4.1"
+hooks= [
+    { id = "docstring-tailor", args = ["--style", "google"] },
+]
+```
+
+`prek util yaml-to-toml` converts an existing YAML config for you.
+
+### Local hook
+
+If your project already installs `docstring-tailor` (for example as a `uv` dev dependency), you can run it as a `repo: local` hook. pre-commit then never clones a remote repo, which is handy in locked-down or offline environments:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: docstring-tailor
+        name: docstring-tailor
+        entry: uv run docstring_tailor format --style google
+        language: system
+        types: [python]
+        pass_filenames: true
+```
+
+For CI, run `docstring-tailor format --diff` instead: it never writes files and exits non-zero when any docstring would change, so it can gate a pipeline.
+
 ## Example docstrings
 
 1. [Module docstring](#module-docstring)
@@ -654,6 +707,7 @@ You don't wrap text because wrapping is a skill issue. You let photons travel un
 | `0.3.0` | 2026-07-20 | Feature update & bug fixes | <ul><li>Introduced a style-agnostic intermediate representation (IR) model and refactored parsing into an abstract base class hierarchy. Google and NumPy docstrings now parse into the same IR via `IndentationBasedParser` subclasses, enabling lossless conversion between styles. Structured list parsing is delegated to style-specific implementations to handle syntactic differences (Google's inline `name (type):` vs. NumPy's `name : type` on separate lines).</li><li>Refactored rendering to match the parser architecture: `DocstringRendererBase` (ABC) with style-specific subclasses that implement two hooks — section header formatting (Google's `Args:` vs. NumPy's `Parameters` + underline) and section body indentation rules (confirmed against numpy's own docstrings to keep bodies flush with headers, unlike Google). Keyword translation between styles happens automatically during conversion.</li><li>Code sections and Python REPL blocks now also can be created outside the 'Example(s)' section.</li><li>Fixed a bug when codeblock sections contain blank lines.</li><li>Fixed a bug when the docstring starts immediately with an (un)ordered list.</li><li>Removed `detect-lists` as CLI parameter, because the logic should always be applied if the docstring contains (un)ordered lists.</li><li>Changed behaviour for empty docstrings so that it consistent with Ruff.</li></ul> |
 | `0.3.1` | 2026-07-21 | Small fixes | <ul><li>The `style` parameter does not have a default argument anymore, instead it always has to be configured explicitly by the user.</li><li>Fixed a bug where one-line docstrings inside indented scopes (e.g. class or method bodies) were wrapped to multiple lines prematurely, due to indentation being counted twice when checking against the configured line length.</li> <li>Added an exception, consistent with Ruff, allowing a one-line docstring to exceed the configured line length by up to 3 characters when only the closing triple quotes would otherwise be pushed onto their own line. This prevents docstring_tailor and Ruff from repeatedly reformatting the same docstring back and forth when both are run as pre-commit hooks.</li></ul> |
 | `0.4.0` | 2026-07-24 | Feature update | <ul><li>Added support for the Sphinx/reST docstring `style`, covering both parsing and rendering. Sphinx docstrings now parse into the same style-agnostic intermediate representation (IR) as Google and NumPy, enabling lossless conversion in all directions between the three styles (`format --style sphinx` and `convert` to/from `sphinx`).</li><li>Extracted a shared `DocstringParserBase` holding the style-agnostic flat-content pipeline; `IndentationBasedParser` (Google/NumPy) and the new directive-based `SphinxDocstringParser` both build on it, reusing the existing pipeline rather than duplicating logic.</li><li>The Sphinx parser handles info-field lists (`:param:`/`:type:`, `:returns:`/`:rtype:`, `:raises:`), the inline parameter form (`:param str name:`), field/type pairing by name, tag aliases (`:return:`, `:raise:`, `:except:`, `:exception:`), and informational directives (`.. note::`, `.. warning::`, `.. seealso::`, `.. example::`).</li><li>The Sphinx renderer emits a contiguous info-field list with separate `:type:`/`:rtype:` lines, with hanging-indent wrapping of field bodies.</li><li>Modelled an absent parameter type as `None` in the IR (never fabricated), and updated the Google and NumPy renderers to degrade gracefully when a type is undocumented.</li><li>Reorganized the golden-file test fixtures into per-style folders (`google/`, `sphinx/`, `convert/`), with the fixture style folder derived automatically from each test case's configuration.</li></ul> |
+| `0.4.1` | 2026-09-12 | Robustness & bug fixes | <ul><li> Made structured-list parsing resilient to malformed entries: a missing `:` separator or a missing `(type)` annotation no longer crashes. The entry's text is preserved (with name and type left unset) and rendered as written, so formatting never fails on imperfect docstrings.</li><li> Modelled a `Raises` entry that lacks a `:` as an unnamed error (`error_type` set to `None`) in the IR, consistent with how unclassifiable parameter entries are handled, and guarded the Google, Numpy and Sphinx renderes accordingly.</li><li> The CLI now processes each file independently: files that cannot be read, decoded, or parsed as Python are reported with a specific error message and skipped, so a single malformed file no longer aborts the whole run.</li><li> Added a Ruff-style run summary (e.g. `2 files reformatted, 1 file left unchanged`) and stopped rewriting files whose content did not change.</li><li>Aligned exit codes with Ruff: `format` exits non-zero only on errors (write mode) or when changes are needed (`--diff`), and `convert` exits non-zero only on errors, enabling reliable use in pre-commit and CI.</li><li>Removed a leftover debug `print` from the CLI output.</li><li> Published a `pre-commit-config.yaml` hook definition so `docstring-tailor` can run as a pre-commit / prek hook via `repo:`, with hosted, local, and `prek.toml` setups documented in the README </li></ul> |
 
 ## Roadmap
 
@@ -681,7 +735,6 @@ The core Sphinx style (parameters, returns, raises, and the common admonitions)
 - Literal-body directives (`.. code-block::`, `.. math::`) — more involved, because their content must be preserved verbatim and never reflowed, and there is no clean equivalent in the current IR. Needs a dedicated literal-block IR node before it can be handled safely.
 
 ### Nice to have
-- Make sure the package can be used as a pre-commit hook.
 - LSP (Language Server Protocol) support, enabling real-time feedback on malformed
   docstrings directly in editors like VS Code, PyCharm and Neovim. Built on top of
   the validation layer and the existing parser, with `pygls` handling the protocol.

{docstring_tailor-0.4.0 → docstring_tailor-0.4.1}/README.md

@@ -11,16 +11,17 @@ Formats Python docstrings to PEP 257 style with configurable line length.
 ## Table of Contents
 1. [Demo](#demo)
 2. [Installation](#Installation)
-3. [Quick start](#quick_start)
+3. [Quick start](#quick-start)
 4. [API Overview](#api-overview)
     - [Command](#command)
     - [Options](#options)
     - [Examples](#examples)
-5. [Example docstrings](#example-docstrings)
-6. [What Your Line Length Says About You!](#what-your-line-length-says-about-you)
-7. [Resources](#resources)
-8. [Release Notes](#release_notes)
-9. [Roadmap](#roadmap)
+5. [Pre-commit and prek hook](#pre-commit-and-prek-hook)
+6. [Example docstrings](#example-docstrings)
+7. [What Your Line Length Says About You!](#what-your-line-length-says-about-you)
+8. [Resources](#resources)
+9. [Release Notes](#release-notes)
+10. [Roadmap](#roadmap)
 
 ## Demo
 
@@ -102,6 +103,8 @@ To convert existing docstrings from one style to another, use the `convert` comm
 uv run docstring_tailor convert my_file.py --from-style google --to-style numpy
 ```
 
+`docstring-tailor` can also run as a [pre-commit](https://pre-commit.com/) / [prek](https://github.com/j178/prek) hook so docstrings stay formatted on every commit, see [Pre-commit and prek hook](#pre-commit-and-prek-hook).
+
 ## API Overview
 
 ### Commands
@@ -184,6 +187,56 @@ style = "google"
 exclude = ["tests", "src/generated/*.py"]
 ```
 
+## Pre-commit and prek hook
+
+`docstring-tailor` can run as a [pre-commit](https://pre-commit.com/) hook, and works unchanged with [prek](https://github.com/j178/prek), the drop-in reimplementation, so docstrings stay formatted automatically on every commit. When the hook reformats a file it rewrites it in place and stops the commit so you can review and re-stage the change, exactly like the Ruff or Black hooks.
+
+### Hosted hook
+
+Add the following to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/AukeB/docstring-tailor
+    rev: 0.4.1
+    hooks:
+      - id: docstring-tailor
+        args: ["--style", "google"]
+```
+
+- `--style` is required, use `google`, `numpy` or `sphinx`. Pass any other option (`--line-length`, `--exclude`) through `args`, or set them in a `[tool.docstring_tailor]` config block instead. `args` is a single flat list where every flag and every value is its own quoted element (e.g. `["--style", "google", "--line-length", "88"]`, with numbers quoted). Install the hook once with `pre-commit install` (or `prek install`).
+
+Prefer TOML? prek also reads a native `prek.toml`, a drop-in alternative to `.pre-commit-config.yaml` (upstream `pre-commit` ignores it). The same hook in `prek.toml`
+
+```toml
+[[repos]]
+repo = "https://github.com/AukeB/docstring-tailor"
+rev = "v0.4.1"
+hooks= [
+    { id = "docstring-tailor", args = ["--style", "google"] },
+]
+```
+
+`prek util yaml-to-toml` converts an existing YAML config for you.
+
+### Local hook
+
+If your project already installs `docstring-tailor` (for example as a `uv` dev dependency), you can run it as a `repo: local` hook. pre-commit then never clones a remote repo, which is handy in locked-down or offline environments:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: docstring-tailor
+        name: docstring-tailor
+        entry: uv run docstring_tailor format --style google
+        language: system
+        types: [python]
+        pass_filenames: true
+```
+
+For CI, run `docstring-tailor format --diff` instead: it never writes files and exits non-zero when any docstring would change, so it can gate a pipeline.
+
 ## Example docstrings
 
 1. [Module docstring](#module-docstring)
@@ -621,6 +674,7 @@ You don't wrap text because wrapping is a skill issue. You let photons travel un
 | `0.3.0` | 2026-07-20 | Feature update & bug fixes | <ul><li>Introduced a style-agnostic intermediate representation (IR) model and refactored parsing into an abstract base class hierarchy. Google and NumPy docstrings now parse into the same IR via `IndentationBasedParser` subclasses, enabling lossless conversion between styles. Structured list parsing is delegated to style-specific implementations to handle syntactic differences (Google's inline `name (type):` vs. NumPy's `name : type` on separate lines).</li><li>Refactored rendering to match the parser architecture: `DocstringRendererBase` (ABC) with style-specific subclasses that implement two hooks — section header formatting (Google's `Args:` vs. NumPy's `Parameters` + underline) and section body indentation rules (confirmed against numpy's own docstrings to keep bodies flush with headers, unlike Google). Keyword translation between styles happens automatically during conversion.</li><li>Code sections and Python REPL blocks now also can be created outside the 'Example(s)' section.</li><li>Fixed a bug when codeblock sections contain blank lines.</li><li>Fixed a bug when the docstring starts immediately with an (un)ordered list.</li><li>Removed `detect-lists` as CLI parameter, because the logic should always be applied if the docstring contains (un)ordered lists.</li><li>Changed behaviour for empty docstrings so that it consistent with Ruff.</li></ul> |
 | `0.3.1` | 2026-07-21 | Small fixes | <ul><li>The `style` parameter does not have a default argument anymore, instead it always has to be configured explicitly by the user.</li><li>Fixed a bug where one-line docstrings inside indented scopes (e.g. class or method bodies) were wrapped to multiple lines prematurely, due to indentation being counted twice when checking against the configured line length.</li> <li>Added an exception, consistent with Ruff, allowing a one-line docstring to exceed the configured line length by up to 3 characters when only the closing triple quotes would otherwise be pushed onto their own line. This prevents docstring_tailor and Ruff from repeatedly reformatting the same docstring back and forth when both are run as pre-commit hooks.</li></ul> |
 | `0.4.0` | 2026-07-24 | Feature update | <ul><li>Added support for the Sphinx/reST docstring `style`, covering both parsing and rendering. Sphinx docstrings now parse into the same style-agnostic intermediate representation (IR) as Google and NumPy, enabling lossless conversion in all directions between the three styles (`format --style sphinx` and `convert` to/from `sphinx`).</li><li>Extracted a shared `DocstringParserBase` holding the style-agnostic flat-content pipeline; `IndentationBasedParser` (Google/NumPy) and the new directive-based `SphinxDocstringParser` both build on it, reusing the existing pipeline rather than duplicating logic.</li><li>The Sphinx parser handles info-field lists (`:param:`/`:type:`, `:returns:`/`:rtype:`, `:raises:`), the inline parameter form (`:param str name:`), field/type pairing by name, tag aliases (`:return:`, `:raise:`, `:except:`, `:exception:`), and informational directives (`.. note::`, `.. warning::`, `.. seealso::`, `.. example::`).</li><li>The Sphinx renderer emits a contiguous info-field list with separate `:type:`/`:rtype:` lines, with hanging-indent wrapping of field bodies.</li><li>Modelled an absent parameter type as `None` in the IR (never fabricated), and updated the Google and NumPy renderers to degrade gracefully when a type is undocumented.</li><li>Reorganized the golden-file test fixtures into per-style folders (`google/`, `sphinx/`, `convert/`), with the fixture style folder derived automatically from each test case's configuration.</li></ul> |
+| `0.4.1` | 2026-09-12 | Robustness & bug fixes | <ul><li> Made structured-list parsing resilient to malformed entries: a missing `:` separator or a missing `(type)` annotation no longer crashes. The entry's text is preserved (with name and type left unset) and rendered as written, so formatting never fails on imperfect docstrings.</li><li> Modelled a `Raises` entry that lacks a `:` as an unnamed error (`error_type` set to `None`) in the IR, consistent with how unclassifiable parameter entries are handled, and guarded the Google, Numpy and Sphinx renderes accordingly.</li><li> The CLI now processes each file independently: files that cannot be read, decoded, or parsed as Python are reported with a specific error message and skipped, so a single malformed file no longer aborts the whole run.</li><li> Added a Ruff-style run summary (e.g. `2 files reformatted, 1 file left unchanged`) and stopped rewriting files whose content did not change.</li><li>Aligned exit codes with Ruff: `format` exits non-zero only on errors (write mode) or when changes are needed (`--diff`), and `convert` exits non-zero only on errors, enabling reliable use in pre-commit and CI.</li><li>Removed a leftover debug `print` from the CLI output.</li><li> Published a `pre-commit-config.yaml` hook definition so `docstring-tailor` can run as a pre-commit / prek hook via `repo:`, with hosted, local, and `prek.toml` setups documented in the README </li></ul> |
 
 ## Roadmap
 
@@ -648,7 +702,6 @@ The core Sphinx style (parameters, returns, raises, and the common admonitions)
 - Literal-body directives (`.. code-block::`, `.. math::`) — more involved, because their content must be preserved verbatim and never reflowed, and there is no clean equivalent in the current IR. Needs a dedicated literal-block IR node before it can be handled safely.
 
 ### Nice to have
-- Make sure the package can be used as a pre-commit hook.
 - LSP (Language Server Protocol) support, enabling real-time feedback on malformed
   docstrings directly in editors like VS Code, PyCharm and Neovim. Built on top of
   the validation layer and the existing parser, with `pygls` handling the protocol.

{docstring_tailor-0.4.0 → docstring_tailor-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring-tailor"
-version = "0.4.0"
+version = "0.4.1"
 description = "Formats Python docstrings to PEP 257 style with configurable line length."
 authors = [{ name = "Auke Bruinsma", email = "afbruinsma@gmail.com" }]
 license = { file = "LICENSE" }

{docstring_tailor-0.4.0 → docstring_tailor-0.4.1}/src/docstring_tailor/constants.py

@@ -54,17 +54,6 @@ UNORDERED_LIST_MARKER: str = "- "
 ORDERED_LIST_SEPARATOR = ". "
 
 
-# ====================================================
-# Constants used for multiple docstings (but not all).
-# ====================================================
-
-
-# Related to StructuredList sections (Use in Google and Numpy format)
-STRUCTURED_LIST_DESCRIPTION_SEPARATOR: str = ":"
-PARAMETER_TYPE_ANNOTATION_OPEN: str = "("
-PARAMETER_TYPE_ANNOTATION_CLOSE: str = ")"
-
-
 # ============================================
 # Constants used for single docstring formats.
 # ============================================
@@ -93,6 +82,8 @@ GOOGLE_ALL_SECTION_KEYWORDS = (
     GOOGLE_NAMED_PARAGRAPH_SECTIONS | GOOGLE_STRUCTURED_LIST_SECTIONS
 )
 
+GOOGLE_STRUCTURED_LIST_DESCRIPTION_SEPARATOR: str = ":"
+
 # === NumPy ---
 
 NUMPY_ITEM_SECTIONS = frozenset(
@@ -101,6 +92,7 @@ NUMPY_ITEM_SECTIONS = frozenset(
 NUMPY_PLAIN_SECTIONS = frozenset({"Examples", "Notes", "References", "See Also"})
 NUMPY_SECTION_HEADERS = NUMPY_ITEM_SECTIONS | NUMPY_PLAIN_SECTIONS
 
+NUMPY_STRUCTURED_LIST_NAME_TYPE_SEPARATOR: str = ":"
 
 # Sphinx/reST-style
 SPHINX_ITEM_DIRECTIVES = frozenset({":param", ":raises", ":returns", ":rtype", ":type"})
@@ -115,7 +107,7 @@ SPHINX_DIRECTIVES = SPHINX_ITEM_DIRECTIVES | SPHINX_PLAIN_DIRECTIVES
 # and plural spellings) are accepted on input; the renderer emits one canonical
 # spelling per group. ':param' also accepts an inline type ':param <type>
 # <name>:', handled by the parser.
-SPHINX_PARAM_TAGS = frozenset({":parma", ":parameter", ":arg", ":argument"})
+SPHINX_PARAM_TAGS = frozenset({":param", ":parameter", ":arg", ":argument"})
 SPHINX_TYPE_TAGS = frozenset({":type"})
 SPHINX_RETURN_TAGS = frozenset({":return", ":returns"})
 SPHINX_RTYPE_TAGS = frozenset({":rtype"})

{docstring_tailor-0.4.0 → docstring_tailor-0.4.1}/src/docstring_tailor/ir_model.py

@@ -82,11 +82,14 @@ class StructuredListError:
     section.
 
     Attributes:
-        error_type (str): The exception type being raised.
+        error_type (str | None): The exception type being raised, or None when
+            the entry had no ':' separator and could not be split. The whole
+            entry is preserved in description instead, mirroring how an
+            unclassifiable parameter entry is handled.
         description (str): The description of when the error is raised.
     """
 
-    error_type: str
+    error_type: str | None
     description: str
 
 

{docstring_tailor-0.4.0 → docstring_tailor-0.4.1}/src/docstring_tailor/main.py

@@ -1,13 +1,7 @@
-"""Main module
-
-Todo
-
-- Fix that for return section the variable name is optional.
-- Fix that the program does not break if brackets can not be found for variable
-  types.
-"""
+"""Main module"""
 
 from collections.abc import Callable
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Annotated, Optional
 
@@ -135,35 +129,174 @@ def _resolve_common_options(
     return resolved_paths, resolved_line_length, resolved_exclude, file_config
 
 
+def _pluralize_files(file_count: int) -> str:
+    """Returns the correctly pluralized noun for a file count.
+
+    Args:
+        file_count (int): The number of files.
+
+    Returns:
+        noun (str): 'file' when count is 1, 'files' otherwise.
+    """
+    noun = "file" if file_count == 1 else "files"
+
+    return noun
+
+
+def _format_run_summary(counter_reformatted: int, counter_unchanged: int) -> str:
+    """Builds a Ruff-style one-line summary of a formatting run.
+
+    Mirrors 'ruff format': only the non-zero categories are named, except when
+    nothing was processed at all, in which case both are reported as zero.
+
+    Args:
+        counter_reformatted (int): Number of files whose content changed.
+        counter_unchanged (int): Number of files left unchanged.
+
+    Returns:
+        summary (str): The human-readable summary line.
+    """
+    reformatted_part = f"{counter_reformatted} {_pluralize_files(file_count=counter_reformatted)} reformatted"
+    unchanged_part = f"{counter_unchanged} {_pluralize_files(file_count=counter_unchanged)} left unchanged"
+
+    if counter_reformatted and counter_unchanged:
+        format_summary = f"{reformatted_part}, {unchanged_part}"
+    elif counter_reformatted:
+        format_summary = reformatted_part
+    elif counter_unchanged:
+        format_summary = unchanged_part
+    else:
+        format_summary = "0 files reformatted, 0 files left unchanged"
+
+    return format_summary
+
+
+@dataclass(frozen=True)
+class _FormatResult:
+    """Outcome counts of a formatting run for multiple python files.
+
+    Attributes:
+        count_reformatted (int): Number of files whose content changed.
+        count_unchanged (int): Number of files left untouched.
+        count_errored (int): Number of files that could not be read, decoded, or
+            parsed and were skipped.
+    """
+
+    count_reformatted: int
+    count_unchanged: int
+    count_errored: int
+
+
+def _process_single_file(
+    file_path: Path,
+    visitor_factory: Callable[[], DocstringVisitor],
+    diff: bool,
+) -> bool:
+    """Reads, transforms, and writes or diffs a single Python file.
+
+    Args:
+        file_path (Path): The file to process.
+        visitor_factory (Callable[[], DocstringVisitor]): Builds a fresh
+            DocstringVisitor this file.
+        diff (bool): If True, print a diff instead of writing files.
+
+    Returns:
+        is_changed (bool): True if formatting changed the file's content.
+    """
+    input_data = file_path.read_text(encoding=ENCODING)
+    input_tree = cst.parse_module(source=input_data)
+    modified_tree = input_tree.visit(visitor_factory())
+
+    modified_code = modified_tree.code
+    is_changed = modified_code != input_data
+
+    if diff:
+        show_diff(original=input_data, modified=modified_code, path=file_path)
+    elif is_changed:
+        file_path.write_text(modified_code, encoding=ENCODING)
+
+    return is_changed
+
+
 def _process_files(
     python_files: list[Path],
     visitor_factory: Callable[[], DocstringVisitor],
     diff: bool,
-) -> None:
+) -> _FormatResult:
     """Parses, transforms, and writes or diffs each collected Python file.
 
     A fresh DocstringVisitor is created per file via visitor_factory, since
     DocstringVisitor accumulates indentation state as it traverses a single
-    file's CST and cannot be safely reused across files.
+    file's CST and cannot be safely reused across files. Unchanged files are not
+    rewritten, so their on-disk timestamps are preserved. In write mode a Ruff-
+    style summary of the run is printed once all files are processed.
+
+    A file that cannot be read, decoded, or parsed as Python is reported to
+    stderr and skipped, so a single malformed file never aborts the whole run
+    and every other file is still processed.
 
     Args:
         python_files (list[Path]): The collected files to process.
         visitor_factory (Callable[[], DocstringVisitor]): Builds a fresh
             DocstringVisitor for each file.
         diff (bool): If True, print a diff instead of writing files.
+
+    Returns:
+        result (_FormatResult): Counts of reformatted, unchanged, and errored
+            files, so the caller can choose an exit code.
+
+    Raises:
+        OSError: If the file cannot be read or written.
+        UnicodeDecodeError: If the file is not valid text in the expected
+            encoding.
+        cst.ParserSyntaxError: If the file is not valid python.
     """
+    counter_reformatted: int = 0
+    counter_unchanged: int = 0
+    counter_errored: int = 0
+
     for file_path in python_files:
-        print(file_path)
-        input_data = file_path.read_text(encoding=ENCODING)
-        input_tree = cst.parse_module(source=input_data)
-        modified_tree = input_tree.visit(visitor_factory())
+        try:
+            is_changed: bool = _process_single_file(
+                file_path=file_path,
+                visitor_factory=visitor_factory,
+                diff=diff,
+            )
+        except OSError as error:
+            typer.echo(
+                f"error: could not read or write '{file_path}': {error}", err=True
+            )
+            counter_errored += 1
+            continue
+        except UnicodeDecodeError as error:
+            typer.echo(
+                f"error: '{file_path}' is not valid {ENCODING} text: {error}", err=True
+            )
+            counter_errored += 1
+            continue
+        except cst.ParserSyntaxError as error:
+            typer.echo(f"error: '{file_path}' is not valid Python: {error}", err=True)
+            counter_errored += 1
+            continue
+
+        if is_changed:
+            counter_reformatted += 1
+        else:
+            counter_unchanged += 1
 
-        modified_code = modified_tree.code
+    if not diff:
+        typer.echo(
+            _format_run_summary(
+                counter_reformatted=counter_reformatted,
+                counter_unchanged=counter_unchanged,
+            )
+        )
 
-        if diff:
-            show_diff(original=input_data, modified=modified_code, path=file_path)
-        else:
-            file_path.write_text(modified_code, encoding=ENCODING)
+    return _FormatResult(
+        count_reformatted=counter_reformatted,
+        count_unchanged=counter_unchanged,
+        count_errored=counter_errored,
+    )
 
 
 @app.command("format")
@@ -193,6 +326,11 @@ def format_command(
         exclude (list[str] | None): Glob patterns for paths to exclude.
         diff (bool): If True, print a unified diff to stdout instead of writing
             files.
+
+    Raises:
+        typer.Exit: With code 1 if any file could not be processed, or, in
+            --diff mode, if any file would be reformatted, so --diff can gate a
+            CI run while a normal write run still succeeds after fixing files.
     """
     resolved_paths, resolved_line_length, resolved_exclude, file_config = (
         _resolve_common_options(paths=paths, line_length=line_length, exclude=exclude)
@@ -218,7 +356,7 @@ def format_command(
         exclude_patterns=resolved_exclude,
     )
 
-    _process_files(
+    format_result = _process_files(
         python_files=python_files,
         visitor_factory=lambda: DocstringVisitor(
             line_length=resolved_line_length,
@@ -228,6 +366,11 @@ def format_command(
         diff=diff,
     )
 
+    # Write mode treats a reformat as success (files are fixed). Only --diff
+    # gates on changes.
+    if format_result.count_errored or (diff and format_result.count_reformatted):
+        raise typer.Exit(code=1)
+
 
 @app.command("convert")
 def convert_command(
@@ -265,8 +408,10 @@ def convert_command(
             files.
 
     Raises:
-        typer.Exit: If from_style and to_style are the same.
+        typer.Exit: With code 1 if from_style and to_style are the same.
+        typer.Exit: With code 1 if any file could not be processed.
     """
+
     if from_style == to_style:
         typer.echo(
             f"--from-style and --to-style were both '{from_style.value}'. "
@@ -288,7 +433,7 @@ def convert_command(
         exclude_patterns=resolved_exclude,
     )
 
-    _process_files(
+    format_result = _process_files(
         python_files=python_files,
         visitor_factory=lambda: DocstringVisitor(
             line_length=resolved_line_length,
@@ -298,6 +443,9 @@ def convert_command(
         diff=diff,
     )
 
+    if format_result.count_errored:
+        raise typer.Exit(code=1)
+
 
 if __name__ == "__main__":
     app()

{docstring_tailor-0.4.0 → docstring_tailor-0.4.1}/src/docstring_tailor/parser/indentation_based/numpy_docstring_parser.py

@@ -85,8 +85,9 @@ class NumpyDocstringParser(IndentationBasedParser):
 
         next_index = index + 1
 
-        if next_index >= len(lines):
-            return False
+        # Don't think this code is necessary
+        # if next_index >= len(lines):
+        #     return False
 
         result = bool(
             RE_PATTERN_NUMPY_SECTION_UNDERLINE.match(lines[next_index].strip())