docstring-tailor 0.1.0__py3-none-any.whl

docstring_tailor/__init__.py

@@ -0,0 +1 @@
+""""""

docstring_tailor/cli_config.py

@@ -0,0 +1,25 @@
+"""CLI configuration constants and allowed values for docstring_tailor."""
+
+from enum import Enum
+
+# Initial argument that specifies the file(s) and/or folder(s)
+DEFAULT_PATHS = [("src")]
+
+
+# Argument: '--style'
+class DocstringStyle(str, Enum):
+    """Supported docstring styles."""
+
+    google = "google"
+    numpy = "numpy"
+    sphinx = "sphinx"
+    epydoc = "epydoc"
+
+
+SUPPORTED_STYLES = {DocstringStyle.google}
+DEFAULT_STYLE = DocstringStyle.google
+
+# Argument: '--line-length'
+LINE_LENGTH_MIN = 30
+LINE_LENGTH_MAX = 300
+LINE_LENGTH_DEFAULT = 100

docstring_tailor/constants.py

@@ -0,0 +1,50 @@
+"""Module for storing project constants."""
+
+# Encoding for reading .py files.
+ENCODING: str = "utf-8"
+
+# Docstring delimiters.
+DOCSTRING_DELIMITER: str = '"""'
+DOCSTRING_DELIMITER_LENGTH: int = len(DOCSTRING_DELIMITER)
+
+# Google-style docstring section keywords.
+GOOGLE_PLAIN_SECTIONS = frozenset(
+    {"Note", "Notes", "References", "See Also", "Todo", "Warning", "Warnings"}
+)
+GOOGLE_ITEM_SECTIONS = frozenset(
+    {"Args", "Arguments", "Attributes", "Raises", "Returns", "Yields"}
+)
+GOOGLE_CODE_SECTIONS = frozenset({"Example", "Examples"})
+GOOGLE_SECTION_HEADERS = (
+    GOOGLE_PLAIN_SECTIONS | GOOGLE_ITEM_SECTIONS | GOOGLE_CODE_SECTIONS
+)
+
+# NumPy-style docstring section keywords.
+NUMPY_ITEM_SECTIONS = frozenset(
+    {
+        "Attributes",
+        "Methods",
+        "Other Parameters",
+        "Parameters",
+        "Raises",
+        "Receives",
+        "Returns",
+        "Yields",
+    }
+)
+NUMPY_PLAIN_SECTIONS = frozenset({"Examples", "Notes", "References", "See Also"})
+NUMPY_SECTION_HEADERS = NUMPY_ITEM_SECTIONS | NUMPY_PLAIN_SECTIONS
+
+# Sphinx/reST-style docstring directive markers.
+# Directive-based rather than section-based — no section headers in the Google/NumPy sense.
+SPHINX_ITEM_DIRECTIVES = frozenset({":param", ":raises", ":returns", ":rtype", ":type"})
+SPHINX_PLAIN_DIRECTIVES = frozenset(
+    {".. example::", ".. note::", ".. seealso::", ".. warning::"}
+)
+SPHINX_DIRECTIVES = SPHINX_ITEM_DIRECTIVES | SPHINX_PLAIN_DIRECTIVES
+
+# Epydoc-style docstring tag markers.
+# Tag-based rather than section-based — no section headers in the Google/NumPy sense.
+EPYDOC_ITEM_TAGS = frozenset({"@param", "@raise", "@return", "@rtype", "@type"})
+EPYDOC_PLAIN_TAGS = frozenset({"@note", "@warning"})
+EPYDOC_TAGS = EPYDOC_ITEM_TAGS | EPYDOC_PLAIN_TAGS

docstring_tailor/docstring_visitor.py

