format-docstring 0.1.7__tar.gz → 0.1.9__tar.gz

{format_docstring-0.1.7 → format_docstring-0.1.9}/.pre-commit-config.yaml

@@ -40,3 +40,27 @@ repos:
     rev: 0.0.11
     hooks:
       - id: markdown-toc-creator
+  - repo: local
+    hooks:
+      - id: format-docstring
+        name: Format self (python docstrings)
+        entry: python
+        args: [-m, format_docstring.main_py, --verbose, diff]
+        language: python
+        types: [python]
+        exclude: ^tests/test_data/
+        additional_dependencies:
+          - click>=8.0
+          - jupyter-notebook-parser>=0.1.4
+          - tomli>=1.1.0
+      - id: format-docstring-jupyter
+        name: Format self (docstrings in Jupyter notebooks)
+        entry: python
+        args: [-m, format_docstring.main_jupyter, --verbose, diff]
+        language: python
+        files: ^.*\.ipynb$
+        exclude: ^tests/test_data/
+        additional_dependencies:
+          - click>=8.0
+          - jupyter-notebook-parser>=0.1.4
+          - tomli>=1.1.0

format_docstring-0.1.9/AGENTS.md

@@ -0,0 +1,93 @@
+# AGENTS.md
+
+This guide briefs coding agents working on `format-docstring`. Use it to get
+oriented before making changes.
+
+## Quick Snapshot
+
+- Formats NumPy-style docstrings (with experimental Google support) in `.py`
+  files and Jupyter notebooks while preserving surrounding code.
+- Distributed as a CLI (`format-docstring`, `format-docstring-jupyter`) with
+  minimum Python 3.10, packaged via `setuptools`.
+- Core dependencies: `click`, `docstring_parser_fork`,
+  `jupyter-notebook-parser`, and `tomli/tomllib` for configuration loading.
+- Version is sourced dynamically in `format_docstring/__init__.py`.
+
+## Repository Layout
+
+- `format_docstring/main_py.py` – Click CLI for Python files; validates input
+  and delegates to `PythonFileFixer`.
+- `format_docstring/main_jupyter.py` – CLI for `.ipynb` files built on
+  `JupyterNotebookParser`/`JupyterNotebookRewriter`.
+- `format_docstring/base_fixer.py` – Shared directory traversal, exclusion
+  regex handling, and `fix_one_directory_or_one_file` orchestration.
+- `format_docstring/docstring_rewriter.py` – AST-based docstring extraction and
+  replacement that leaves non-docstring text untouched.
+- `format_docstring/line_wrap_numpy.py` / `line_wrap_google.py` –
+  Style-specific wrapping helpers; NumPy path is the production code path,
+  Google is partial.
+- `format_docstring/line_wrap_utils.py` – Shared utilities for wrapping (indent
+  management, bullet handling, preserving literal blocks, etc.).
+- `format_docstring/config.py` – `pyproject.toml` discovery, parsing, and Click
+  default injection.
+- `tests/` – Pytest suite with fixture-driven cases in `tests/test_data/`; see
+  `tests/helpers.py` for fixture loading helpers.
+
+## Implementation Notes
+
+- `docstring_rewriter.fix_src` parses with `ast.parse`, collects docstring
+  literals, and rewrites source slices using absolute offsets from
+  `calc_line_starts`; this avoids `ast.unparse` and keeps comments/spacing.
+- Wrapping honors NumPy section heuristics, rST constructs, code fences,
+  `Examples` prompts, and literal blocks introduced by `::`.
+- CLI exposes `--docstring-style`, but the Python entry-point currently raises
+  if a non-NumPy style is requested; Jupyter flow passes style through
+  unchanged.
+- `BaseFixer` subclasses return `1` when any file changed so callers can
+  surface non-zero exit codes.
+- Notebook fixer round-trips JSON via `json.dump(..., indent=1)` and rewrites
+  cells only when content changes, preserving magics with `reconstruct_source`.
+
+## Configuration
+
+- User-facing configuration lives under `[tool.format_docstring]` inside
+  `pyproject.toml` and supports `line_length`, `docstring_style`, `exclude`,
+  `fix_rst_backticks`, and `verbose` (`default` or `diff` to print unified
+  diffs on rewrites).
+- `config.inject_config_from_file` auto-discovers the nearest `pyproject.toml`
+  (walking up from targets) and merges values into Click’s `default_map`.
+- Default exclude pattern is `\.git|\.tox|\.pytest_cache`; tests tweak it as
+  needed.
+
+## Development Workflow
+
+- Install: `pip install -e .` for the project,
+  `pip install -r requirements.dev` for tooling.
+- Tests: `pytest --tb=long`, or target modules such as
+  `pytest tests/test_docstring_rewriter.py`.
+- Lint/format: `muff check --fix --config=muff.toml format_docstring tests`,
+  `muff format --diff --config=muff.toml format_docstring tests`.
+- Type checking: `mypy format_docstring/`.
+- Tox: `tox` for the full matrix (py310–py313, mypy, lint), or focused runs
+  like `tox -e py311`, `tox -e mypy`, `tox -e muff-format`.
+- CLI smoke tests: `format-docstring --help`,
+  `format-docstring-jupyter --help`.
+- Pre-commit: `pre-commit run -a`.
+
+## Testing Notes
+
+- Fixture files under `tests/test_data/line_wrap` and
+  `tests/test_data/end_to_end` use `LINE_LENGTH: <int>` headers followed by
+  `BEFORE`/`AFTER` sections split by `**********`.
+- `tests/test_playground.py` focuses on regression snippets;
+  `tests/test_config.py` exercises config discovery and CLI overrides.
+- When modifying wrapping rules, update both the helper (`line_wrap_utils.py`)
+  and the corresponding expectation files in `tests/test_data/`.
+
+## Style Guidance
+
+- Formatting rules mirror `muff.toml` (line length 79, single quotes, NumPy
+  docstring convention). Respect these when adding code.
+- Keep docstring style tests conservative: avoid mutating non-docstring
+  content, and add regression cases whenever handling around literal sections
+  or tables changes.

