format-docstring 0.1.0__py3-none-any.whl

format_docstring/__init__.py

@@ -0,0 +1,5 @@
+"""A Python formatter to wrap/adjust docstring lines."""
+
+import importlib.metadata
+
+__version__ = importlib.metadata.version('format-docstring')

format_docstring/base_fixer.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+
+class BaseFixer:
+    """Base class for fixing code formatting issues."""
+
+    def __init__(
+            self,
+            path: str,
+            exclude_pattern: str = r'\.git|\.tox|\.pytest_cache',
+    ) -> None:
+        """Initialize the fixer with a path and optional exclude pattern."""
+        self.path = path
+        self.exclude_pattern = exclude_pattern
+
+    def _get_files_to_process(
+            self, directory: Path, pattern: str
+    ) -> list[Path]:
+        """Get list of files to process, filtered by exclude pattern."""
+        all_files = sorted(directory.rglob(pattern))
+        return [
+            f
+            for f in all_files
+            if not should_exclude_file(f, self.exclude_pattern)
+        ]
+
+    def fix_one_directory_or_one_file(self) -> int:
+        """
+        Fix formatting in a single file or all Python files in a directory.
+        """
+        path_obj = Path(self.path)
+
+        if path_obj.is_file():
+            if should_exclude_file(path_obj, self.exclude_pattern):
+                return 0
+
+            return self.fix_one_file(path_obj.as_posix())
+
+        # Is a directory
+        filenames = self._get_files_to_process(path_obj, '*.py')
+        all_status = set()
+        for filename in filenames:
+            status = self.fix_one_file(filename.as_posix())
+            all_status.add(status)
+
+        return 0 if not all_status or all_status == {0} else 1
+
+    def fix_one_file(self, *varargs: Any, **kwargs: Any) -> int:
+        """Fix formatting in a single file."""
+        raise NotImplementedError('Please implement this method')
+
+
+def should_exclude_file(file_path: Path, exclude_pattern: str) -> bool:
+    """Return True if `file_path` matches the provided exclude regex.
+
+    If `exclude_pattern` is empty or invalid, no files are excluded.
+    """
+    if not exclude_pattern:
+        return False
+
+    try:
+        exclude_regex = re.compile(exclude_pattern)
+    except re.error:
+        return False
+
+    return bool(exclude_regex.search(file_path.as_posix()))

format_docstring/config.py