@@ -0,0 +1,269 @@
+"""Module providing functionality to format Python docstrings"""
+
+import re
+
+import libcst as cst
+
+from docstring_tailor.constants import (
+    DOCSTRING_DELIMITER,
+    DOCSTRING_DELIMITER_LENGTH,
+)
+from docstring_tailor.multi_line_docstring_formatter import MultiLineDocstringFormatter
+
+
+class DocstringVisitor(cst.CSTTransformer):
+    """A transformer for traversing and formatting docstrings.
+
+    Subclasses libcst's CSTTransformer, which implements the visitor pattern over a Concrete Syntax
+    Tree (CST). When tree.visit(DocstringVisitor()) is called, libcst traverses every node in the
+    tree and automatically dispatches to the corresponding visit_* or leave_* method on this class
+    if one exists. Method names are derived directly from the CST node class names — for example,
+    visit_IndentedBlock is called for every cst.IndentedBlock node encountered. visit_* methods are
+    called on entry into a node (pre-order) and leave_* methods are called on exit (post-order).
+    leave_* methods receive both the original and updated node, and their return value replaces the
+    node in the reconstructed tree.
+
+    The visit_* methods in this class (visit_Module, visit_IndentedBlock) are used exclusively to
+    track indentation state as the tree is traversed, not to modify it. The leave_IndentedBlock is
+    also to track indentation. Modifications to the tree happen only in in the
+    leave_SimpleStatementLine method.
+
+    Workflow: The entry point for all transformations is leave_SimpleStatementLine, called for every
+    simple statement encountered. It delegates to _is_docstring to determine whether the statement
+    is a docstring. If not, the node is returned unchanged via the super() call. If it is, the node
+    is passed to _format_docstring, which extracts the raw string content and passes it to
+    _build_docstring. From there, two paths are possible: if the content fits on one line and
+    contains no deliberate paragraph breaks, _build_one_line_docstring is called; otherwise
+    _build_multi_line_docstring is called, which delegates to the MultiLineDocstringFormatter class
+    for the more complex multi-line formatting logic.
+
+    Attributes:
+        _line_length (int): Maximum characters per line including indentation and triple double
+            quotes.
+        _current_indent (str): The accumulated indentation string at the current nesting level,
+            updated as the tree is traversed.
+        _indent_unit (str): The indentation unit string used in the source file, captured from the
+            module node on entry. Initialised to four spaces as a safety placeholder.
+    """
+
+    def __init__(self, line_length: int) -> None:
+        """Initialises the DocstringVisitor.
+
+        Sets up the indentation tracker used to correctly format multi-line docstrings at any
+        nesting level. The initial value of _indent_unit is a four-space placeholder for safety, as
+        it will always be overwritten by visit_Module before any docstring is processed.
+
+        Args:
+            line_length (int): Maximum characters per line including indentation and triple double
+                quotes.
+        """
+        self._line_length = line_length
+        self._current_indent = ""
+        self._indent_unit = "    "
+
+    def visit_Module(self, node: cst.Module) -> None:
+        """Captures the default indentation unit from the module on first entry.
+
+        Called automatically by libcst when entering the root Module node, before any other node is
+        visited. Overwrites the placeholder _indent_unit set in __init__ with the actual indentation
+        string used in the source file.
+
+        Args:
+            node (cst.Module): The root module node.
+        """
+        self._indent_unit = node.default_indent
+
+    def visit_IndentedBlock(self, node: cst.IndentedBlock) -> None:
+        """Tracks the current indentation level when entering an indented block.
+
+        Called automatically by libcst each time it enters a cst.IndentedBlock node, such as the
+        body of a function, class, or control flow statement. Accumulates the indentation depth by
+        appending one indent unit to _current_indent.
+
+        Args:
+            node (cst.IndentedBlock): The indented block node being visited.
+        """
+        self._current_indent += self._indent_unit
+
+    def leave_IndentedBlock(
+        self,
+        original_node: cst.IndentedBlock,
+        updated_node: cst.IndentedBlock,
+    ) -> cst.IndentedBlock:
+        """Restores the current indentation level when leaving an indented block.
+
+        Called automatically by libcst each time it exits a cst.IndentedBlock node. Counterpart to
+        visit_IndentedBlock — strips one indent unit from _current_indent to restore the indentation
+        level of the enclosing scope.
+
+        Args:
+            original_node (cst.IndentedBlock): The original indented block node.
+            updated_node (cst.IndentedBlock): The updated indented block node.
+
+        Returns:
+            updated_node (cst.IndentedBlock): The updated node, unchanged.
+        """
+        self._current_indent = self._current_indent[: -len(self._indent_unit)]
+
+        return updated_node
+
+    def _build_multi_line_docstring(self, content: str) -> str:
+        """Builds a raw multi-line docstring from the stripped content.
+
+        Multi-line docstrings are significantly more complex than one-line docstrings — Taking the
+        'Google' docstring format as example, they contain multiple sections of different types
+        (plain paragraphs, item sections such as Args and Returns, and code sections such as
+        Examples) each requiring different formatting logic. This complexity is delegated entirely
+        to MultiLineDocstringFormatter, which handles section detection and formatting
+        independently.
+
+        Args:
+            content (str): The stripped docstring content, excluding the triple quote delimiters.
+
+        Returns:
+            multi_line_docstring (str): The formatted multi-line docstring including the triple
+                quote delimiters.
+        """
+        multi_line_docstring_formatter = MultiLineDocstringFormatter(
+            line_length=self._line_length,
+            current_indent=self._current_indent,
+            indent_unit=self._indent_unit,
+        )
+
+        formatted_sections = multi_line_docstring_formatter.format(content=content)
+
+        multi_line_docstring = (
+            DOCSTRING_DELIMITER
+            + formatted_sections
+            + "\n"
+            + self._current_indent
+            + DOCSTRING_DELIMITER
+        )
+
+        return multi_line_docstring
+
+    def _build_one_line_docstring(self, content: str) -> str:
+        """Builds a raw one-line docstring from the normalized content.
+
+        Args:
+            content (str): The normalized stripped docstring content, excluding the triple quote
+                delimiters.
+
+        Returns:
+            one_line_docstring (str): The formatted one-line docstring including the triple quote
+                delimiters.
+        """
+        one_line_docstring = DOCSTRING_DELIMITER + content + DOCSTRING_DELIMITER
+
+        return one_line_docstring
+
+    def _build_docstring(self, content: str) -> str:
+        """Builds the formatted docstring from the stripped content.
+
+        Determines whether the content fits on one line and contains no deliberate paragraph breaks.
+        If both conditions are met, delegates to _build_one_line_docstring. Otherwise delegates to
+        _build_multi_line_docstring.
+
+        Args:
+            content (str): The stripped docstring content, excluding the triple quote delimiters.
+
+        Returns:
+            docstring (str): The formatted docstring including the triple quote delimiters.
+        """
+        is_deliberately_multiline = bool(re.search(r"\n\s*\n", content))
+        normalized_content = re.sub(r"\s+", " ", content.strip())
+        fits_on_one_line = (
+            len(self._current_indent)
+            + len(normalized_content)
+            + 2 * DOCSTRING_DELIMITER_LENGTH
+            <= self._line_length
+        )
+
+        if fits_on_one_line and not is_deliberately_multiline:
+            docstring = self._build_one_line_docstring(content=normalized_content)
+        else:
+            docstring = self._build_multi_line_docstring(content=content)
+
+        return docstring
+
+    def _format_docstring(
+        self, node: cst.SimpleStatementLine
+    ) -> cst.SimpleStatementLine:
+        """Extracts, transforms, and reattaches the formatted docstring on the given node.
+
+        Extracts the raw string value from the CST node, strips the triple quote delimiters, and
+        passes the content to _build_docstring. The resulting formatted docstring is then wrapped
+        back into the appropriate CST node types and reattached to the statement. One-line
+        docstrings have the closing triple quotes on the same line; multi-line docstrings have them
+        on a new line.
+
+        Args:
+            node (cst.SimpleStatementLine): A CST node containing a docstring.
+
+        Returns:
+            updated_node (cst.SimpleStatementLine): The updated node with the formatted docstring.
+        """
+        # Extract
+        raw_docstring = node.body[0].value.value  # type: ignore
+        raw_docstring_without_triple_quotes = raw_docstring[
+            DOCSTRING_DELIMITER_LENGTH:-DOCSTRING_DELIMITER_LENGTH
+        ].strip()
+
+        # Transform
+        updated_docstring = self._build_docstring(
+            content=raw_docstring_without_triple_quotes
+        )
+
+        # Update
+        updated_simple_string = cst.SimpleString(updated_docstring)
+        updated_expression = node.body[0].with_changes(value=updated_simple_string)
+        updated_node = node.with_changes(body=(updated_expression,))
+
+        return updated_node
+
+    def _is_docstring(self, node: cst.SimpleStatementLine) -> bool:
+        """Determines if a given node is a docstring.
+
+        Checks that the statement contains exactly one expression, that the expression is a simple
+        string, and that the string begins with the triple quote delimiter.
+
+        Args:
+            node (cst.SimpleStatementLine): A node in the CST representing a statement.
+
+        Returns:
+            is_docstring (bool): True if the node is a docstring, False otherwise.
+        """
+        is_docstring: bool = (
+            len(node.body) == 1
+            and isinstance(node.body[0], cst.Expr)
+            and isinstance(node.body[0].value, cst.SimpleString)
+            and node.body[0].value.value.startswith(DOCSTRING_DELIMITER)
+        )
+
+        return is_docstring
+
+    def leave_SimpleStatementLine(
+        self,
+        original_node: cst.SimpleStatementLine,
+        updated_node: cst.SimpleStatementLine,
+    ) -> (
+        cst.BaseStatement | cst.FlattenSentinel[cst.BaseStatement] | cst.RemovalSentinel
+    ):
+        """Processes a simple statement line during traversal and formats it if it is a docstring.
+
+        Called automatically by libcst for every simple statement in the file. Acts as the entry
+        point for all docstring transformations. If the statement is not a docstring, the node is
+        returned unchanged via the super() call. If it is, it is passed to _format_docstring for
+        formatting.
+
+        Args:
+            original_node (cst.SimpleStatementLine): The original CST node.
+            updated_node (cst.SimpleStatementLine): The updated CST node.
+
+        Returns:
+            node (cst.BaseStatement): The final statement after transformation.
+        """
+        if self._is_docstring(node=updated_node):
+            updated_node = self._format_docstring(node=updated_node)
+
+        return super().leave_SimpleStatementLine(original_node, updated_node)