{format_docstring-0.1.7 → format_docstring-0.1.9}/CHANGELOG.md

@@ -6,6 +6,39 @@ The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.9] - 2025-10-16
+
+- Added
+  - A "`# no-format-docstring`" directive to ignore certain docstring
+  - Verbose diff output via `--verbose diff` and
+    `[tool.format_docstring] verbose`
+  - Normalize NumPy section headings that include trailing colons (e.g.,
+    `Parameters:`); also, fix Google-style "Arg" header into "Parameters"
+- Changed
+  - Added "self format" pre-commit hook to format docstrings within this repo
+    with its own formatting logic
+
+## [0.1.8] - 2025-10-14
+
+- Fixed
+  - Bug in `_fix_rst_backticks()` where backtick pairs spanning multiple lines
+    (e.g., multi-line external links) were incorrectly processed
+  - Added `(?!_)` lookahead to regex pattern to prevent matching trailing
+    backticks from cross-references (e.g., `` `text`_ ``)
+- Changed
+  - Moved backtick fixing from line-by-line processing to whole-docstring
+    processing to correctly handle multi-line constructs
+  - REPL lines (starting with `>>> ` or `... `) are now protected with
+    placeholders during backtick fixing to preserve backticks in Python
+    examples
+- Added
+  - Test cases for multi-line external links in
+    `test_fix_rst_backticks_cases()`
+  - Test cases for REPL lines with backticks in
+    `test_fix_rst_backticks_cases()`
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.7...0.1.8
+
 ## [0.1.7] - 2025-10-14
 
 - Fixed
@@ -13,6 +46,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
     external links (e.g., `` `Python <https://example.org>`_ ``)
   - Refactored `_fix_rst_backticks()` to use pre-compiled regex pattern for
     better performance
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.6...0.1.7
 
 ## [0.1.6] - 2025-10-13
 

