docstring-tailor 0.2.0__tar.gz → 0.2.1.dev0__tar.gz

{docstring_tailor-0.2.0 → docstring_tailor-0.2.1.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-tailor
-Version: 0.2.0
+Version: 0.2.1.dev0
 Summary: Automatic formatting of Python docstrings according to PEP 257
 Author-email: Auke Bruinsma <afbruinsma@gmail.com>
 License: MIT License
@@ -33,22 +33,41 @@ Description-Content-Type: text/markdown
 
 # Docstring Tailor 🪡
 
-Automatic formatting of Python docstrings according to PEP 257 and a predefined maximum number of chacacters per line.
+Automatic formatting of Python docstrings according to PEP 257 and a predefined maximum number of characters per line.
 
 [![PyPI Version](https://img.shields.io/pypi/v/docstring-tailor?color=lightblue)](https://pypi.org/project/docstring-tailor/)
-[![License](https://img.shields.io/pypi/l/docstring-tailor)](https://pypi.org/project/docstring-tailor/)
+[![License](https://img.shields.io/pypi/l/docstring-tailor?color=lightblue)](https://pypi.org/project/docstring-tailor/)
 [![Wheel](https://img.shields.io/pypi/wheel/docstring-tailor?color=lightblue)](https://pypi.org/project/docstring-tailor/)
+[![Downloads](https://img.shields.io/pypi/dm/docstring-tailor?color=lightblue)](https://pypi.org/project/docstring-tailor/)
+
 
 ## Table of Contents
-1. [Installation](#Installation)
-2. [Quick start](#quick_start)
-3. [API Overview](#api-overview)
+1. [Demo](#demo)
+2. [Installation](#Installation)
+3. [Quick start](#quick_start)
+4. [API Overview](#api-overview)
     - [Command](#command)
     - [Options](#options)
     - [Examples](#examples)
-4. [Example docstrings](#example-docstrings)
-5. [Release Notes](#release_notes)
-6. [Roadmap](#roadmap)
+5. [Example docstrings](#example-docstrings)
+6. [Release Notes](#release_notes)
+7. [Roadmap](#roadmap)
+
+## Demo
+
+<details>
+<summary><b>Show demo</b></summary>
+
+<br>
+
+- `docstring-tailor` formats docstrings to fit a given line length, while preserving its structure throughout — For exapmle blank lines, argument indentation, continuation line alignment, and code blocks in the Examples section all remain intact.
+- **Note**: The slider in the [Marimo notebook](https://marimo.io/) is not part of the package. It was created solely to illustrate how the output changes continuously as the line length varies.
+
+<br>
+
+![Demo](https://raw.githubusercontent.com/AukeB/docstring-tailor/main/assets/gif_images/docstring_slider.gif)
+
+</details>
 
 ## Installation
 
@@ -112,55 +131,56 @@ style = "google"
 ```bash
 uv run docstring_tailor [PATHS ...] [OPTIONS]
 ```
-
 `PATHS` may contain one or more files and/or directories.
-
 Examples:
-
 ```bash
 uv run docstring_tailor my_file.py
 uv run docstring_tailor src/
 uv run docstring_tailor src/ tests/test_file.py
 ```
-
 If no paths are provided, `docstring_tailor` will attempt to locate and format files inside the `src` directory.
 
----
-
 ### Options
 
 | <div style="width:140px">Option</div> | <div style="width:50px">Type</div> | <div style="width:80px">Default</div> | Description |
 |---|---|---|---|
-| `--line-length`  | `int`  | 100      | Maximum number of characters allowed per line after formatting.                                                                       |
-| `--style`        | `str`  | google   | Docstring style to enforce. Currently only the Google docstring style is supported.                                                   |
-| `--detect-lists` | `bool` | true     | Detect unordered and ordered/numbered lists anywhere in a docstring and preserve each list element on its own line during formatting. |
+| `--line-length`      | `int`  | 100    | Maximum number of characters allowed per line after formatting. |
+| `--style`            | `str`  | google | Docstring style to enforce. Currently only the Google docstring style is supported. |
+| `--detect-lists`     | `bool` | true   | Detect unordered and ordered/numbered lists anywhere in a docstring and preserve each list element on its own line during formatting. |
+| `--exclude`          | `str`  | —      | A glob pattern for paths to exclude. Can be passed multiple times. Single-path patterns (e.g. `tests`, `*.pyi`) match by name anywhere in the tree. Relative patterns (e.g. `src/generated/*.py`) match against the path relative to the project root. |
+| `--diff`             | flag   | —      | Print a unified diff of changes to stdout instead of modifying files. No files are written when this flag is set. |
+| `--version`, `-V`    | flag   | —      | Print the installed version and exit. |
+| `--help`             | flag   | —      | Show the help message and exit. |
 
 ### Examples
 
 `CLI`
-
 ```bash
 uv run docstring_tailor src/ --line-length 88
 uv run docstring_tailor my_file.py --style google
 uv run docstring_tailor --detect-lists
 uv run docstring_tailor --no-detect-lists
-```
+uv run docstring_tailor src/ --exclude tests --exclude "src/generated/*.py"
+uv run docstring_tailor src/ --diff
+uv run docstring_tailor --version
+uv run docstring_tailor --help
 
+```
 `pyproject.toml`
-
 ```toml
 [tool.docstring_tailor]
 line-length = 88
 style = "google"
 detect-lists = true
+exclude = ["tests", "src/generated/*.py"]
 ```
 
 `docstring_tailor.toml`
-
 ```toml
 line-length = 88
 style = "google"
 detect-lists = true
+exclude = ["tests", "src/generated/*.py"]
 ```
 
 ## Example docstrings
@@ -315,8 +335,7 @@ def example_generator(n):
 ```
 - Similar to `Returns`, `Yields` is also supported.
 
-```pythonUnordered and numbered lists
-
+```python
 """Demonstrates a Google-style module docstring containing a Note
 section.
 
@@ -378,24 +397,21 @@ Steps:
 
 - Personally, I like to use unordered and numbered lists sometimes in a docstring. Similar to what has been described before, **indentation** is used to detect new list elements. 
 
-
 ## Release Notes
 
 | <div style="width:70px">Version</div> | <div style="width:100px">Release date</div> | <div style="width:130px">Type</div> | Details |
 |---|---|---|---|
-| `0.1.0` | 2026-05-31 | Initial release | First public release of `docstring-tailor`. Includes <ul><li>Automatic docstring wrapping for module, class and function docstring, for both one line and multi line docstrings, with a configurable `line-length` parameter.</li><li>Paragraph-aware formatting, differentiating between 'Args', 'Examples' or normal text sections.</li> <li> Docstring support for the Google `style` (Numpy, Sphinx, Epydoc not yet supported). </li><li>TOML-based configuration support.</li><li> Test coverage: 52% </ul> |
+| `0.1.0` | 2026-05-31 | Initial release | First public release of `docstring-tailor`. Includes <ul><li>Automatic docstring wrapping for module, class and function docstrings, for both one line and multi line docstrings, with a configurable `line-length` parameter.</li><li>Paragraph-aware formatting, differentiating between 'Args', 'Examples' or normal text sections.</li> <li> Docstring support for the Google `style` (Numpy, Sphinx, Epydoc not yet supported). </li><li>TOML-based configuration support.</li><li> Test coverage: 52% </ul> |
 | `0.1.1` | 2026-05-31 | Documentation update | Updated the `README.md` file with the 'Installation' and 'Quick Start' section. |
 | `0.2.0` | 2026-06-07 | Feature update | <ul><li>Implemented the `detect-lists` parameter, adding support for unordered and ordered (numbered) lists in docstrings. When enabled, list structures are detected automatically and each list item is formatted onto its own line.</li><li>Introduced a declarative golden-file test framework for formatter validation. Test cases are now generated from parametrized templates using Cartesian-product expansion, significantly reducing boilerplate and improving scalability for configuration coverage.</li><li>Expanded this `README.md` with the 'API Overview', 'Release Notes', 'Example docstrings' and 'Roadmap' sections.</li><li>Test coverage: 75%</li></ul> |
+| `0.2.1` | 2026-06-10 | Feature update | <ul><li>Added the `-V`/`--version` command to the CLI.</li><li>Added the `--exclude` command to the CLI.</li><li>Added the `--diff` command to the CLI.</li><li>Added the 'Demo' part to to the `README.md`.</ul> |
 
 ## Roadmap
 
 ### Must have
 
 - Support for all major docstrings styles (Google, Numpy, Sphinx, Epydoc).
-- Add `diff` functionality that will show you the formatting changes before actually changing the file(s).
 - Make sure the package can be used as a pre-commit hook.
-- Add `exclude` parameters that allows the user to ignore specific files.
-- Add `v`/`version` parameter that shows the version of the package.
 
 ### Nice to have
 

{docstring_tailor-0.2.0 → docstring_tailor-0.2.1.dev0}/README.md

@@ -1,21 +1,40 @@
 # Docstring Tailor 🪡
 
-Automatic formatting of Python docstrings according to PEP 257 and a predefined maximum number of chacacters per line.
+Automatic formatting of Python docstrings according to PEP 257 and a predefined maximum number of characters per line.
 
 [![PyPI Version](https://img.shields.io/pypi/v/docstring-tailor?color=lightblue)](https://pypi.org/project/docstring-tailor/)
-[![License](https://img.shields.io/pypi/l/docstring-tailor)](https://pypi.org/project/docstring-tailor/)
+[![License](https://img.shields.io/pypi/l/docstring-tailor?color=lightblue)](https://pypi.org/project/docstring-tailor/)
 [![Wheel](https://img.shields.io/pypi/wheel/docstring-tailor?color=lightblue)](https://pypi.org/project/docstring-tailor/)
+[![Downloads](https://img.shields.io/pypi/dm/docstring-tailor?color=lightblue)](https://pypi.org/project/docstring-tailor/)
+
 
 ## Table of Contents
-1. [Installation](#Installation)
-2. [Quick start](#quick_start)
-3. [API Overview](#api-overview)
+1. [Demo](#demo)
+2. [Installation](#Installation)
+3. [Quick start](#quick_start)
+4. [API Overview](#api-overview)
     - [Command](#command)
     - [Options](#options)
     - [Examples](#examples)
-4. [Example docstrings](#example-docstrings)
-5. [Release Notes](#release_notes)
-6. [Roadmap](#roadmap)
+5. [Example docstrings](#example-docstrings)
+6. [Release Notes](#release_notes)
+7. [Roadmap](#roadmap)
+
+## Demo
+
+<details>
+<summary><b>Show demo</b></summary>
+
+<br>
+
+- `docstring-tailor` formats docstrings to fit a given line length, while preserving its structure throughout — For exapmle blank lines, argument indentation, continuation line alignment, and code blocks in the Examples section all remain intact.
+- **Note**: The slider in the [Marimo notebook](https://marimo.io/) is not part of the package. It was created solely to illustrate how the output changes continuously as the line length varies.
+
+<br>
+
+![Demo](https://raw.githubusercontent.com/AukeB/docstring-tailor/main/assets/gif_images/docstring_slider.gif)
+
+</details>
 
 ## Installation
 
@@ -79,55 +98,56 @@ style = "google"
 ```bash
 uv run docstring_tailor [PATHS ...] [OPTIONS]
 ```
-
 `PATHS` may contain one or more files and/or directories.
-
 Examples:
-
 ```bash
 uv run docstring_tailor my_file.py
 uv run docstring_tailor src/
 uv run docstring_tailor src/ tests/test_file.py
 ```
-
 If no paths are provided, `docstring_tailor` will attempt to locate and format files inside the `src` directory.
 
----
-
 ### Options
 
 | <div style="width:140px">Option</div> | <div style="width:50px">Type</div> | <div style="width:80px">Default</div> | Description |
 |---|---|---|---|
-| `--line-length`  | `int`  | 100      | Maximum number of characters allowed per line after formatting.                                                                       |
-| `--style`        | `str`  | google   | Docstring style to enforce. Currently only the Google docstring style is supported.                                                   |
-| `--detect-lists` | `bool` | true     | Detect unordered and ordered/numbered lists anywhere in a docstring and preserve each list element on its own line during formatting. |
+| `--line-length`      | `int`  | 100    | Maximum number of characters allowed per line after formatting. |
+| `--style`            | `str`  | google | Docstring style to enforce. Currently only the Google docstring style is supported. |
+| `--detect-lists`     | `bool` | true   | Detect unordered and ordered/numbered lists anywhere in a docstring and preserve each list element on its own line during formatting. |
+| `--exclude`          | `str`  | —      | A glob pattern for paths to exclude. Can be passed multiple times. Single-path patterns (e.g. `tests`, `*.pyi`) match by name anywhere in the tree. Relative patterns (e.g. `src/generated/*.py`) match against the path relative to the project root. |
+| `--diff`             | flag   | —      | Print a unified diff of changes to stdout instead of modifying files. No files are written when this flag is set. |
+| `--version`, `-V`    | flag   | —      | Print the installed version and exit. |
+| `--help`             | flag   | —      | Show the help message and exit. |
 
 ### Examples
 
 `CLI`
-
 ```bash
 uv run docstring_tailor src/ --line-length 88
 uv run docstring_tailor my_file.py --style google
 uv run docstring_tailor --detect-lists
 uv run docstring_tailor --no-detect-lists
-```
+uv run docstring_tailor src/ --exclude tests --exclude "src/generated/*.py"
+uv run docstring_tailor src/ --diff
+uv run docstring_tailor --version
+uv run docstring_tailor --help
 
+```
 `pyproject.toml`
-
 ```toml
 [tool.docstring_tailor]
 line-length = 88
 style = "google"
 detect-lists = true
+exclude = ["tests", "src/generated/*.py"]
 ```
 
 `docstring_tailor.toml`
-
 ```toml
 line-length = 88
 style = "google"
 detect-lists = true
+exclude = ["tests", "src/generated/*.py"]
 ```
 
 ## Example docstrings
@@ -282,8 +302,7 @@ def example_generator(n):
 ```
 - Similar to `Returns`, `Yields` is also supported.
 
-```pythonUnordered and numbered lists
-
+```python
 """Demonstrates a Google-style module docstring containing a Note
 section.
 
@@ -345,24 +364,21 @@ Steps:
 
 - Personally, I like to use unordered and numbered lists sometimes in a docstring. Similar to what has been described before, **indentation** is used to detect new list elements. 
 
-
 ## Release Notes
 
 | <div style="width:70px">Version</div> | <div style="width:100px">Release date</div> | <div style="width:130px">Type</div> | Details |
 |---|---|---|---|
-| `0.1.0` | 2026-05-31 | Initial release | First public release of `docstring-tailor`. Includes <ul><li>Automatic docstring wrapping for module, class and function docstring, for both one line and multi line docstrings, with a configurable `line-length` parameter.</li><li>Paragraph-aware formatting, differentiating between 'Args', 'Examples' or normal text sections.</li> <li> Docstring support for the Google `style` (Numpy, Sphinx, Epydoc not yet supported). </li><li>TOML-based configuration support.</li><li> Test coverage: 52% </ul> |
+| `0.1.0` | 2026-05-31 | Initial release | First public release of `docstring-tailor`. Includes <ul><li>Automatic docstring wrapping for module, class and function docstrings, for both one line and multi line docstrings, with a configurable `line-length` parameter.</li><li>Paragraph-aware formatting, differentiating between 'Args', 'Examples' or normal text sections.</li> <li> Docstring support for the Google `style` (Numpy, Sphinx, Epydoc not yet supported). </li><li>TOML-based configuration support.</li><li> Test coverage: 52% </ul> |
 | `0.1.1` | 2026-05-31 | Documentation update | Updated the `README.md` file with the 'Installation' and 'Quick Start' section. |
 | `0.2.0` | 2026-06-07 | Feature update | <ul><li>Implemented the `detect-lists` parameter, adding support for unordered and ordered (numbered) lists in docstrings. When enabled, list structures are detected automatically and each list item is formatted onto its own line.</li><li>Introduced a declarative golden-file test framework for formatter validation. Test cases are now generated from parametrized templates using Cartesian-product expansion, significantly reducing boilerplate and improving scalability for configuration coverage.</li><li>Expanded this `README.md` with the 'API Overview', 'Release Notes', 'Example docstrings' and 'Roadmap' sections.</li><li>Test coverage: 75%</li></ul> |
+| `0.2.1` | 2026-06-10 | Feature update | <ul><li>Added the `-V`/`--version` command to the CLI.</li><li>Added the `--exclude` command to the CLI.</li><li>Added the `--diff` command to the CLI.</li><li>Added the 'Demo' part to to the `README.md`.</ul> |
 
 ## Roadmap
 
 ### Must have
 
 - Support for all major docstrings styles (Google, Numpy, Sphinx, Epydoc).
-- Add `diff` functionality that will show you the formatting changes before actually changing the file(s).
 - Make sure the package can be used as a pre-commit hook.
-- Add `exclude` parameters that allows the user to ignore specific files.
-- Add `v`/`version` parameter that shows the version of the package.
 
 ### Nice to have
 

{docstring_tailor-0.2.0 → docstring_tailor-0.2.1.dev0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring-tailor"
-version = "0.2.0"
+version = "0.2.1.dev0"
 description = "Automatic formatting of Python docstrings according to PEP 257"
 authors = [{ name = "Auke Bruinsma", email = "afbruinsma@gmail.com" }]
 license = { file = "LICENSE" }

{docstring_tailor-0.2.0 → docstring_tailor-0.2.1.dev0}/src/docstring_tailor/constants.py

@@ -1,5 +1,6 @@
 """Module for storing project constants."""
 
+from collections import namedtuple
 from pathlib import Path
 
 # Repository relative file paths.
@@ -58,3 +59,6 @@ CODE_BLOCK_PREFIXES = (
     FENCED_CODE_BLOCK_BACKTICKS,
     FENCED_CODE_BLOCK_TILDES,
 )
+
+# Named tuples
+Section = namedtuple("Section", ["name", "body"])

{docstring_tailor-0.2.0 → docstring_tailor-0.2.1.dev0}/src/docstring_tailor/main.py

@@ -1,7 +1,7 @@
 """Main module"""
 
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Optional
 
 import libcst as cst
 import typer
@@ -18,6 +18,7 @@ from docstring_tailor.cli_config import (
 )
 from docstring_tailor.constants import ENCODING
 from docstring_tailor.docstring_visitor import DocstringVisitor
+from docstring_tailor.utils.utils_cli import show_diff, version_callback
 from docstring_tailor.utils.utils_file_system import (
     collect_python_files,
     load_config,
@@ -33,10 +34,6 @@ def main(
         list[Path] | None,
         typer.Argument(help="Files or directories to process. Defaults to 'src/'."),
     ] = None,
-    style: Annotated[
-        DocstringStyle | None,
-        typer.Option("--style", help="Docstring style to format to."),
-    ] = None,
     line_length: Annotated[
         int | None,
         typer.Option(
@@ -46,6 +43,10 @@ def main(
             max=LINE_LENGTH_MAX,
         ),
     ] = None,
+    style: Annotated[
+        DocstringStyle | None,
+        typer.Option("--style", help="Docstring style to format to."),
+    ] = None,
     detect_lists: Annotated[
         bool | None,
         typer.Option(
@@ -53,6 +54,35 @@ def main(
             help="Detect and preserve list formatting.",
         ),
     ] = None,
+    exclude: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--exclude",
+            help=(
+                "A glob pattern for paths to exclude. Can be passed multiple times. "
+                "Single-path patterns (e.g. 'tests', '*.pyi') match by name anywhere "
+                "in the tree. Relative patterns (e.g. 'src/generated/*.py') match "
+                "against the path relative to the project root."
+            ),
+        ),
+    ] = None,
+    diff: Annotated[
+        bool,
+        typer.Option(
+            "--diff",
+            help="Show a diff of changes without modifying any files.",
+        ),
+    ] = False,
+    version: Annotated[
+        Optional[bool],
+        typer.Option(
+            "-V",
+            "--version",
+            callback=version_callback,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = None,
 ) -> None:
     """Formats Python docstrings in the given files or directories to the specified style.
 
@@ -61,23 +91,28 @@ def main(
 
     Args:
         paths (list[Path] | None): Files or directories to process. Defaults to 'src/'.
-        style (DocstringStyle | None): The docstring style to format to.
         line_length (int | None): The maximum line length to wrap docstrings to.
+        style (DocstringStyle | None): The docstring style to format to.
+        detect_lists (bool | None): Whether to detect and preserve list formatting.
+        diff (bool): If True, print a unified diff to stdout instead of writing files.
+        exclude (list[str] | None): Glob patterns for paths to exclude.
+        version (bool | None): If passed, print the version and exit.
     """
     # Resolve configuration with priority: CLI argument > config file > built-in default.
     file_config = load_config()
     resolved_paths = paths or [Path(p) for p in DEFAULT_PATHS]
-    resolved_style = style or DocstringStyle(
-        file_config.get("style", DEFAULT_STYLE.value)
-    )
     resolved_line_length = line_length or file_config.get(
         "line-length", LINE_LENGTH_DEFAULT
     )
+    resolved_style = style or DocstringStyle(
+        file_config.get("style", DEFAULT_STYLE.value)
+    )
     resolved_detect_lists = (
         detect_lists
         if detect_lists is not None
         else file_config.get("detect-lists", DETECT_LISTS_DEFAULT)
     )
+    resolved_exclude = exclude or file_config.get("exclude", [])
 
     if resolved_style not in SUPPORTED_STYLES:
         typer.echo(
@@ -87,7 +122,10 @@ def main(
         raise typer.Exit(code=1)
 
     validate_paths(paths=resolved_paths)
-    python_files = collect_python_files(paths=resolved_paths)
+    python_files = collect_python_files(
+        paths=resolved_paths,
+        exclude_patterns=resolved_exclude,
+    )
 
     for file_path in python_files:
         input_data = file_path.read_text(encoding=ENCODING)
@@ -97,25 +135,14 @@ def main(
                 line_length=resolved_line_length, detect_lists=resolved_detect_lists
             )
         )
-        file_path.write_text(modified_tree.code, encoding=ENCODING)
 
+        modified_code = modified_tree.code
 
-if __name__ == "__main__":
-    app()
-
-
-"""TODO:
+        if diff:
+            show_diff(original=input_data, modified=modified_code, path=file_path)
+        else:
+            file_path.write_text(modified_code, encoding=ENCODING)
 
-- Fix issue with (un)ordered lists if list element span multiple lines.
 
-- Currently, this code has been written specifically for the 'Google' docstring format. Fine for
-now, but the end state goal is to have the functionality that the user can specify the style in the
-pyproject.toml and that everything formats correctly to that style. The reading from pyproject.toml
-is already there, the biggest effort is in reformatting docstring_section_formatter a bit to make it
-work for all styles.
-
-- Check all the parameters in the docstringformatter package to see which ones I also want.
-
-- Implement feature that you can display the diff in terminal, instead of immediately formatting and
-overwriting the .py files.
-"""
+if __name__ == "__main__":
+    app()

{docstring_tailor-0.2.0 → docstring_tailor-0.2.1.dev0}/src/docstring_tailor/multi_line_docstring_formatter.py

@@ -2,7 +2,6 @@
 
 import re
 import textwrap
-from collections import namedtuple
 
 from docstring_tailor.constants import (
     CODE_BLOCK_PREFIXES,
@@ -11,14 +10,10 @@ from docstring_tailor.constants import (
     GOOGLE_ITEM_SECTIONS,
     GOOGLE_PLAIN_SECTIONS,
     GOOGLE_SECTION_HEADERS,
+    Section,
 )
-from docstring_tailor.utils.utils_formatting import (
-    format_list,
-    format_paragraph,
-    is_list,
-)
-
-Section = namedtuple("Section", ["name", "body"])
+from docstring_tailor.utils.utils_formatting import format_list, format_paragraph
+from docstring_tailor.utils.utils_list_detection import is_list
 
 
 class MultiLineDocstringFormatter:

docstring_tailor-0.2.1.dev0/src/docstring_tailor/utils/utils_cli.py

@@ -0,0 +1,55 @@
+"""Utility module containing helper functions for the CLI."""
+
+import difflib
+from importlib import metadata
+from pathlib import Path
+
+import typer
+
+
+def version_callback(value: bool) -> None:
+    """Print the package version and exit.
+
+    Args:
+        value (bool): Whether the flag was passed.
+
+    Raises:
+        typer.Exit: Always raised after printing, to halt execution.
+    """
+    if value:
+        version = metadata.version("docstring-tailor")
+        typer.echo(version)
+        raise typer.Exit()
+
+
+def show_diff(original: str, modified: str, path: Path) -> None:
+    """Prints a unified diff between the original and modified source to stdout.
+
+    Skips output entirely if the two sources are identical. Each line of the diff is coloured:
+    additions in green, removals in red, and header lines in bold, falling back to plain output on
+    terminals that don't support ANSI codes.
+
+    Args:
+        original (str): The source text before formatting.
+        modified (str): The source text after formatting.
+        path (Path): The file path, used as the diff header label.
+    """
+    if original == modified:
+        return
+
+    diff_lines = difflib.unified_diff(
+        original.splitlines(keepends=True),
+        modified.splitlines(keepends=True),
+        fromfile=f"{path} (original)",
+        tofile=f"{path} (formatted)",
+    )
+
+    for line in diff_lines:
+        if line.startswith("+++") or line.startswith("---"):
+            typer.echo(typer.style(line, bold=True), nl=False)
+        elif line.startswith("+"):
+            typer.echo(typer.style(line, fg=typer.colors.GREEN), nl=False)
+        elif line.startswith("-"):
+            typer.echo(typer.style(line, fg=typer.colors.RED), nl=False)
+        else:
+            typer.echo(line, nl=False)

docstring_tailor-0.2.1.dev0/src/docstring_tailor/utils/utils_file_system.py

@@ -0,0 +1,117 @@
+"""Module containing various utility functions related to interacting with local file system."""
+
+from pathlib import Path
+
+import typer
+
+
+def load_config() -> dict:
+    """Loads configuration from docstring_tailor.toml or pyproject.toml.
+
+    Walks up from the current directory. docstring_tailor.toml takes priority over pyproject.toml if
+    both exist at the same level. Stops at the first file found containing docstring_tailor
+    configuration.
+
+    Returns:
+        config (dict): Configuration settings, or an empty dict if none found.
+    """
+    import tomllib
+
+    for directory in [Path.cwd(), *Path.cwd().parents]:
+        tailor_config = directory / "docstring_tailor.toml"
+        if tailor_config.exists():
+            with open(tailor_config, "rb") as file:
+                return tomllib.load(file)
+
+        pyproject = directory / "pyproject.toml"
+        if pyproject.exists():
+            with open(pyproject, "rb") as file:
+                data = tomllib.load(file)
+            tool_config = data.get("tool", {}).get("docstring_tailor", {})
+            if tool_config:
+                return tool_config
+
+    return {}
+
+
+def _is_excluded(path: Path, exclude_patterns: list[str], project_root: Path) -> bool:
+    """Checks whether a path matches any of the provided exclusion patterns.
+
+    Supports two pattern types, mirroring Ruff's exclude behaviour:
+    - Single-path patterns (e.g. '.mypy_cache', 'foo.py', 'foo_*.py') are matched against every
+      component of the path, so they exclude by name anywhere in the tree.
+    - Relative patterns containing a separator (e.g. 'directory/foo.py', 'directory/*.py') are
+      matched against the path relative to the project root, so they only exclude at that specific
+      location.
+
+    Args:
+        path (Path): The absolute path to test.
+        exclude_patterns (list[str]): Glob patterns provided via --exclude.
+        project_root (Path): The directory against which relative patterns are resolved (typically
+            cwd or the directory containing pyproject.toml).
+
+    Returns:
+        excluded (bool): True if the path matches at least one pattern.
+    """
+    for pattern in exclude_patterns:
+        is_relative_pattern = "/" in pattern or "\\" in pattern
+        if is_relative_pattern:
+            try:
+                relative_path = path.relative_to(project_root)
+                if relative_path.match(pattern):
+                    return True
+            except ValueError:
+                pass
+        else:
+            for part in path.parts:
+                if Path(part).match(pattern):
+                    return True
+
+    return False
+
+
+def collect_python_files(
+    paths: list[Path],
+    exclude_patterns: list[str] | None = None,
+) -> list[Path]:
+    """Collects all Python files from a list of file and/or directory paths.
+
+    Directories are searched recursively. Files are included directly. Any path matching one of the
+    provided exclusion patterns is silently skipped.
+
+    Args:
+        paths (list[Path]): A list of file and/or directory paths to search.
+        exclude_patterns (list[str] | None): Glob patterns for paths to exclude.
+
+    Returns:
+        python_files (list[Path]): A flat list of all collected .py file paths.
+    """
+    resolved_patterns = exclude_patterns or []
+    project_root = Path.cwd()
+    python_files: list[Path] = []
+
+    for path in paths:
+        if path.is_dir():
+            for candidate in path.rglob("*.py"):
+                if not _is_excluded(candidate, resolved_patterns, project_root):
+                    python_files.append(candidate)
+        else:
+            if not _is_excluded(path, resolved_patterns, project_root):
+                python_files.append(path)
+
+    return python_files
+
+
+def validate_paths(paths: list[Path]) -> None:
+    """Validates that all provided paths exist on the filesystem.
+
+    Args:
+        paths (list[Path]): A list of file and/or directory paths to validate.
+
+    Raises:
+        typer.Exit: If any path does not exist.
+    """
+    for path in paths:
+        if not path.exists():
+            typer.echo(f"Error: path '{path}' does not exist.")
+            raise typer.Exit(code=1)

{docstring_tailor-0.2.0 → docstring_tailor-0.2.1.dev0}/src/docstring_tailor/utils/utils_formatting.py

@@ -33,91 +33,6 @@ def format_paragraph(
     return formatted
 
 
-def _is_unordered_list(lines: list[str]) -> bool:
-    """Returns True if at least two consecutive list items starting with an unordered marker are
-    found, ignoring continuation lines from wrapped items.
-
-    Args:
-        lines (list[str]): The lines to check.
-
-    Returns:
-        result (bool): True if an unordered list is detected, False otherwise.
-    """
-    non_empty_lines = [line for line in lines if line.strip()]
-    if not non_empty_lines:
-        return False
-
-    base_indent = min(len(line) - len(line.lstrip()) for line in non_empty_lines)
-    pattern = re.compile(r"^\s*[-*+]\s+")
-    count = 0
-
-    for line in lines:
-        if not line.strip():
-            continue
-
-        if len(line) - len(line.lstrip()) == base_indent:
-            if pattern.match(line):
-                count += 1
-                if count >= 2:
-                    return True
-            else:
-                count = 0
-
-    return False
-
-
-def _is_ordered_list(lines: list[str]) -> bool:
-    """Returns True if at least two consecutive sequentially numbered list items are found, ignoring
-    continuation lines from wrapped items.
-
-    Args:
-        lines (list[str]): The lines to check.
-
-    Returns:
-        result (bool): True if an ordered list is detected, False otherwise.
-    """
-    non_empty_lines = [line for line in lines if line.strip()]
-    if not non_empty_lines:
-        return False
-
-    base_indent = min(len(line) - len(line.lstrip()) for line in non_empty_lines)
-    pattern = re.compile(r"^\s*(\d+)[.)]\s+")
-    expected = 1
-    count = 0
-
-    for line in lines:
-        if not line.strip():
-            continue
-
-        if len(line) - len(line.lstrip()) == base_indent:
-            match = pattern.match(line)
-            if match and int(match.group(1)) == expected:
-                count += 1
-                expected += 1
-                if count >= 2:
-                    return True
-            else:
-                expected = 1
-                count = 0
-
-    return False
-
-
-def is_list(text: str) -> bool:
-    """Returns True if the text block contains an unordered or ordered list.
-
-    Args:
-        text (str): The text block to check.
-
-    Returns:
-        result (bool): True if a list is detected, False otherwise.
-    """
-    lines = text.split("\n")
-    result = _is_unordered_list(lines=lines) or _is_ordered_list(lines=lines)
-
-    return result
-
-
 def format_list(text: str, wrap_width: int, line_separator: str) -> str:
     """Formats a list block, preserving each item on its own line.
 

docstring_tailor-0.2.1.dev0/src/docstring_tailor/utils/utils_list_detection.py

@@ -0,0 +1,88 @@
+"""Utility module with functions for list detection in docstrings."""
+
+import re
+
+
+def _is_unordered_list(lines: list[str]) -> bool:
+    """Returns True if at least two consecutive list items starting with an unordered marker are
+    found, ignoring continuation lines from wrapped items.
+
+    Args:
+        lines (list[str]): The lines to check.
+
+    Returns:
+        result (bool): True if an unordered list is detected, False otherwise.
+    """
+    non_empty_lines = [line for line in lines if line.strip()]
+    if not non_empty_lines:
+        return False
+
+    base_indent = min(len(line) - len(line.lstrip()) for line in non_empty_lines)
+    pattern = re.compile(r"^\s*[-*+]\s+")
+    count = 0
+
+    for line in lines:
+        if not line.strip():
+            continue
+
+        if len(line) - len(line.lstrip()) == base_indent:
+            if pattern.match(line):
+                count += 1
+                if count >= 2:
+                    return True
+            else:
+                count = 0
+
+    return False
+
+
+def _is_ordered_list(lines: list[str]) -> bool:
+    """Returns True if at least two consecutive sequentially numbered list items are found, ignoring
+    continuation lines from wrapped items.
+
+    Args:
+        lines (list[str]): The lines to check.
+
+    Returns:
+        result (bool): True if an ordered list is detected, False otherwise.
+    """
+    non_empty_lines = [line for line in lines if line.strip()]
+    if not non_empty_lines:
+        return False
+
+    base_indent = min(len(line) - len(line.lstrip()) for line in non_empty_lines)
+    pattern = re.compile(r"^\s*(\d+)[.)]\s+")
+    expected = 1
+    count = 0
+
+    for line in lines:
+        if not line.strip():
+            continue
+
+        if len(line) - len(line.lstrip()) == base_indent:
+            match = pattern.match(line)
+            if match and int(match.group(1)) == expected:
+                count += 1
+                expected += 1
+                if count >= 2:
+                    return True
+            else:
+                expected = 1
+                count = 0
+
+    return False
+
+
+def is_list(text: str) -> bool:
+    """Returns True if the text block contains an unordered or ordered list.
+
+    Args:
+        text (str): The text block to check.
+
+    Returns:
+        result (bool): True if a list is detected, False otherwise.
+    """
+    lines = text.split("\n")
+    result = _is_unordered_list(lines=lines) or _is_ordered_list(lines=lines)
+
+    return result

{docstring_tailor-0.2.0 → docstring_tailor-0.2.1.dev0}/tests/test_formatting.py

@@ -4,9 +4,9 @@ import libcst as cst
 import pytest
 
 from docstring_tailor.docstring_visitor import DocstringVisitor
+from docstring_tailor.utils.utils_testing import generate_case_ids, read_fixture
 from tests.cases.config_model import Case
 from tests.cases.formatting_cases import CASES
-from tests.utils_test import generate_case_ids, read_fixture
 
 
 @pytest.mark.parametrize("case", CASES, ids=generate_case_ids)

{docstring_tailor-0.2.0 → docstring_tailor-0.2.1.dev0}/uv.lock

@@ -119,7 +119,7 @@ toml = [
 
 [[package]]
 name = "docstring-tailor"
-version = "0.2.0"
+version = "0.2.1.dev0"
 source = { editable = "." }
 dependencies = [
     { name = "libcst" },

docstring_tailor-0.2.0/src/docstring_tailor/utils/utils_file_system.py

@@ -1,70 +0,0 @@
-"""Module containing various utility functions."""
-
-from pathlib import Path
-
-import typer
-
-
-def load_config() -> dict:
-    """Loads configuration from docstring_tailor.toml or pyproject.toml.
-
-    Walks up from the current directory. docstring_tailor.toml takes priority over pyproject.toml if
-    both exist at the same level. Stops at the first file found containing docstring_tailor
-    configuration.
-
-    Returns:
-        config (dict): Configuration settings, or an empty dict if none found.
-    """
-    import tomllib
-
-    for directory in [Path.cwd(), *Path.cwd().parents]:
-        tailor_config = directory / "docstring_tailor.toml"
-        if tailor_config.exists():
-            with open(tailor_config, "rb") as file:
-                return tomllib.load(file)
-
-        pyproject = directory / "pyproject.toml"
-        if pyproject.exists():
-            with open(pyproject, "rb") as file:
-                data = tomllib.load(file)
-            tool_config = data.get("tool", {}).get("docstring_tailor", {})
-            if tool_config:
-                return tool_config
-
-    return {}
-
-
-def collect_python_files(paths: list[Path]) -> list[Path]:
-    """Collects all Python files from a list of file and/or directory paths.
-
-    Directories are searched recursively. Files are included directly.
-
-    Args:
-        paths (list[Path]): A list of file and/or directory paths to search.
-
-    Returns:
-        python_files (list[Path]): A flat list of all collected .py file paths.
-    """
-    python_files: list[Path] = []
-    for path in paths:
-        if path.is_dir():
-            python_files.extend(path.rglob("*.py"))
-        else:
-            python_files.append(path)
-
-    return python_files
-
-
-def validate_paths(paths: list[Path]) -> None:
-    """Validates that all provided paths exist on the filesystem.
-
-    Args:
-        paths (list[Path]): A list of file and/or directory paths to validate.
-
-    Raises:
-        typer.Exit: If any path does not exist.
-    """
-    for path in paths:
-        if not path.exists():
-            typer.echo(f"Error: path '{path}' does not exist.")
-            raise typer.Exit(code=1)