docstring_tailor/main.py

@@ -0,0 +1,107 @@
+"""Main module"""
+
+from pathlib import Path
+from typing import Annotated
+
+import libcst as cst
+import typer
+
+from docstring_tailor.cli_config import (
+    DEFAULT_PATHS,
+    DEFAULT_STYLE,
+    LINE_LENGTH_DEFAULT,
+    LINE_LENGTH_MAX,
+    LINE_LENGTH_MIN,
+    SUPPORTED_STYLES,
+    DocstringStyle,
+)
+from docstring_tailor.constants import ENCODING
+from docstring_tailor.docstring_visitor import DocstringVisitor
+from docstring_tailor.utils import collect_python_files, load_config, validate_paths
+
+app = typer.Typer()
+
+
+@app.command()
+def main(
+    paths: Annotated[
+        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(
+            "--line-length",
+            help=f"Maximum line length. Must be between {LINE_LENGTH_MIN} and {LINE_LENGTH_MAX}.",
+            min=LINE_LENGTH_MIN,
+            max=LINE_LENGTH_MAX,
+        ),
+    ] = None,
+) -> None:
+    """Formats Python docstrings in the given files or directories to the specified style.
+
+    Processes all .py files found at the provided paths, reformatting their docstrings in place.
+    Directories are searched recursively.
+
+    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.
+    """
+    # 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
+    )
+
+    if resolved_style not in SUPPORTED_STYLES:
+        typer.echo(
+            f"Style '{resolved_style.value}' is not yet supported. "
+            f"Currently supported: {', '.join(s.value for s in SUPPORTED_STYLES)}."
+        )
+        raise typer.Exit(code=1)
+
+    validate_paths(paths=resolved_paths)
+    python_files = collect_python_files(paths=resolved_paths)
+
+    for file_path in python_files:
+        input_data = file_path.read_text(encoding=ENCODING)
+        input_tree = cst.parse_module(source=input_data)
+        modified_tree = input_tree.visit(
+            DocstringVisitor(line_length=resolved_line_length)
+        )
+        file_path.write_text(modified_tree.code, encoding=ENCODING)
+
+
+if __name__ == "__main__":
+    app()
+
+
+"""TODO:
+
+- 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.
+
+- Testing. Write more tests. Get to 100% code coverage. Redesign the structure of the 'tests/'
+folder. All tests will be roughly the same, they have an input .py file from the 'raw' folder, which
+will be formatted, and then it should be equal to the content of one of the files in the 'formatted'
+folder. This means we can define a mapping that states which files in the raw folder should be
+identical after formatting to a certain file in the formatted folder. In this way you may only need
+one test function that just iterates over this mapping.
+"""

