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

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

@@ -5,12 +5,19 @@ repos:
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
+        exclude: \.json$|\.ipynb$
       - id: debug-statements
       - id: double-quote-string-fixer
       - id: requirements-txt-fixer
-      - id: pretty-format-json
-        args: [--no-ensure-ascii, --indent=4, --no-sort-keys]
         exclude: \.ipynb$
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+      - id: check-toml
+      - id: check-yaml
+      - id: name-tests-test
+        args: [--pytest-test-first]
+        exclude: ^tests/test_data/|^tests/helpers\.py$
+      - id: check-merge-conflict
   - repo: https://github.com/asottile/pyupgrade
     rev: v3.20.0
     hooks:
@@ -31,15 +38,30 @@ repos:
     hooks:
       - id: yamlfix
   - repo: https://github.com/hukkin/mdformat
-    rev: 0.7.22
+    rev: 1.0.0
     hooks:
       - id: mdformat
         args: [--wrap, '79', --number]
-        additional_dependencies: [mdformat-tables]
+        additional_dependencies: [mdformat-gfm]
+  - repo: https://github.com/jsh9/format-json
+    rev: 0.1.2
+    hooks:
+      - id: format-json
+        args:
+          - --autofix
+          - --no-ensure-ascii
+          - --indent=4
+          - --no-sort-keys
+          - --no-eof-newline
   - repo: https://github.com/jsh9/markdown-toc-creator
     rev: 0.0.11
     hooks:
       - id: markdown-toc-creator
+  - repo: https://github.com/jsh9/markdown-heading-numbering
+    rev: 0.1.0
+    hooks:
+      - id: markdown-heading-numbering
+        exclude: ^CHANGELOG\.md$
   - repo: local
     hooks:
       - id: format-docstring

{format_docstring-0.1.9 → format_docstring-0.2.1}/AGENTS.md

@@ -3,7 +3,7 @@
 This guide briefs coding agents working on `format-docstring`. Use it to get
 oriented before making changes.
 
-## Quick Snapshot
+## 1. Quick Snapshot
 
 - Formats NumPy-style docstrings (with experimental Google support) in `.py`
   files and Jupyter notebooks while preserving surrounding code.
@@ -13,7 +13,7 @@ oriented before making changes.
   `jupyter-notebook-parser`, and `tomli/tomllib` for configuration loading.
 - Version is sourced dynamically in `format_docstring/__init__.py`.
 
-## Repository Layout
+## 2. Repository Layout
 
 - `format_docstring/main_py.py` – Click CLI for Python files; validates input
   and delegates to `PythonFileFixer`.
@@ -33,13 +33,24 @@ oriented before making changes.
 - `tests/` – Pytest suite with fixture-driven cases in `tests/test_data/`; see
   `tests/helpers.py` for fixture loading helpers.
 
-## Implementation Notes
+## 3. 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.
+- For functions, `_collect_param_metadata` records signature annotations and
+  default values so NumPy `Parameters` signatures in docstrings are
+  resynchronised with the real function definition. Defaulted parameters omit
+  redundant `, optional`, and forward references keep their original quoting.
+- Return annotations are likewise projected into `Returns`/`Yields` sections,
+  mirroring tuple element splits when the docstring already enumerates them.
+- `Raises` section entries are treated like signature lines in the NumPy
+  wrapper so exception names stay untouched while descriptions wrap.
 - Wrapping honors NumPy section heuristics, rST constructs, code fences,
   `Examples` prompts, and literal blocks introduced by `::`.
+- `_normalize_signature_segment` flattens multiline annotations via
+  `ast.unparse` but uses token-level replay to preserve the author's quoting
+  style for forward references and string defaults.
 - CLI exposes `--docstring-style`, but the Python entry-point currently raises
   if a non-NumPy style is requested; Jupyter flow passes style through
   unchanged.
