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

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

@@ -57,6 +57,11 @@ repos:
     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.2.0 → 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,7 +33,7 @@ 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
@@ -44,6 +44,8 @@ oriented before making changes.
   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
@@ -57,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`,
@@ -68,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.
@@ -83,17 +85,20 @@ 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.
@@ -101,7 +106,7 @@ oriented before making changes.
   content, and add regression cases whenever handling around literal sections
   or tables changes.
 
-## What is a "signature line"?
+## 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:

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

@@ -6,6 +6,13 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.0
+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>

{format_docstring-0.2.0 → format_docstring-0.2.1}/format_docstring/line_wrap_numpy.py

@@ -71,7 +71,7 @@ def wrap_docstring_numpy(
         'attribute',  # tolerate typo
         'attribute:',
     }
-    SECTION_RETURNS = {
+    SECTION_RETURNS_YIELDS = {
         'returns',
         'returns:',
         'return',  # tolerate typo
@@ -80,6 +80,8 @@ def wrap_docstring_numpy(
         'yields:',
         'yield',  # tolerate typo
         'yield:',
+    }
+    SECTION_RAISES = {
         'raises',
         'raises:',
         'raise',  # tolerate typo
@@ -183,7 +185,7 @@ def wrap_docstring_numpy(
             continue
 
         # Returns/Yields sections
-        if section_lower_case in SECTION_RETURNS:
+        if section_lower_case in SECTION_RETURNS_YIELDS:
             if line.strip() == '':
                 temp_out.append(line)
                 i += 1
@@ -234,6 +236,19 @@ def wrap_docstring_numpy(
             i += 1
             continue
 
+        # Raises section
+        if section_lower_case in SECTION_RAISES:
+            if line.strip() == '':
+                temp_out.append(line)
+                i += 1
+                continue
+
+            # Treat top-level lines as signatures
+            if indent_length <= leading_indent:  # type: ignore[operator]
+                temp_out.append(line)
+                i += 1
+                continue
+
         # Examples or any other section
         collect_to_temp_output(temp_out, line)
         i += 1

{format_docstring-0.2.0 → format_docstring-0.2.1}/format_docstring.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.0
+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>

{format_docstring-0.2.0 → format_docstring-0.2.1}/format_docstring.egg-info/SOURCES.txt

@@ -58,14 +58,16 @@ tests/test_data/end_to_end/numpy/module_level_docstring.txt
 tests/test_data/end_to_end/numpy/new_lines_before_and_after.txt
 tests/test_data/end_to_end/numpy/no_format_docstring_comment.txt
 tests/test_data/end_to_end/numpy/param_signature_without_type.txt
-tests/test_data/end_to_end/numpy/parameter_signature_sync.txt
 tests/test_data/end_to_end/numpy/parameters_returns_raises_wrapping.txt
 tests/test_data/end_to_end/numpy/returns_signature_and_description.txt
-tests/test_data/end_to_end/numpy/returns_signature_sync.txt
 tests/test_data/end_to_end/numpy/section_headings_with_colons.txt
 tests/test_data/end_to_end/numpy/section_title_fixed.txt
 tests/test_data/end_to_end/numpy/sections_notes_examples.txt
+tests/test_data/end_to_end/numpy/signature_dont_sync_raises.txt
 tests/test_data/end_to_end/numpy/signature_line_is_not_wrapped.txt
+tests/test_data/end_to_end/numpy/signature_sync_parameters.txt
+tests/test_data/end_to_end/numpy/signature_sync_returns.txt
+tests/test_data/end_to_end/numpy/signature_sync_yields.txt
 tests/test_data/end_to_end/numpy/single_line_docstring.txt
 tests/test_data/end_to_end/numpy/texts_are_rewrapped.txt
 tests/test_data/end_to_end/numpy/very_long_unbreakable_word.txt

{format_docstring-0.2.0 → format_docstring-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "format-docstring"
-version = "0.2.0"
+version = "0.2.1"
 description = "A Python formatter to wrap/adjust docstring lines"
 readme = "README.md"
 license = {text = "MIT"}

format_docstring-0.2.1/tests/test_data/end_to_end/numpy/signature_dont_sync_raises.txt

@@ -0,0 +1,48 @@
+LINE_LENGTH: 79
+
+**********
+def func1() -> Any:
+    """
+    Do something.
+
+    This test case is to make sure the raised exceptions are not modified by
+    this formatter.
+
+    Returns
+    -------
+    Any
+
+    Raises
+    ------
+    ValueError
+        When value is wrong. This is a very very very very very very very very very very very very very very very very very very very very very very very very very very very long line.
+    IOError
+        When IO is wrong. This is a very very very very very very very very very very very very very very very very very very very very very very very very very very very long line.
+    """
+    pass
+
+**********
+
+def func1() -> Any:
+    """
+    Do something.
+
+    This test case is to make sure the raised exceptions are not modified by
+    this formatter.
+
+    Returns
+    -------
+    Any
+
+    Raises
+    ------
+    ValueError
+        When value is wrong. This is a very very very very very very very very
+        very very very very very very very very very very very very very very
+        very very very very very long line.
+    IOError
+        When IO is wrong. This is a very very very very very very very very
+        very very very very very very very very very very very very very very
+        very very very very very long line.
+    """
+    pass

format_docstring-0.2.0/tests/test_data/end_to_end/numpy/returns_signature_sync.txt → format_docstring-0.2.1/tests/test_data/end_to_end/numpy/signature_sync_returns.txt

@@ -84,6 +84,35 @@ def custom_return_type_2() -> tuple['MyType1', "MyType2"]:
     """
     pass
 
+
+def with_return_var_name_1() -> str:
+    """
+    Do something
+
+    Returns
+    -------
+    result:float
+        The result
+    """
+    pass
+
+
+def with_return_var_name_2() -> tuple[str, int, int]:
+    """
+    Do something
+
+    Returns
+    -------
+    name:
+        The name
+    index :bool
+        The index
+    status: str
+        The status
+    """
+    pass
+
+
 **********
 from typing import List
 
@@ -167,3 +196,31 @@ def custom_return_type_2() -> tuple['MyType1', "MyType2"]:
         Integer
     """
     pass
+
+
+def with_return_var_name_1() -> str:
+    """
+    Do something
+
+    Returns
+    -------
+    result : str
+        The result
+    """
+    pass
+
+
+def with_return_var_name_2() -> tuple[str, int, int]:
+    """
+    Do something
+
+    Returns
+    -------
+    name : str
+        The name
+    index : int
+        The index
+    status : int
+        The status
+    """
+    pass

format_docstring-0.2.1/tests/test_data/end_to_end/numpy/signature_sync_yields.txt

@@ -0,0 +1,103 @@
+LINE_LENGTH: 79
+
+**********
+from collections.abc import Generator, Iterator
+
+
+def yield_numbers() -> Iterator[int]:
+    """
+    Yield numbers.
+
+    Yields
+    ------
+    str
+        Should match annotation.
+    """
+    yield 1
+
+
+def yield_named() -> Generator[int, None, None]:
+    """
+    Yield named.
+
+    Yields
+    ------
+    result : str
+        Should match annotation.
+    """
+    yield 1
+
+
+def yield_custom_type_1() -> Iterator['MyType1']:
+    """
+    Yield custom type.
+
+    Yields
+    ------
+    str
+    """
+    yield 'value'
+
+
+def yield_custom_type_2() -> Iterator[tuple['MyType1', "MyType2"]]:
+    """
+    Yield another custom type.
+
+    Yields
+    ------
+    str
+        Combined values.
+    """
+    yield 'value'
+    yield 1
+
+**********
+from collections.abc import Generator, Iterator
+
+
+def yield_numbers() -> Iterator[int]:
+    """
+    Yield numbers.
+
+    Yields
+    ------
+    Iterator[int]
+        Should match annotation.
+    """
+    yield 1
+
+
+def yield_named() -> Generator[int, None, None]:
+    """
+    Yield named.
+
+    Yields
+    ------
+    result : Generator[int, None, None]
+        Should match annotation.
+    """
+    yield 1
+
+
+def yield_custom_type_1() -> Iterator['MyType1']:
+    """
+    Yield custom type.
+
+    Yields
+    ------
+    Iterator['MyType1']
+    """
+    yield 'value'
+
+
+def yield_custom_type_2() -> Iterator[tuple['MyType1', "MyType2"]]:
+    """
+    Yield another custom type.
+
+    Yields
+    ------
+    Iterator[tuple['MyType1', "MyType2"]]
+        Combined values.
+    """
+    yield 'value'
+    yield 1