@@ -0,0 +1,211 @@
+"""Configuration file parsing for format-docstring."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+def find_config_file(paths: list[str] | tuple[str, ...] | None) -> Path | None:
+    """
+    Find pyproject.toml by walking up from the target path(s).
+
+    Parameters
+    ----------
+    paths : list[str] | tuple[str, ...] | None
+        The paths to search from. If None or empty, searches from cwd.
+
+    Returns
+    -------
+    Path | None
+        The path to pyproject.toml if found, None otherwise.
+    """
+    if not paths:
+        search_path = Path.cwd()
+    elif len(paths) == 1:
+        search_path = Path(paths[0])
+        if search_path.is_file():
+            search_path = search_path.parent
+    else:
+        # Find common parent folder
+        search_path = _find_common_parent(paths)
+
+    # Walk up the directory tree looking for pyproject.toml
+    current = search_path.resolve()
+    while True:
+        config_file = current / 'pyproject.toml'
+        if config_file.exists():
+            return config_file
+
+        parent = current.parent
+        if parent == current:  # Reached root
+            break
+
+        current = parent
+
+    return None
+
+
+def _find_common_parent(paths: list[str] | tuple[str, ...]) -> Path:
+    """
+    Find the common parent folder of the given paths.
+
+    Parameters
+    ----------
+    paths : list[str] | tuple[str, ...]
+        The paths to find the common parent for.
+
+    Returns
+    -------
+    Path
+        The common parent folder.
+    """
+    path_objs = [Path(p) for p in paths]
+
+    # For single path, return its parent if it looks like a file
+    if len(path_objs) == 1:
+        path = path_objs[0]
+        # If it has a file extension, treat as file
+        if path.suffix:
+            return path.parent
+        # If it exists and is a file, return parent
+        if path.exists() and path.is_file():
+            return path.parent
+        # Otherwise treat as directory
+        return path
+
+    # For multiple paths, find common parent by comparing parts
+    # Convert all file paths to their parent directories
+    dir_paths = []
+    for path in path_objs:
+        if path.suffix or (path.exists() and path.is_file()):
+            dir_paths.append(path.parent)
+        else:
+            dir_paths.append(path)
+
+    # Start with the first directory
+    common = dir_paths[0]
+
+    # Find common parent by comparing parts
+    for path in dir_paths[1:]:
+        # Find common parts
+        common_parts = []
+        for p1, p2 in zip(common.parts, path.parts, strict=False):
+            if p1 == p2:
+                common_parts.append(p1)
+            else:
+                break
+
+        if common_parts:
+            common = Path(*common_parts)
+        else:
+            # No common parent, use cwd
+            common = Path.cwd()
+            break
+
+    return common
+
+
+def load_config_from_file(config_file: Path) -> dict[str, Any]:
+    """
+    Load configuration from a pyproject.toml file.
+
+    Parameters
+    ----------
+    config_file : Path
+        Path to the configuration file.
+
+    Returns
+    -------
+    dict[str, Any]
+        Configuration dictionary with normalized keys (underscores).
+    """
+    if not config_file.exists():
+        return {}
+
+    try:
+        with open(config_file, 'rb') as fp:
+            raw_config = tomllib.load(fp)
+
+        # Extract [tool.format_docstring] section
+        format_docstring_section = raw_config.get('tool', {}).get(
+            'format_docstring', {}
+        )
+
+        # Normalize keys: replace hyphens with underscores
+        return {
+            k.replace('-', '_'): v for k, v in format_docstring_section.items()
+        }
+    except Exception:
+        # If there's any error reading/parsing the file, return empty config
+        return {}
+
+
+def update_click_context(
+        ctx: click.Context,
+        config: dict[str, Any],
+) -> None:
+    """
+    Update the Click context's default_map with configuration values.
+
+    Parameters
+    ----------
+    ctx : click.Context
+        The Click context to update.
+    config : dict[str, Any]
+        Configuration dictionary to merge into the context.
+    """
+    if ctx.default_map is None:
+        ctx.default_map = {}
+
+    ctx.default_map.update(config)
+
+
+def inject_config_from_file(
+        ctx: click.Context,
+        param: click.Parameter,  # noqa: ARG001 (required by Click callback signature)
+        value: str | None,
+) -> str | None:
+    """
+    Click callback to inject configuration from a config file.
+
+    This is used as a callback for the --config option.
+
+    Parameters
+    ----------
+    ctx : click.Context
+        The Click context.
+    param : click.Parameter
+        The Click parameter (unused, required by Click callback signature).
+    value : str | None
+        The path to the config file, or None to auto-discover.
+
+    Returns
+    -------
+    str | None
+        The config file path if found/specified, None otherwise.
+    """
+    config_file: Path | None
+
+    if value:
+        # User specified a config file
+        config_file = Path(value)
+    else:
+        # Auto-discover config file from paths
+        paths = ctx.params.get('paths')
+        config_file = find_config_file(paths)
+
+    if config_file and config_file.exists():
+        config = load_config_from_file(config_file)
+        update_click_context(ctx, config)
+        return str(config_file)
+
+    return None

format_docstring/docstring_rewriter.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+import ast
+
+from format_docstring.line_wrap_google import wrap_docstring_google
+from format_docstring.line_wrap_numpy import (
+    handle_single_line_docstring_that_is_a_bit_too_long,
+    wrap_docstring_numpy,
+)
+
+ModuleClassOrFunc = (
+    ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef
+)
+
+
+def fix_src(
+        source_code: str,
+        *,
+        line_length: int = 79,
+        docstring_style: str = 'numpy',
+) -> str:
+    """Return code with only docstrings updated to wrapped content.
+
+    Parameters
+    ----------
+    source_code : str
+        The full Python source code to process.
+    line_length : int, default=79
+        Target maximum line length for wrapping logic.
+
+    docstring_style : str, default='numpy'
+        The docstring style to target ('numpy' or 'google').
+
+    Returns
+    -------
+    str
+        The updated source code. Only docstring literals are changed; all
+        other formatting is preserved.
+
+    Notes
+    -----
+    This function avoids ``ast.unparse`` and instead replaces docstring
+    literal spans directly in the original text to preserve non-docstring
+    formatting and comments.
+
+    """
+    tree: ast.Module = ast.parse(source_code)
+    line_starts: list[int] = calc_line_starts(source_code)
+
+    replacements: list[tuple[int, int, str]] = []
+
+    # Module-level docstring
+    rep = build_replacement_docstring(
+        tree, source_code, line_starts, line_length, docstring_style
+    )
+    if rep is not None:
+        replacements.append(rep)
+
+    # Class/function-level docstrings
+    for node in ast.walk(tree):
+        if isinstance(
+            node, ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef
+        ):
+            rep = build_replacement_docstring(
+                node, source_code, line_starts, line_length, docstring_style
+            )
+            if rep is not None:
+                replacements.append(rep)
+
+    # Apply replacements from the end to avoid shifting offsets
+    if not replacements:
+        return source_code
+
+    replacements.sort(key=lambda x: x[0], reverse=True)
+    new_src = source_code
+    for start, end, text in replacements:
+        new_src = new_src[:start] + text + new_src[end:]
+
+    return new_src
+
+
+def calc_line_starts(source_code: str) -> list[int]:
+    """Return starting offsets for each line in the source string.
+
+    Parameters
+    ----------
+    source_code : str
+        The source text to analyze.
+
+    Returns
+    -------
+    list[int]
+        A list of absolute indices for the start of each line.
+
+    """
+    starts: list[int] = [0]
+    for i, ch in enumerate(source_code):
+        if ch == '\n':
+            starts.append(i + 1)
+
+    return starts
+
+
+def build_replacement_docstring(
+        node: ModuleClassOrFunc,
+        source_code: str,
+        line_starts: list[int],
+        line_length: int,
+        docstring_style: str = 'numpy',
+) -> tuple[int, int, str] | None:
+    """Compute a single docstring replacement for the given node.
+
+    Parameters
+    ----------
+    node : ModuleClassOrFunc
+        The AST node owning the docstring.
+    source_code : str
+        The original source text.
+    line_starts : list[int]
+        Line start offsets from :func:`_line_starts`.
+    line_length : int
+        Target maximum line length for wrapping logic.
+
+    docstring_style : str, default='numpy'
+        The docstring style to target ('numpy' or 'google').
+
+    Returns
+    -------
+    tuple[int, int, str] or None
+        A tuple ``(start, end, new_literal)`` indicating the replacement
+        range and text, or ``None`` if no change is needed.
+
+    """
+    docstring_obj: ast.Expr | None = find_docstring(node)
+    if docstring_obj is None:
+        return None
+
+    val: ast.Constant = docstring_obj.value  # type: ignore[assignment]
+    if not hasattr(val, 'lineno') or not hasattr(val, 'end_lineno'):
+        return None
+
+    start: int = calc_abs_pos(line_starts, val.lineno, val.col_offset)
+    end: int = calc_abs_pos(line_starts, val.end_lineno, val.end_col_offset)  # type: ignore[arg-type]  # noqa: LN002
+    original_literal = source_code[start:end]
+
+    doc: str | None = ast.get_docstring(node, clean=False)
+    if doc is None:
+        return None
+
+    # Use the docstring literal's column offset as the indentation level for
+    # formatting. This lets the wrapper ensure leading/trailing newlines plus
+    # matching spaces are present so closing quotes align with the parent's
+    # indentation.
+    leading_indent: int = getattr(val, 'col_offset', 0)
+
+    # Only enforce leading/trailing newline+indent for multi-line docstrings
+    # or when wrapping will occur. Keep short single-line docstrings unchanged.
+    leading_indent_: int | None = (
+        leading_indent if ('\n' in doc or len(doc) > line_length) else None
+    )
+
+    wrapped: str = wrap_docstring(
+        doc,
+        line_length=line_length,
+        docstring_style=docstring_style,
+        leading_indent=leading_indent_,  # type: ignore[arg-type]
+    )
+
+    new_literal: str | None = rebuild_literal(original_literal, wrapped)
+
+    new_literal = handle_single_line_docstring_that_is_a_bit_too_long(
+        whole_docstring_literal=new_literal,
+        docstring_content=wrapped,
+        docstring_starting_col=val.col_offset,
+        docstring_ending_col=val.end_col_offset,  # type: ignore[arg-type]
+        line_length=line_length,
+    )
+
+    if new_literal is None or new_literal == original_literal:
+        return None
+
+    return start, end, new_literal
+
+
+def find_docstring(node: ModuleClassOrFunc) -> ast.Expr | None:
+    """Return the first statement if it is a string-literal docstring.
+
+    Parameters
+    ----------
+    node : ModuleClassOrFunc
+        An ``ast.Module``, ``ast.ClassDef``, ``ast.FunctionDef``, or
+        ``ast.AsyncFunctionDef`` node.
+
+    Returns
+    -------
+    ast.Expr or None
+        The ``ast.Expr`` node that holds the docstring literal, if present;
+        otherwise ``None``.
+
+    """
+    body: list[ast.stmt] | None = getattr(node, 'body', None)
+    if not body:
+        return None
+
+    first = body[0]
+    if not isinstance(first, ast.Expr):
+        return None
+
+    val = first.value
+    if isinstance(val, ast.Constant) and isinstance(val.value, str):
+        return first
+
+    return None
+
+
+def calc_abs_pos(line_starts: list[int], lineno: int, col: int) -> int:
+    """Convert a (lineno, col) pair to an absolute index.
+
+    Parameters
+    ----------
+    line_starts : list[int]
+        Precomputed start offsets for each line, from :func:`_line_starts`.
+    lineno : int
+        1-based line number.
+    col : int
+        0-based column offset.
+
+    Returns
+    -------
+    int
+        The absolute character index into the source string.
+
+    """
+    return line_starts[lineno - 1] + col
+
+
+def rebuild_literal(original_literal: str, content: str) -> str | None:
+    """Rebuild a string literal preserving prefix and quote style.
+
+    Parameters
+    ----------
+    original_literal : str
+        The exact text of the original string literal including any prefix
+        and surrounding quotes.
+    content : str
+        The new inner content (without surrounding quotes).
+
+    Returns
+    -------
+    str or None
+        A new literal string with the same prefix and quotes and the new
+        content. Returns ``None`` if the original cannot be parsed.
+
+    """
+    i = 0
+    n = len(original_literal)
+    while i < n and original_literal[i] in 'rRuUbBfF':
+        i += 1
+
+    prefix = original_literal[:i]
+
+    delim = ''
+    if original_literal[i : i + 3] in ('"""', "'''"):
+        delim = original_literal[i : i + 3]
+        i += 3
+    elif i < n and original_literal[i] in ('"', "'"):
+        delim = original_literal[i]
+        i += 1
+    else:
+        return None
+
+    return f'{prefix}{delim}{content}{delim}'
+
+
+def wrap_docstring(
+        docstring: str,
+        line_length: int = 79,
+        docstring_style: str = 'numpy',
+        leading_indent: int = 0,
+) -> str:
+    """Wrap a docstring to the given line length (stub).
+
+    Parameters
+    ----------
+    docstring : str
+        The original docstring contents without quotes.
+    line_length : int, default=79
+        Target maximum line length for wrapping logic.
+    docstring_style : str, default="numpy"
+        The docstring style to target ('numpy' or 'google').
+    leading_indent : int, default=0
+        The number of indentation spaces of this docstring.
+
+    Returns
+    -------
+    str
+        The transformed docstring contents.
+
+    Notes
+    -----
+    This function dispatches to style-specific implementations:
+    - 'numpy'  -> wrap_docstring_numpy
+    - 'google' -> wrap_docstring_google
+
+    """
+    style = (docstring_style or '').strip().lower()
+    if style == 'google':
+        return wrap_docstring_google(
+            docstring, line_length, leading_indent=leading_indent
+        )
+    # Default to NumPy-style for unknown/unspecified styles to be permissive.
+    return wrap_docstring_numpy(
+        docstring, line_length, leading_indent=leading_indent
+    )

format_docstring/line_wrap_google.py

@@ -0,0 +1,7 @@
+def wrap_docstring_google(
+        docstring: str,
+        line_length: int,
+        leading_indent: int | None = None,
+) -> str:
+    """A placeholder for now."""  # noqa: D401
+    return ''