{format_docstring-0.1.7 → format_docstring-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.1.7
+Version: 0.1.9
 Summary: A Python formatter to wrap/adjust docstring lines
 Author-email: jsh9 <25124332+jsh9@users.noreply.github.com>
 Maintainer-email: jsh9 <25124332+jsh9@users.noreply.github.com>
@@ -27,7 +27,6 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: jupyter-notebook-parser>=0.1.4
 Requires-Dist: click>=8.0
-Requires-Dist: docstring_parser_fork>=0.0.14
 Requires-Dist: tomli>=1.1.0; python_version < "3.11"
 Dynamic: license-file
 
@@ -50,6 +49,7 @@ A Python formatter to automatically format numpy-style docstrings.
 - [4. Usage](#4-usage)
   - [4.1. Command Line Interface](#41-command-line-interface)
   - [4.2. Pre-commit Hook](#42-pre-commit-hook)
+  - [4.3. Opting Out of Formatting](#43-opting-out-of-formatting)
 - [5. Configuration](#5-configuration)
   - [5.1. Command-Line Options](#51-command-line-options)
   - [5.2. Usage Examples](#52-usage-examples)
@@ -281,6 +281,19 @@ Then install the pre-commit hook:
 pre-commit install
 ```
 
+### 4.3. Opting Out of Formatting
+
+Add a comment containing `no-format-docstring` on the same line as the closing
+triple quotes to prevent the formatter from touching that docstring:
+`""" ... """  # no-format-docstring`.
+
+You can combine this "no-format-docstring" with other directives like "noqa".
+
+Tip: If you only want to keep specific formatter changes inside a docstring,
+first run `format-docstring`, accept the parts you like, revert the edits you
+dislike, and then add an inline `# no-format-docstring` comment so future runs
+leave that docstring untouched.
+
 ## 5. Configuration
 
 ### 5.1. Command-Line Options
@@ -291,6 +304,8 @@ pre-commit install
   default: `numpy`). Note: Currently only `numpy` style is fully supported.
 - `--fix-rst-backticks BOOL`: Automatically fix single backticks to double
   backticks per rST syntax (default: True)
+- `--verbose CHOICE`: Logging detail level (`default` keeps the existing
+  behaviour, `diff` prints unified diffs when rewrites happen)
 - `--exclude TEXT`: Regex pattern to exclude files/directories (default:
   `\.git|\.tox|\.pytest_cache`)
 - `--config PATH`: Path to a `pyproject.toml` config file. If not specified,
@@ -311,6 +326,9 @@ format-docstring --line-length 72 src/
 # Format Jupyter notebooks excluding certain directories
 format-docstring-jupyter --exclude "\.git|\.venv|__pycache__" notebooks/
 
+# Preview changes with unified diffs
+format-docstring --verbose diff src/
+
 # Use a specific config file
 format-docstring --config path/to/pyproject.toml src/
 
@@ -332,6 +350,7 @@ line_length = 79
 docstring_style = "numpy"
 fix_rst_backticks = true
 exclude = "\\.git|\\.venv|__pycache__"
+verbose = "default"  # or "diff" to print unified diffs
 ```
 
 **Available options:**
@@ -344,6 +363,7 @@ exclude = "\\.git|\\.venv|__pycache__"
   backticks per rST syntax (default: `true`)
 - `exclude` (str): Regex pattern to exclude files/directories (default:
   `"\\.git|\\.tox|\\.pytest_cache"`)
+- `verbose` (str): Logging detail level (`"default"` or `"diff"`)
 
 The tool searches for `pyproject.toml` starting from the target file/directory
 and walking up the parent directories until one is found.

{format_docstring-0.1.7 → format_docstring-0.1.9}/README.md

@@ -17,6 +17,7 @@ A Python formatter to automatically format numpy-style docstrings.
 - [4. Usage](#4-usage)
   - [4.1. Command Line Interface](#41-command-line-interface)
   - [4.2. Pre-commit Hook](#42-pre-commit-hook)
+  - [4.3. Opting Out of Formatting](#43-opting-out-of-formatting)
 - [5. Configuration](#5-configuration)
   - [5.1. Command-Line Options](#51-command-line-options)
   - [5.2. Usage Examples](#52-usage-examples)
@@ -248,6 +249,19 @@ Then install the pre-commit hook:
 pre-commit install
 ```
 
+### 4.3. Opting Out of Formatting
+
+Add a comment containing `no-format-docstring` on the same line as the closing
+triple quotes to prevent the formatter from touching that docstring:
+`""" ... """  # no-format-docstring`.
+
+You can combine this "no-format-docstring" with other directives like "noqa".
+
+Tip: If you only want to keep specific formatter changes inside a docstring,
+first run `format-docstring`, accept the parts you like, revert the edits you
+dislike, and then add an inline `# no-format-docstring` comment so future runs
+leave that docstring untouched.
+
 ## 5. Configuration
 
 ### 5.1. Command-Line Options
@@ -258,6 +272,8 @@ pre-commit install
   default: `numpy`). Note: Currently only `numpy` style is fully supported.
 - `--fix-rst-backticks BOOL`: Automatically fix single backticks to double
   backticks per rST syntax (default: True)
+- `--verbose CHOICE`: Logging detail level (`default` keeps the existing
+  behaviour, `diff` prints unified diffs when rewrites happen)
 - `--exclude TEXT`: Regex pattern to exclude files/directories (default:
   `\.git|\.tox|\.pytest_cache`)
 - `--config PATH`: Path to a `pyproject.toml` config file. If not specified,
@@ -278,6 +294,9 @@ format-docstring --line-length 72 src/
 # Format Jupyter notebooks excluding certain directories
 format-docstring-jupyter --exclude "\.git|\.venv|__pycache__" notebooks/
 
+# Preview changes with unified diffs
+format-docstring --verbose diff src/
+
 # Use a specific config file
 format-docstring --config path/to/pyproject.toml src/
 
@@ -299,6 +318,7 @@ line_length = 79
 docstring_style = "numpy"
 fix_rst_backticks = true
 exclude = "\\.git|\\.venv|__pycache__"
+verbose = "default"  # or "diff" to print unified diffs
 ```
 
 **Available options:**
@@ -311,6 +331,7 @@ exclude = "\\.git|\\.venv|__pycache__"
   backticks per rST syntax (default: `true`)
 - `exclude` (str): Regex pattern to exclude files/directories (default:
   `"\\.git|\\.tox|\\.pytest_cache"`)
+- `verbose` (str): Logging detail level (`"default"` or `"diff"`)
 
 The tool searches for `pyproject.toml` starting from the target file/directory
 and walking up the parent directories until one is found.

{format_docstring-0.1.7 → format_docstring-0.1.9}/format_docstring/base_fixer.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import difflib
 import re
+import sys
 from pathlib import Path
 from typing import Any
 
@@ -12,10 +14,12 @@ class BaseFixer:
             self,
             path: str,
             exclude_pattern: str = r'\.git|\.tox|\.pytest_cache',
+            verbose: str = 'default',
     ) -> None:
         """Initialize the fixer with a path and optional exclude pattern."""
         self.path = path
         self.exclude_pattern = exclude_pattern
+        self.verbose = verbose
 
     def _get_files_to_process(
             self, directory: Path, pattern: str
@@ -28,6 +32,25 @@ class BaseFixer:
             if not should_exclude_file(f, self.exclude_pattern)
         ]
 
+    def _print_diff(self, filename: str, before: str, after: str) -> None:
+        """Print a unified diff when verbose mode is enabled."""
+        if self.verbose != 'diff':
+            return
+
+        diff = difflib.unified_diff(
+            before.splitlines(keepends=True),
+            after.splitlines(keepends=True),
+            fromfile=f'{filename} (before)',
+            tofile=f'{filename} (after)',
+            lineterm='',
+        )
+        diff_text = ''.join(diff)
+        if diff_text:
+            if not diff_text.endswith('\n'):
+                diff_text += '\n'
+
+            print(diff_text, file=sys.stderr, end='')
+
     def fix_one_directory_or_one_file(self) -> int:
         """
         Fix formatting in a single file or all Python files in a directory.
@@ -55,9 +78,10 @@ class BaseFixer:
 
 
 def should_exclude_file(file_path: Path, exclude_pattern: str) -> bool:
-    """Return True if `file_path` matches the provided exclude regex.
+    """
+    Return True if ``file_path`` matches the provided exclude regex.
 
-    If `exclude_pattern` is empty or invalid, no files are excluded.
+    If ``exclude_pattern`` is empty or invalid, no files are excluded.
     """
     if not exclude_pattern:
         return False

{format_docstring-0.1.7 → format_docstring-0.1.9}/format_docstring/docstring_rewriter.py

@@ -12,6 +12,40 @@ ModuleClassOrFunc = (
     ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef
 )
 
+NO_FORMAT_DOCSTRING_MARKER = 'no-format-docstring'
+
+
+def _determine_newline(text: str) -> str:
+    r"""
+    Return the dominant newline style detected in ``text``.
+
+    Defaults to ``\n`` when no Windows/Mac classic newlines are present.
+    """
+    if '\r\n' in text:
+        return '\r\n'
+
+    if '\r' in text:
+        return '\r'
+
+    return '\n'
+
+
+def _has_inline_no_format_comment(source_code: str, end_pos: int) -> bool:
+    """
+    Return True if the closing quotes share a line with the sentinel comment.
+    """
+    source_len = len(source_code)
+    line_end = source_code.find('\n', end_pos)
+    if line_end == -1:
+        line_end = source_len
+
+    same_line_segment = source_code[end_pos:line_end].lower()
+    hash_index = same_line_segment.find('#')
+    if hash_index == -1:
+        return False
+
+    return NO_FORMAT_DOCSTRING_MARKER in same_line_segment[hash_index:]
+
 
 def fix_src(
         source_code: str,
@@ -20,7 +54,8 @@ def fix_src(
         docstring_style: str = 'numpy',
         fix_rst_backticks: bool = True,
 ) -> str:
-    """Return code with only docstrings updated to wrapped content.
+    """
+    Return code with only docstrings updated to wrapped content.
 
     Parameters
     ----------
@@ -31,21 +66,20 @@ def fix_src(
     docstring_style : str, default='numpy'
         The docstring style to target ('numpy' or 'google').
     fix_rst_backticks : bool, default=True
-        If True, automatically fix single backticks to double backticks per
-        rST syntax.
+        If True, automatically fix single backticks to double backticks per rST
+        syntax.
 
     Returns
     -------
     str
-        The updated source code. Only docstring literals are changed; all
-        other formatting is preserved.
+        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.
-
+    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)
@@ -93,7 +127,8 @@ def fix_src(
 
 
 def calc_line_starts(source_code: str) -> list[int]:
-    """Return starting offsets for each line in the source string.
+    """
+    Return starting offsets for each line in the source string.
 
     Parameters
     ----------
@@ -104,7 +139,6 @@ def calc_line_starts(source_code: str) -> list[int]:
     -------
     list[int]
         A list of absolute indices for the start of each line.
-
     """
     starts: list[int] = [0]
     for i, ch in enumerate(source_code):
@@ -122,7 +156,8 @@ def build_replacement_docstring(
         docstring_style: str = 'numpy',
         fix_rst_backticks: bool = True,
 ) -> tuple[int, int, str] | None:
-    """Compute a single docstring replacement for the given node.
+    """
+    Compute a single docstring replacement for the given node.
 
     Parameters
     ----------
@@ -137,15 +172,14 @@ def build_replacement_docstring(
     docstring_style : str, default='numpy'
         The docstring style to target ('numpy' or 'google').
     fix_rst_backticks : bool, default=True
-        If True, automatically fix single backticks to double backticks per
-        rST syntax.
+        If True, automatically fix single backticks to double backticks per rST
+        syntax.
 
     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.
-
+        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:
@@ -159,6 +193,9 @@ def build_replacement_docstring(
     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]
 
+    if _has_inline_no_format_comment(source_code, end):
+        return None
+
     doc: str | None = ast.get_docstring(node, clean=False)
     if doc is None:
         return None
@@ -200,7 +237,8 @@ def build_replacement_docstring(
 
 
 def find_docstring(node: ModuleClassOrFunc) -> ast.Expr | None:
-    """Return the first statement if it is a string-literal docstring.
+    """
+    Return the first statement if it is a string-literal docstring.
 
     Parameters
     ----------
@@ -213,7 +251,6 @@ def find_docstring(node: ModuleClassOrFunc) -> ast.Expr | None:
     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:
@@ -231,7 +268,8 @@ def find_docstring(node: ModuleClassOrFunc) -> ast.Expr | None:
 
 
 def calc_abs_pos(line_starts: list[int], lineno: int, col: int) -> int:
-    """Convert a (lineno, col) pair to an absolute index.
+    """
+    Convert a (lineno, col) pair to an absolute index.
 
     Parameters
     ----------
@@ -246,19 +284,19 @@ def calc_abs_pos(line_starts: list[int], lineno: int, col: int) -> int:
     -------
     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.
+    """
+    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.
+        The exact text of the original string literal including any prefix and
+        surrounding quotes.
     content : str
         The new inner content (without surrounding quotes).
 
@@ -267,7 +305,6 @@ def rebuild_literal(original_literal: str, content: str) -> str | None:
     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)
@@ -286,6 +323,11 @@ def rebuild_literal(original_literal: str, content: str) -> str | None:
     else:
         return None
 
+    newline: str = _determine_newline(original_literal)
+    if newline != '\n':
+        normalized_content = content.replace('\r\n', '\n').replace('\r', '\n')
+        content = newline.join(normalized_content.split('\n'))
+
     return f'{prefix}{delim}{content}{delim}'
 
 
@@ -296,7 +338,8 @@ def wrap_docstring(
         leading_indent: int = 0,
         fix_rst_backticks: bool = True,
 ) -> str:
-    """Wrap a docstring to the given line length (stub).
+    """
+    Wrap a docstring to the given line length (stub).
 
     Parameters
     ----------
@@ -309,8 +352,8 @@ def wrap_docstring(
     leading_indent : int, default=0
         The number of indentation spaces of this docstring.
     fix_rst_backticks : bool, default=True
-        If True, automatically fix single backticks to double backticks per
-        rST syntax.
+        If True, automatically fix single backticks to double backticks per rST
+        syntax.
 
     Returns
     -------
@@ -322,7 +365,6 @@ def wrap_docstring(
     This function dispatches to style-specific implementations:
     - 'numpy'  -> wrap_docstring_numpy
     - 'google' -> wrap_docstring_google
-
     """
     style = (docstring_style or '').strip().lower()
     if style == 'google':