Metadata-Version: 2.4
Name: docstring-tailor
Version: 0.2.1
Summary: Automatic formatting of Python docstrings according to PEP 257
Author-email: Auke Bruinsma <afbruinsma@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Auke Bruinsma
        
        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.
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.11
Requires-Dist: libcst>=1.8.6
Requires-Dist: typer>=0.26.4
Description-Content-Type: text/markdown

# Docstring Tailor 🪡

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?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&cache_bust=1)](https://pypi.org/project/docstring-tailor/)


## Table of Contents
1. [Demo](#demo)
2. [Installation](#Installation)
3. [Quick start](#quick_start)
4. [API Overview](#api-overview)
    - [Command](#command)
    - [Options](#options)
    - [Examples](#examples)
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 example 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>

<img src="https://github.com/user-attachments/assets/983ae257-472d-465e-9924-9d90bca10f0d" alt="Demo" />

If the image does not show, click [here](https://private-user-images.githubusercontent.com/32795119/606010424-983ae257-472d-465e-9924-9d90bca10f0d.gif?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODExNzU3ODQsIm5iZiI6MTc4MTE3NTQ4NCwicGF0aCI6Ii8zMjc5NTExOS82MDYwMTA0MjQtOTgzYWUyNTctNDcyZC00NjVlLTk5MjQtOWQ5MGJjYTEwZjBkLmdpZj9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA2MTElMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwNjExVDEwNTgwNFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPWMzYjdjYjYyZGJkNDgwZmM3NDFjNjlmMDdiOGI1ZWE0ODA1YTczOTg3NzYwZjkwY2VjYWYwNGJiZDc1NjhkZTMmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT1pbWFnZSUyRmdpZiJ9.CgQI0L986Mb1A6rcpn22KzG3mnJBTX5kVtlLGEoVN-w).

</details>

## Installation

Installation with [UV](https://docs.astral.sh/uv/) (recommended)
```bash
uv add --dev docstring-tailor
```

Or with pip:

```bash
pip install docstring-tailor
```

## Quick start

Run on a single file or directory:

```bash
uv run docstring_tailor my_file.py
uv run docstring_tailor my_folder
```
Multiple files and/or folders are also accepted. Without a file path or folder path, it will try to locate the `src` folder.

The default line length is 100. To customise it:

```bash
uv run docstring_tailor --line-length 88
```

Configure it permanently in `pyproject.toml` or in `docstring_tailor.toml`:

```toml
# pyproject.toml
[tool.docstring_tailor]
line-length = 88
```

```toml
# docstring_tailor.toml
line-length = 88
```

Define a docstring style, however the only style that is currently supported is [Google](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). This is also the default style. Explicit configuration:

```bash
uv run docstring_tailor --style google
```

or in `pyproject.toml`

```toml
[tool.docstring_tailor]
style = "google"
```

## API Overview

### Command

```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. |
| `--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

1. [Google](#google)
    - [Module docstring](#module-docstring)
    - [Class docstring](#class-docstring)
    - [Function docstring](#function-docstring)
    - [Codeblocks](#codeblocks)
    - [Other sections](#other-sections)
    - [Unordered and numbered lists](#unordered-and-numbered-lists)

### Google

#### Module docstring

```python
"""Demonstrates a minimal Google-style module docstring.

This module exists as a formatting example and illustrates the typical
structure of a Google-style docstring, including a concise summary
line followed by an additional descriptive paragraph.
"""
```
- Make sure to you use a **blank line** in between the summary line and the more elaborate description.

#### Class docstring

```python
class ExampleConfiguration:
    """Represents a configuration object used to demonstrate Google-
    style class docstrings.

    This class is provided as a formatting example and illustrates how
    attributes are documented consistently in the Google docstring
    style.

    Attributes:
        example_argument_1 (str): Stores the first configuration value
            provided at initialization.
        example_argument_2 (int): Stores the second configuration
            value provided at initialization.
    """
```
- The `Attributes` section is recognized by the formatter and triggers special indentation rules for attribute entries.
- If the description of an attribute extends to the next line, **it must be indented one additional level beyond the attribute name**. This indentation level is important: it is used by the formatter to distinguish between a new attribute entry and a continuation of the previous attribute’s description.

#### Function docstring

```python
def example_function(example_argument_1: str, example_argument_2: int) -> str:
    """Demonstrates a Google-style function docstring with multiple
    sections.

    This function exists purely as a formatting example and
    illustrates how Args, Returns, Examples, and Raises sections are
    structured in a Google-style docstring.

    Args:
        example_argument_1 (str): First example input value used to
            construct a formatted result string.
        example_argument_2 (int): Second example input value used to
            influence the transformation logic.

    Returns:
        str: A formatted string combining both input arguments into a
            single human-readable representation.

    Examples:
        Basic usage with typical inputs produces a simple combined
        string:

        >>> example_function("alpha", 3)
        'alpha-3'

        You can also write text in between two Python REPL sections,
        and this part will be formatted, while the two small code
        sections won't be formatted.

        >>> example_function(
        ...     "beta",
        ...     7,
        ... )
        'beta-7'

    Raises:
        ValueError: Raised when example_argument_2 is negative or
            zero, as only positive integers are considered valid in
            this demonstration.
    """
    if example_argument_2 <= 0:
        raise ValueError("example_argument_2 must be positive")

    return f"{example_argument_1}-{example_argument_2}"
```
- The `Args`, `Returns`, `Examples` and `Raises` section are all keywords recognized by the formatter.
- You can either use `Args` or `Arguments` for the argument section, and    `Example` or `Examples` for the example section.
- Similar to the `Attributes` section for the class docstring above, make sure to **introduce another level of indentation** for the description of a function argument, return variable or error description, if it extends to the next line.
- In the `Example` section, make sure to use `>>>` for the start of the Python REPL, and use `...` for continuation lines. In this way it is consistent with Pydoc.
- You can also use these keywords in module or class docstrings. For example, an `Args` section in a class docstring, or an `Example(s)` section in a module docstring.

#### Codeblocks

```python
"""Demonstrates a Google-style module docstring containing a code
block.

This module-level docstring is used as a formatting example and shows
how code blocks can be embedded inside docstrings using fenced
delimiters.

Example:
    ```
    def example_function(x, y):
        return x + y
    ```
"""
```

```python
"""Demonstrates a Google-style module docstring containing a code
block.

This module-level docstring is used as a formatting example and shows
how code blocks can be embedded inside docstrings using fenced
delimiters.

Example:
    ~~~
    def example_function(x, y):
        return x + y
    ~~~
"""
```
- Codeblocks should be under the `Example(s)` section.
- You can either use backticks ` ``` ` or tildes `~~~`, similar to how code sections work in markdown files.

#### Other sections

```python
def example_generator(n):
    """Generators have a ``Yields`` section instead of a ``Returns``
    section.

    Args:
        n (int): The upper limit of the range to generate, from 0 to
            `n` - 1.

    Yields:
        int: The next number in the range of 0 to `n` - 1.
    """
```
- Similar to `Returns`, `Yields` is also supported.

```python
"""Demonstrates a Google-style module docstring containing a Note
section.

This module-level docstring is used as a formatting example and
illustrates how additional informational sections can be included
alongside the main description in a Google-style docstring.

Note:
    The formatting of this docstring is intentionally designed to test
    how note sections are detected and preserved during docstring
    transformation.
"""
```
- `Note` is a keyword that is also supported.
- You can use either `Note` or `Notes`.

#### Unordered and numbered lists

```python
"""Demonstrates that Google-style docstrings can include structured
lists.

This module-level docstring is used as a formatting example and shows
how unordered lists can be represented inside a docstring. Each list
item is recognized by the formatter and rendered on a separate line.

Items:
- Demonstrates that docstrings may contain structured unordered lists
  that are parsed and formatted consistently by the docstring
  formatter.
- Shows that each list item is treated as an independent element and
  is wrapped separately when exceeding the configured line length.
- Illustrates that long list items may span multiple lines while
  preserving indentation and list structure integrity across
  formatting operations.
"""
```

```python
"""Demonstrates that Google-style docstrings can include structured
lists.

This module-level docstring is used as a formatting example and shows
how numbered lists can be represented inside a docstring. Each list
item is recognized by the formatter and rendered on a separate line.

Steps:
1. Demonstrates that docstrings may contain structured numbered lists
   that are parsed and formatted consistently by the docstring
   formatter.
2. Shows that each list item is treated as a separate logical element
   and is wrapped independently when exceeding the configured line
   length.
3. Illustrates that long list items may span multiple lines while
   preserving indentation and list structure integrity across
   formatting operations.
"""
```

- 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 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-11 | 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).
- Make sure the package can be used as a pre-commit hook.

### Nice to have

- Add docstring linting functionality by converting the docstring into an AST (Abstract Syntax Tree).
- Add docstring conversion functionality that allows you to change your docstring style. For example, conversion from the 'Google' docstring style to 'Numpy'. Passing the linting phase successfully would be a requirement for conversion.

### Maybe later

- Parameter that allows the user to format module, class and function docstrings independently.