@@ -48,7 +59,7 @@ oriented before making changes.
 - Notebook fixer round-trips JSON via `json.dump(..., indent=1)` and rewrites
   cells only when content changes, preserving magics with `reconstruct_source`.
 
-## Configuration
+## 4. Configuration
 
 - User-facing configuration lives under `[tool.format_docstring]` inside
   `pyproject.toml` and supports `line_length`, `docstring_style`, `exclude`,
@@ -59,7 +70,7 @@ oriented before making changes.
 - Default exclude pattern is `\.git|\.tox|\.pytest_cache`; tests tweak it as
   needed.
 
-## Development Workflow
+## 5. Development Workflow
 
 - Install: `pip install -e .` for the project,
   `pip install -r requirements.dev` for tooling.
@@ -74,20 +85,51 @@ oriented before making changes.
   `format-docstring-jupyter --help`.
 - Pre-commit: `pre-commit run -a`.
 
-## Testing Notes
+## 6. 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 `**********`.
+- Regression fixture
+  `tests/test_data/end_to_end/numpy/signature_dont_sync_raises.txt` guards
+  against mutating exception names in `Raises` blocks.
 - `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
+## 7. 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.
+
+## 8. What is a "signature line"?
+
+They are the lines in the docstring where input and return args are defined,
+for example, in this docstring:
+
+```python
+"""
+Do something
+
+Parameters
+----------
+arg1 : str
+    Arg 1
+arg2 : int = 2
+    Arg 2
+
+Returns
+-------
+dict[str, str]
+   The mapping
+```
+
+Signature lines are:
+
+- arg1 : str
+- arg2 : int = 2
+- dict[str, str]

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

@@ -6,6 +6,22 @@ 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.2.1] - 2025-10-20
+
+- Fixed
+  - A bug where raised exceptions in docstrings are incorrectly changed
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.2.0...0.2.1
+
+## [0.2.0] - 2025-10-20
+
+- Added
+  - AST-driven synchronization of NumPy `Parameters` and `Returns` signature
+    lines with the function signature, including tuple element expansion for
+    multi-line return blocks
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.9...0.2.0
+
 ## [0.1.9] - 2025-10-16
 
 - Added
@@ -17,6 +33,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Changed
   - Added "self format" pre-commit hook to format docstrings within this repo
     with its own formatting logic
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.8...0.1.9
 
 ## [0.1.8] - 2025-10-14
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.1.9
+Version: 0.2.1
 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>
@@ -34,6 +34,8 @@ Dynamic: license-file
 
 A Python formatter to automatically format numpy-style docstrings.
 
+______________________________________________________________________
+
 **Table of Contents:**
 
 <!--TOC-->
@@ -45,6 +47,7 @@ A Python formatter to automatically format numpy-style docstrings.
   - [2.3. Minor typos can be automatically fixed](#23-minor-typos-can-be-automatically-fixed)
   - [2.4. Default value declarations are standardized](#24-default-value-declarations-are-standardized)
   - [2.5. Single backticks are converted to double backticks (rST syntax)](#25-single-backticks-are-converted-to-double-backticks-rst-syntax)
+  - [2.6. Docstring parameters and returns stay in sync with signatures](#26-docstring-parameters-and-returns-stay-in-sync-with-signatures)
 - [3. Installation](#3-installation)
 - [4. Usage](#4-usage)
   - [4.1. Command Line Interface](#41-command-line-interface)
@@ -54,24 +57,28 @@ A Python formatter to automatically format numpy-style docstrings.
   - [5.1. Command-Line Options](#51-command-line-options)
   - [5.2. Usage Examples](#52-usage-examples)
   - [5.3. `pyproject.toml` Configuration](#53-pyprojecttoml-configuration)
+- [6. Caveat](#6-caveat)
 
 <!--TOC-->
 
+______________________________________________________________________
+
 ## 1. Overview
 
 `format-docstring` is a tool that automatically formats and wraps docstring
 content in Python files and Jupyter notebooks.
 
-Compared with [`docformatter`](https://github.com/PyCQA/docformatter) and
-[`pydocstringformatter`](https://github.com/DanielNoord/pydocstringformatter),
-this tool (`format-docstring`) goes further by intelligently wrapping docstring
-contents, fixing common typos, etc.
+Baseline reflow corresponds to the common docstring cleanups offered by
+general-purpose formatters: splitting one-line docstrings into the canonical
+multi-line layout (triple quotes, blank line, summary), normalizing
+indentation, and wrapping text at a fixed column width without applying extra
+heuristics.
 
-The formatting that would be done by
-[docformatter](https://github.com/PyCQA/docformatter) and
-[pydocstringformatter](https://github.com/DanielNoord/pydocstringformatter) can
-be readily handled by [Ruff](https://github.com/astral-sh/ruff) or
-[Black](https://github.com/psf/black).
+| Feature                                   | `format-docstring` | [docformatter] | [pydocstringformatter] | [Ruff] | [Black] |
+| ----------------------------------------- | ------------------ | -------------- | ---------------------- | ------ | ------- |
+| Docstring wrapping                        | ✅                 | ❌             | ❌                     | ❌     | ❌      |
+| Compatible with line length linter (E501) | ✅                 | ❌             | ❌                     | N/A    | N/A     |
+| Fixes common docstring typos              | ✅                 | ❌             | ❌                     | ❌     | ❌      |
 
 ## 2. Before vs After Examples
 
@@ -187,6 +194,25 @@ def mu_function():
     pass
 ```
 
+or, Google-style section headers can be fixed:
+
+```diff
+def my_function():
+    """
+    My function
+
+-    Args:
+-    ----
++    Parameters
++    ----------
+    arg1 : str
+        Arg 1
+
+    ...
+    """
+    pass
+```
+
 ### 2.4. Default value declarations are standardized
 
 ```diff
@@ -230,9 +256,94 @@ def process_data(data):
 -        Processed data with key `result`.
 +        Processed data with key ``result``.
     """