docstring_tailor/multi_line_docstring_formatter.py

@@ -0,0 +1,474 @@
+"""Module for MultiLineDocstringFormatter."""
+
+import re
+import textwrap
+from collections import namedtuple
+
+from docstring_tailor.constants import (
+    DOCSTRING_DELIMITER_LENGTH,
+    GOOGLE_CODE_SECTIONS,
+    GOOGLE_ITEM_SECTIONS,
+    GOOGLE_PLAIN_SECTIONS,
+    GOOGLE_SECTION_HEADERS,
+)
+
+Section = namedtuple("Section", ["name", "body"])
+
+
+class MultiLineDocstringFormatter:
+    """Formats the content sections of a docstring into the Google Docstring format.
+
+    The formatting pipeline starts in format(), which delegates to _split_content() to divide the
+    docstring into a preamble and a list of named sections. The preamble — everything before the
+    first section header — is split on double newlines and each paragraph formatted independently.
+    Named sections are dispatched to a dedicated formatter based on their type: item sections (Args,
+    Returns, etc.), plain sections (Note, etc.), or code sections (Examples). Code sections are
+    preserved verbatim since they contain doctest-format code that must not be wrapped or modified.
+
+    Attributes:
+        _line_length (int): Maximum characters per line including indentation and triple double
+            quotes.
+        _current_indent (str): The accumulated indentation string at the current nesting level,
+            updated as the tree is traversed.
+        _indent_unit (str): The indentation unit string used in the source file, captured from the
+            module node on entry. Initialised to four spaces as a safety placeholder.
+        _indent_length (int): The length of the `_ident_unit`, which is the same as the number of
+            spaces used for a single indentation.
+        _paragraph_separator (str): Paragraphs are separated using two '\n' value and the current
+            indentation. Examples of paragraphs are the 'Args' section, or the 'Returns' section.
+        _line_separator (str): Lines are separated using a single '\n' value and the current
+            indentation. When formatting, this is used for moving something to the next line.
+    """
+
+    def __init__(self, line_length: int, current_indent: str, indent_unit: str) -> None:
+        """Initialises the MultiLineDocstringFormatter.
+
+        Args:
+            line_length (int): Maximum characters per line including indentation.
+            current_indent (str): The accumulated indentation string at the current nesting level.
+            indent_unit (str): The indentation unit string used in the source file.
+        """
+        self._line_length = line_length
+        self._current_indent = current_indent
+        self._indent_unit = indent_unit
+        self._indent_length = len(self._indent_unit)
+
+        self._paragraph_separator = "\n\n" + self._current_indent
+        self._line_separator = "\n" + self._current_indent
+
+    def _format_plain_paragraph(self, paragraph: str) -> str:
+        """Formats a plain text paragraph within an indented section body.
+
+        Used for plain sections such as Note and Warning where the body is indented one level beyond
+        the section header. All lines including continuations are at the same indentation level.
+
+        Args:
+            paragraph (str): A plain text paragraph.
+
+        Returns:
+            formatted_plain_paragraph (str): The wrapped paragraph string.
+        """
+        normalized = re.sub(r"\s+", " ", paragraph.strip())
+        wrap_width = self._line_length - len(self._current_indent) - self._indent_length
+        lines = textwrap.wrap(normalized, width=wrap_width)
+
+        line_separator_indented = self._line_separator + self._indent_unit
+        formatted_plain_paragraph = line_separator_indented.join(lines)
+
+        return formatted_plain_paragraph
+
+    def _format_plain_section(self, section_name: str, section_body: str) -> str:
+        """Formats a plain text section such as Note or Warning.
+
+        Args:
+            section_name (str): The section header name, e.g. 'Note'.
+            section_body (str): The section content, excluding the header line.
+
+        Returns:
+            formatted_plain_section (str): The formatted section string.
+        """
+        formatted_content = self._format_plain_paragraph(paragraph=section_body)
+        formatted_plain_section = (
+            section_name
+            + ":\n"
+            + self._current_indent
+            + self._indent_unit
+            + formatted_content
+        )
+
+        return formatted_plain_section
+
+    def _format_item(self, item_text: str) -> str:
+        """Formats a single labelled item, wrapping its description if it exceeds the line length.
+
+        Continuation lines are indented one additional level beyond the item's base indent by
+        passing a subsequent_indent to textwrap, which is then preserved when the lines are joined
+        with the item separator.
+
+        Args:
+            item_text (str): The full stripped item string, e.g. 'name (str): Description.'.
+
+        Returns:
+            formatted (str): The formatted item string with correct indentation.
+        """
+        wrap_width = self._line_length - len(self._current_indent) - self._indent_length
+        lines = textwrap.wrap(
+            item_text.strip(), width=wrap_width, subsequent_indent=self._indent_unit
+        )
+
+        line_separator = "\n" + self._current_indent + self._indent_unit
+        formatted = line_separator.join(lines)
+
+        return formatted
+
+    def _parse_items(self, section_content: str) -> list[str]:
+        """Groups lines from a section body into individual item strings.
+
+        Detects item boundaries by indentation level. A new item starts whenever a line returns to
+        the minimum indentation level found in the section. Continuation lines at a deeper
+        indentation are joined to the current item.
+
+        Args:
+            section_content (str): The section body, excluding the header line.
+
+        Returns:
+            items (list[str]): A list of stripped item strings, one per labelled item.
+        """
+        lines = [line for line in section_content.split("\n") if line.strip()]
+
+        if not lines:
+            return []
+
+        base_indent = min(len(line) - len(line.lstrip()) for line in lines)
+
+        items: list[str] = []
+        current_item_lines: list[str] = []
+        for line in lines:
+            indent = len(line) - len(line.lstrip())
+            if indent == base_indent and current_item_lines:
+                items.append(" ".join(l.strip() for l in current_item_lines))
+                current_item_lines = [line]
+            else:
+                current_item_lines.append(line)
+
+        if current_item_lines:
+            items.append(" ".join(l.strip() for l in current_item_lines))
+
+        return items
+
+    def _format_items(self, section_content: str) -> str:
+        """Formats the body of an item section by parsing and formatting each item.
+
+        Args:
+            section_content (str): The section body, excluding the header line.
+
+        Returns:
+            formatted (str): The formatted items joined with the correct indentation.
+        """
+        item_texts = self._parse_items(section_content=section_content)
+        formatted_items = [
+            self._format_item(item_text=item_text) for item_text in item_texts
+        ]
+
+        item_separator = self._line_separator + self._indent_unit
+        formatted_items = item_separator.join(formatted_items)
+
+        return formatted_items
+
+    def _format_item_section(self, section_name: str, section_body: str) -> str:
+        """Formats a named section whose body consists of labelled items.
+
+        Formats each item independently and reassembles the section with the header on the first
+        line.
+
+        Args:
+            section_name (str): The section header name, e.g. 'Args' or 'Returns'.
+            section_body (str): The section content, excluding the header line.
+
+        Returns:
+            formatted (str): The formatted section string.
+        """
+        formatted_items = self._format_items(section_content=section_body)
+        formatted_item_section = (
+            section_name
+            + ":\n"
+            + self._current_indent
+            + self._indent_unit
+            + formatted_items
+        )
+
+        return formatted_item_section
+
+    def _format_code_chunk(self, chunk: str) -> str:
+        """Formats a single verbatim code block by stripping original indentation and re-indenting.
+
+        Preserves the content exactly as written, only adjusting the leading indentation to match
+        the current nesting level. Blank lines within the block are preserved.
+
+        Args:
+            chunk (str): A single code block string, delimited by double newlines in the caller.
+
+        Returns:
+            formatted_code_chunk (str): The re-indented code block with no leading prefix on the
+                first line, since the prefix is added by the outer join in _format_code_section.
+        """
+        lines = chunk.split("\n")
+        non_empty_lines = [line for line in lines if line.strip()]
+
+        if not non_empty_lines:
+            return ""
+
+        base_indent = min(len(line) - len(line.lstrip()) for line in non_empty_lines)
+
+        formatted_lines: list[str] = []
+        for line in lines:
+            if line.strip():
+                formatted_lines.append(line[base_indent:])
+            else:
+                formatted_lines.append("")
+
+        while formatted_lines and not formatted_lines[0]:
+            formatted_lines.pop(0)
+        while formatted_lines and not formatted_lines[-1]:
+            formatted_lines.pop()
+
+        line_separator = self._line_separator + self._indent_unit
+        formatted_code_chunk = line_separator.join(formatted_lines)
+
+        return formatted_code_chunk
+
+    def _format_code_section(self, section_name: str, section_body: str) -> str:
+        """Formats a code section such as Examples, preserving code verbatim and wrapping plain
+        text.
+
+        Splits the section body on double newlines into chunks. A chunk is treated as a code block
+        if its first non-empty line starts with '>>>'; otherwise it is treated as plain text and
+        formatted with _format_plain_paragraph. This distinction cannot be made perfectly — program
+        output that follows a blank line is indistinguishable from plain text — but the convention
+        that plain text between code blocks does not start with '>>>' covers all practical cases.
+
+        Args:
+            section_name (str): The section header name, e.g. 'Examples'.
+            section_body (str): The section content, excluding the header line.
+
+        Returns:
+            formatted_code_section (str): The formatted section string with verbatim code blocks and
+                wrapped plain text.
+        """
+        chunks = re.split(r"\n\s*\n", section_body)
+        formatted_chunks: list[str] = []
+
+        for chunk in chunks:
+            if not chunk.strip():
+                continue
+
+            first_content_line = next(
+                (line.strip() for line in chunk.split("\n") if line.strip()), ""
+            )
+
+            if first_content_line.startswith(">>>"):
+                formatted_chunks.append(self._format_code_chunk(chunk=chunk))
+            else:
+                formatted_chunks.append(self._format_plain_paragraph(paragraph=chunk))
+
+        if not formatted_chunks:
+            return section_name + ":"
+
+        chunk_separator = self._paragraph_separator + self._indent_unit
+        content = chunk_separator.join(formatted_chunks)
+
+        formatted_code_section = (
+            section_name + ":\n" + self._current_indent + self._indent_unit + content
+        )
+
+        return formatted_code_section
+
+    def _format_section(self, section_name: str, section_body: str) -> str:
+        """Detects the section type and dispatches to the appropriate formatter.
+
+        Args:
+            section_name (str): The section header name, e.g. 'Args' or 'Examples'.
+            section_body (str): The section content, excluding the header line.
+
+        Returns:
+            (str): The formatted section string.
+        """
+        if section_name in GOOGLE_PLAIN_SECTIONS:
+            return self._format_plain_section(
+                section_name=section_name, section_body=section_body
+            )
+        elif section_name in GOOGLE_ITEM_SECTIONS:
+            return self._format_item_section(
+                section_name=section_name, section_body=section_body
+            )
+        elif section_name in GOOGLE_CODE_SECTIONS:
+            return self._format_code_section(
+                section_name=section_name, section_body=section_body
+            )
+        else:
+            raise ValueError(f"Unsupported section_name: {section_name}")
+
+    def _format_middle_paragraph(self, paragraph: str) -> str:
+        """Formats a plain text paragraph that appears between the opening paragraph and a section.
+
+        Unlike the opening paragraph, the first line here starts at the full current indentation
+        level rather than after the triple quotes, so the full line width is available.
+
+        Args:
+            paragraph (str): A plain text paragraph.
+
+        Returns:
+            formatted (str): The wrapped paragraph string.
+        """
+        normalized = re.sub(r"\s+", " ", paragraph.strip())
+        wrap_width = self._line_length - len(self._current_indent)
+        lines = textwrap.wrap(normalized, width=wrap_width)
+
+        formatted_paragraph = self._line_separator.join(lines)
+
+        return formatted_paragraph
+
+    def _format_opening_paragraph(self, paragraph: str) -> str:
+        """Formats the first paragraph of a docstring, which starts after the opening triple double
+        quotes.
+
+        Uses initial_indent to simulate the triple quotes consuming space on the first line,
+        ensuring it wraps correctly. The placeholder is stripped before returning since the actual
+        triple quotes are prepended by the caller.
+
+        Args:
+            paragraph (str): The first plain text paragraph.
+
+        Returns:
+            formatted_paragraph (str): The wrapped paragraph string.
+        """
+        normalized = re.sub(r"\s+", " ", paragraph.strip())
+        width = self._line_length - len(self._current_indent)
+        lines = textwrap.wrap(
+            normalized,
+            width=width,
+            initial_indent=" " * DOCSTRING_DELIMITER_LENGTH,
+            subsequent_indent="",
+        )
+
+        if lines:
+            lines[0] = lines[0][DOCSTRING_DELIMITER_LENGTH:]
+
+        formatted_paragraph = self._line_separator.join(lines)
+
+        return formatted_paragraph
+
+    def _format_preamble(self, preamble: str) -> str:
+        """Formats the preamble — the content before the first named section header.
+
+        Splits on double newlines to separate paragraphs. The first paragraph is formatted with
+        _format_opening_paragraph to account for the triple quotes consuming space on the first
+        line. Subsequent paragraphs are formatted with _format_middle_paragraph at full line width.
+
+        Args:
+            preamble (str): The preamble content string.
+
+        Returns:
+            formatted_preamble (str): The formatted preamble string.
+        """
+        paragraphs = re.split(r"\n\s*\n", preamble.strip())
+        formatted_paragraphs: list[str] = []
+
+        for i, paragraph in enumerate(paragraphs):
+            if not paragraph.strip():
+                continue
+            if i == 0:
+                formatted_paragraphs.append(
+                    self._format_opening_paragraph(paragraph=paragraph)
+                )
+            else:
+                formatted_paragraphs.append(
+                    self._format_middle_paragraph(paragraph=paragraph)
+                )
+
+        formatted_preamble = self._paragraph_separator.join(formatted_paragraphs)
+
+        return formatted_preamble
+
+    def _split_content(self, content: str) -> tuple[str, list[Section]]:
+        """Splits docstring content into a preamble and a list of named sections.
+
+        Scans the content line by line for section headers from GOOGLE_SECTION_HEADERS. Everything
+        before the first header is the preamble. Each header and the lines that follow it up to the
+        next header form one section. Section headers are matched with longer names first to avoid
+        partial matches (e.g. 'See Also' before 'Also').
+
+        Args:
+            content (str): The stripped docstring content, excluding the triple double quote
+                delimiters.
+
+        Returns:
+            result (tuple[str, list[tuple[str, str]]]): A tuple of the preamble string and a list of
+                (section_name, section_body) pairs.
+        """
+        lines = content.split("\n")
+
+        sorted_headers: list[str] = sorted(
+            GOOGLE_SECTION_HEADERS, key=lambda h: len(h), reverse=True
+        )
+
+        header_pattern = re.compile(
+            r"^\s*(" + "|".join(re.escape(h) for h in sorted_headers) + r"):\s*$"
+        )
+
+        header_positions: list[tuple[int, str]] = []
+
+        for i, line in enumerate(lines):
+            match = header_pattern.match(line)
+            if match:
+                header_positions.append((i, match.group(1)))
+
+        if not header_positions:
+            return content, []
+
+        preamble = "\n".join(lines[: header_positions[0][0]])
+        sections: list[Section] = []
+
+        for i, (line_number, section_name) in enumerate(header_positions):
+            end = (
+                header_positions[i + 1][0]
+                if i + 1 < len(header_positions)
+                else len(lines)
+            )
+            section_body = "\n".join(lines[line_number + 1 : end])
+            section = Section(name=section_name, body=section_body)
+            sections.append(section)
+
+        return preamble, sections
+
+    def format(self, content: str) -> str:
+        """Formats the full docstring content into the Google Docstring format.
+
+        Splits the content into a preamble and named sections by detecting section headers first, so
+        that double newlines inside sections such as Examples are not mistakenly treated as
+        paragraph breaks. Formats each part independently and rejoins with a blank line between
+        each.
+
+        Args:
+            content (str): The stripped docstring content, excluding the triple quote delimiters.
+
+        Returns:
+            formatted_sections (str): The fully formatted docstring content.
+        """
+        preamble, sections = self._split_content(content=content)
+
+        formatted_parts: list[str] = []
+
+        if preamble.strip():
+            formatted_parts.append(self._format_preamble(preamble=preamble))
+
+        for section in sections:
+            formatted_parts.append(
+                self._format_section(
+                    section_name=section.name, section_body=section.body
+                )
+            )
+
+        formatted_sections = self._paragraph_separator.join(formatted_parts)
+
+        return formatted_sections