+```
+
+### 2.6. Docstring parameters and returns stay in sync with signatures
+
+```diff
+from typing import List, Optional
+
+
+def create_user(
+        user: Optional[str] = None,
+        roles: List["Role"] | None = None,
+        retries: int = 0,
+        serializer: "Serializer" | None = None,
+        something_else: tuple[int, ...] = (
+            "1",
+            '2',
+            3,
+            4,
+            5,
+            6,
+            7,
+            8,
+            9,
+            10,
+            11,
+            12,
+        ),
+) -> None:
+    """
+    Parameters
+    ----------
+-    user : str
++    user : Optional[str], default=None
+        Login name.
+-    roles : list
++    roles : List["Role"] | None, default=None
+        Assigned roles.
+-    retries : int
++    retries : int, default=0
+        Number of retry attempts.
+-    serializer : Serializer, optional
++    serializer : "Serializer" | None, default=None
+        Custom serializer instance.
+-    something_else : tuple[int, ...]
++    something_else : tuple[int, ...], default=("1", '2', 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)
+    """
     pass
 ```
 
+And return type hint:
+
+```diff
+def build_mapping() -> dict[str, str]:
+    """
+    Returns
+    -------
+-    str
++    dict[str, str]
+        Mapping of values.
+    """
+```
+
+For tuple return annotations, tuple elements are split across multiple
+signature lines only when the docstring already adopted that layout:
+
+```diff
+def compute_values() -> tuple[int, str, list[str]]:
+    """
+    Returns
+    -------
+-    float
++    int
+        First element.
+-    str
++    str
+        Second element.
+-    List[str]
++    list[str]
+        Third element.
+    """
+```
+
+Annotations and defaults are extracted from the actual function signature, so
+docstring signature lines reflect the ground truth. Defaulted parameters omit
+redundant `, optional`, forward references keep their original quoting, and
+return signatures track tuple splitting conventions already present in the
+docstring.
+
 ## 3. Installation
 
 ```bash