docstring_tailor/utils.py

@@ -0,0 +1,70 @@
+"""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)

docstring_tailor-0.1.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: docstring-tailor
+Version: 0.1.0
+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
+Requires-Python: >=3.11
+Requires-Dist: libcst>=1.8.6
+Requires-Dist: logging>=0.4.9.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 chacacters per line.
+
+## Docstring conventions according to PEP 257
+
+See https://peps.python.org/pep-0257/ for the complete document.
+
+**What is a docstring?** A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the `__doc__` special attribute of that object.
+
+## Different types and forms of docstrings
+
+The PEP document makes distinctions between different types of docstrings. For some docstring properties, the convention depends on the kind of object it belongs to. For module docstrings, it can also further depend on the type of python file. Therefore, a distinction is made between these **types** of docstrings:
+
+**Four types of docstrings**:
+1. Module docstrings
+    - Module docstrings for scripts (stand-alone program)
+    - Module docstrings for `__init__.py` files
+    - Module docstrings for 'normal' modules.
+2. Class docstrings
+3. Method or function docstrings
+
+Besides the types, docstrings can occur in two different **forms**.
+
+**Two forms of docstrings**:
+1. One-line docstrings
+2. Multi-line docstrings
+
+### Conventions for one-line docstrings
+1. Triple quotes are used even though the string fits on one line. This makes it easy to later expand it.
+2. The closing quotes are on the same line as the opening quotes. This looks better for one-liners.
+3. There’s no blank line either before or after the docstring, except when the the type of docstring is a class docstring. Then there should be a blank line after the docstring.
+4. The docstring is a phrase ending in a period. It prescribes the function or method’s effect as a command (“Do this”, “Return that”), not as a description; e.g. don’t write “Returns the pathname …”.
+5. The one-line docstring should NOT be a “signature” reiterating the function/method parameters (which can be obtained by introspection).
+
+### Conventions for multi-line docstrings
+1. Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line.
+2. The summary line may be on the same line as the opening quotes or on the next line.
+3. The entire docstring is indented the same as the quotes at its first line.
+4. Insert a blank line after all docstrings (one-line or multi-line) that document a class.
+5. Blank lines should be removed from the beginning and end of the docstring.
+
+#### Module docstrings
+
+5. The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in the object’s docstring.) 
+6. The docstring of a script (a stand-alone program) should be usable as its “usage” message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a “-h” option, for “help”)
+7. The docstring for a package (i.e., the docstring of the package’s `__init__.py` module) should also list the modules and subpackages exported by the package.
+
+#### Function or method docstrings
+
+8. The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.
+
+#### Class docstrings
+
+9. The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its __init__ method. Individual methods should be documented by their own docstring.
+10. If a class subclasses another class and its behavior is mostly inherited from that class, its docstring should mention this and summarize the differences.
+
+## Formatting operations applied by this tool
+
+**How does this tool detect docstrings?**: All string literals that start with triple double quotes (""") are recognized as docstrings and will potentially be formatted.
+
+**One-line docstrings**
+- Regarding the 5 conventions mentioned above for one-line docstrings, only convention number 2 is enforced (The closing quotes are on the same line as the opening quotes).
+- It is the user's reponsibility to adhere to convention number 1, since the triple quotes are used by this tool to detect the docstring. The same goes for convention number 3, 4 and 5.
+
+- Besides the conventions mentioned above, the docstring is formatted according to a pre-defined maximum number of characters per line (**line length**). This means:
+    - If a docstring is spread out over multiple lines, but it could fit on one line, it will be converted to a one-line docstring.
+    - If a docstring exceeds the line length, it will be converted to a multi-line docstring.
+
+**Multi-line docstrings**
+- Regarding the conventions for multi-line docstrings mentioned above, number 2 is applied. This means if the summary line is on the next line, it will be enforced on the same line as the opening triple double quotes.
+- Convention number 5 is also enforced, blank lines at the start and end of the docstring are removed.
+- Most of the other conventions are about the content of the docstring, which are not checked by this tool.
+
+Next to that, the layout of the docstring is preserved. For now the focus is on the 'Google' type docstring format, which in its most basic form, looks like this.
+
+```
+def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
+    """Example function with PEP 484 type annotations.
+
+    Args:
+        param1: The first parameter.
+        param2: The second parameter.
+
+    Returns:
+        The return value. True for success, False otherwise.
+    """
+```
+
+Or it can look like this:
+
+```
+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.
+
+    Examples:
+        Examples should be written in doctest format, and should illustrate how
+        to use the function.
+
+        >>> print([i for i in example_generator(4)])
+        [0, 1, 2, 3]
+
+    """
+    for i in range(n):
+        yield i
+```
+
+Maintaining this structure, while enforcing a maximum characters per line, means the following rules have to be implented in the formatting logic.
+
+- If the user starts a new line, even though there is still space on the current line for the next word, it should be corrected and the word should be moved to the current line.
+- If the line is too long, the part that exceed the line limit should be moved to the next line.
+- If the user uses two '\n' values, it means this was a deliberate choice (for example, starting the 'Args' section) and this should be preserved.
+- Single '\n' characters in for example the 'Args' section should be preserved, as each parameter should start on a new line.
+- If the docstring contains an 'Example' or 'Examples' section, the indentation for the code part and the code itself (indicated with '>>>' and '...') should be untouched, as this code should be able to be interpreted.

docstring_tailor-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+docstring_tailor/__init__.py,sha256=IjHRV0k2DNwvFrEHebmsXiBvmITE8nQUnsR07h9tVkU,7
+docstring_tailor/cli_config.py,sha256=Y1ZtKqmj6jsOK4nOwed_KBHH_k_mHStEqiNwv7fRTlQ,551
+docstring_tailor/constants.py,sha256=jzWpfAr3-QRuBuy7zGfWAH8Sf-VbN0D7r8hUeebjlMY,1770
+docstring_tailor/docstring_visitor.py,sha256=DXSVx-NaJsgrj-NaqEPsFjXGgb5K84oxzBBK5yxRMZE,11796
+docstring_tailor/main.py,sha256=qOEtufWJ_62BKNEeWrDjd1JmHphxvAL6_Ase_6YfscY,3971
+docstring_tailor/multi_line_docstring_formatter.py,sha256=89OkyyQpc0g2Vzlr8DKnqzMT4fAZh00uxG2KHTW1068,19024
+docstring_tailor/utils.py,sha256=kCzUpzIuDtRFcc0_H58yC8_haoGvDsPGh4n7ZIVre5I,2136
+docstring_tailor-0.1.0.dist-info/METADATA,sha256=4YUGnXRNJRcSQj9ZWBQ6i-AgGWsIqfMmtN4hPBI11uc,9359
+docstring_tailor-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+docstring_tailor-0.1.0.dist-info/entry_points.txt,sha256=krQaPqsMrevpU_ZeNs5-a01fxWDRLPkBeF2VySB394M,63
+docstring_tailor-0.1.0.dist-info/licenses/LICENSE,sha256=o3AOsIM_IeJ8-bPxcB5DBbCA3EtsC5zo4HAnB4b-Kao,1070
+docstring_tailor-0.1.0.dist-info/RECORD,,

docstring_tailor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

docstring_tailor-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+docstring_tailor = docstring_tailor.main:app

docstring_tailor-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+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.