@@ -367,3 +478,17 @@ verbose = "default"  # or "diff" to print unified diffs
 
 The tool searches for `pyproject.toml` starting from the target file/directory
 and walking up the parent directories until one is found.
+
+## 6. Caveat
+
+This tool assumes the docstrings are written in **mostly** the correct format,
+because it needs those formatting cues (such as section headers and `------`)
+to parse docstrings.
+
+If the docstrings are far from perfectly formatted, it's recommended that you
+use AI coding assistants to rewrite the docstrings first.
+
+[black]: https://github.com/psf/black
+[docformatter]: https://github.com/PyCQA/docformatter
+[pydocstringformatter]: https://github.com/DanielNoord/pydocstringformatter
+[ruff]: https://github.com/astral-sh/ruff

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

@@ -2,6 +2,8 @@
 
 A Python formatter to automatically format numpy-style docstrings.
 
+______________________________________________________________________
+
 **Table of Contents:**
 
 <!--TOC-->
@@ -13,6 +15,7 @@ A Python formatter to automatically format numpy-style docstrings.
   - [2.3. Minor typos can be automatically fixed](#23-minor-typos-can-be-automatically-fixed)
   - [2.4. Default value declarations are standardized](#24-default-value-declarations-are-standardized)
   - [2.5. Single backticks are converted to double backticks (rST syntax)](#25-single-backticks-are-converted-to-double-backticks-rst-syntax)
+  - [2.6. Docstring parameters and returns stay in sync with signatures](#26-docstring-parameters-and-returns-stay-in-sync-with-signatures)
 - [3. Installation](#3-installation)
 - [4. Usage](#4-usage)
   - [4.1. Command Line Interface](#41-command-line-interface)
@@ -22,24 +25,28 @@ A Python formatter to automatically format numpy-style docstrings.
   - [5.1. Command-Line Options](#51-command-line-options)
   - [5.2. Usage Examples](#52-usage-examples)
   - [5.3. `pyproject.toml` Configuration](#53-pyprojecttoml-configuration)
+- [6. Caveat](#6-caveat)
 
 <!--TOC-->
 
+______________________________________________________________________
+
 ## 1. Overview
 
 `format-docstring` is a tool that automatically formats and wraps docstring
 content in Python files and Jupyter notebooks.
 
-Compared with [`docformatter`](https://github.com/PyCQA/docformatter) and
-[`pydocstringformatter`](https://github.com/DanielNoord/pydocstringformatter),
-this tool (`format-docstring`) goes further by intelligently wrapping docstring
-contents, fixing common typos, etc.
+Baseline reflow corresponds to the common docstring cleanups offered by
+general-purpose formatters: splitting one-line docstrings into the canonical
+multi-line layout (triple quotes, blank line, summary), normalizing
+indentation, and wrapping text at a fixed column width without applying extra
+heuristics.
 
-The formatting that would be done by
-[docformatter](https://github.com/PyCQA/docformatter) and
-[pydocstringformatter](https://github.com/DanielNoord/pydocstringformatter) can
-be readily handled by [Ruff](https://github.com/astral-sh/ruff) or
-[Black](https://github.com/psf/black).
+| Feature                                   | `format-docstring` | [docformatter] | [pydocstringformatter] | [Ruff] | [Black] |
+| ----------------------------------------- | ------------------ | -------------- | ---------------------- | ------ | ------- |
+| Docstring wrapping                        | ✅                 | ❌             | ❌                     | ❌     | ❌      |
+| Compatible with line length linter (E501) | ✅                 | ❌             | ❌                     | N/A    | N/A     |
+| Fixes common docstring typos              | ✅                 | ❌             | ❌                     | ❌     | ❌      |
 
 ## 2. Before vs After Examples
 
@@ -155,6 +162,25 @@ def mu_function():
     pass
 ```
 
+or, Google-style section headers can be fixed:
+
+```diff
+def my_function():
+    """
+    My function
+
+-    Args:
+-    ----
++    Parameters
++    ----------
+    arg1 : str
+        Arg 1
+
+    ...
+    """
+    pass
+```
+
 ### 2.4. Default value declarations are standardized
 
 ```diff
@@ -198,9 +224,94 @@ def process_data(data):
 -        Processed data with key `result`.
 +        Processed data with key ``result``.
     """
+```
+
+### 2.6. Docstring parameters and returns stay in sync with signatures
+
+```diff
+from typing import List, Optional
+
+
+def create_user(
+        user: Optional[str] = None,
+        roles: List["Role"] | None = None,
+        retries: int = 0,
+        serializer: "Serializer" | None = None,
+        something_else: tuple[int, ...] = (
+            "1",
+            '2',
+            3,
+            4,
+            5,
+            6,
+            7,
+            8,
+            9,
+            10,
+            11,
+            12,
+        ),
+) -> None:
+    """
+    Parameters
+    ----------
+-    user : str
++    user : Optional[str], default=None
+        Login name.
+-    roles : list
++    roles : List["Role"] | None, default=None
+        Assigned roles.
+-    retries : int
++    retries : int, default=0
+        Number of retry attempts.
+-    serializer : Serializer, optional
++    serializer : "Serializer" | None, default=None
+        Custom serializer instance.
+-    something_else : tuple[int, ...]
++    something_else : tuple[int, ...], default=("1", '2', 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)
+    """
     pass
 ```
 
+And return type hint:
+
+```diff
+def build_mapping() -> dict[str, str]:
+    """
+    Returns
+    -------
+-    str
++    dict[str, str]
+        Mapping of values.
+    """
+```
+
+For tuple return annotations, tuple elements are split across multiple
+signature lines only when the docstring already adopted that layout:
+
+```diff
+def compute_values() -> tuple[int, str, list[str]]:
+    """
+    Returns
+    -------
+-    float
++    int
+        First element.
+-    str
++    str
+        Second element.
+-    List[str]
++    list[str]
+        Third element.
+    """
+```
+
+Annotations and defaults are extracted from the actual function signature, so
+docstring signature lines reflect the ground truth. Defaulted parameters omit
+redundant `, optional`, forward references keep their original quoting, and
+return signatures track tuple splitting conventions already present in the
+docstring.
+
 ## 3. Installation
 
 ```bash
@@ -335,3 +446,17 @@ verbose = "default"  # or "diff" to print unified diffs
 
 The tool searches for `pyproject.toml` starting from the target file/directory
 and walking up the parent directories until one is found.
+
+## 6. Caveat
+
+This tool assumes the docstrings are written in **mostly** the correct format,
+because it needs those formatting cues (such as section headers and `------`)
+to parse docstrings.
+
+If the docstrings are far from perfectly formatted, it's recommended that you
+use AI coding assistants to rewrite the docstrings first.
+
+[black]: https://github.com/psf/black
+[docformatter]: https://github.com/PyCQA/docformatter
+[pydocstringformatter]: https://github.com/DanielNoord/pydocstringformatter
+[ruff]: https://github.com/astral-sh/ruff

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

@@ -8,7 +8,18 @@ from typing import Any
 
 
 class BaseFixer:
-    """Base class for fixing code formatting issues."""
+    r"""
+    Base class for fixing code formatting issues.
+
+    Parameters
+    ----------
+    path : str
+        Target file or directory to process.
+    exclude_pattern : str, default='\.git|\.tox|\.pytest_cache'
+        Regular expression describing paths to skip.
+    verbose : str, default='default'
+        Verbosity mode; ``'diff'`` prints unified diffs for rewritten files.
+    """
 
     def __init__(
             self,
@@ -16,7 +27,6 @@ class BaseFixer:
             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