format-docstring 0.2.4__tar.gz → 0.2.5__tar.gz

{format_docstring-0.2.4 → format_docstring-0.2.5}/.gitignore

@@ -208,3 +208,6 @@ __marimo__/
 
 # JetBrains IDEs
 .idea/
+
+# VS Code
+.vscode/

{format_docstring-0.2.4 → format_docstring-0.2.5}/CHANGELOG.md

@@ -6,6 +6,14 @@ 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.5] - 2025-11-20
+
+- Fixed
+  - A bug where `Generator[XXX, YYY, ZZZ]` in the return type annotation is not
+    parsed correctly (the Yields section should have been XXX)
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.2.4...0.2.5
+
 ## [0.2.4] - 2025-10-27
 
 - Fixed

{format_docstring-0.2.4 → format_docstring-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.4
+Version: 0.2.5
 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.4 → format_docstring-0.2.5}/format_docstring/line_wrap_numpy.py

@@ -197,6 +197,7 @@ def wrap_docstring_numpy(  # noqa: C901, PLR0915, TODO: https://github.com/jsh9/
 
             # Treat top-level lines as signatures
             if leading_indent is None or indent_length <= leading_indent:
+                is_yields_section = section_lower_case.startswith('yield')
                 if not return_signature_style_determined:
                     return_use_multiple_signatures = (
                         _detect_multiple_return_signatures(
@@ -223,6 +224,12 @@ def wrap_docstring_numpy(  # noqa: C901, PLR0915, TODO: https://github.com/jsh9/
                     # Fallback to last component when docstring expects more
                     desired_annotation = return_components[-1]
 
+                if is_yields_section:
+                    desired_annotation = (
+                        _unwrap_generator_annotation(desired_annotation)
+                        or desired_annotation
+                    )
+
                 if desired_annotation is None:
                     temp_out.append(line)
                     i += 1
@@ -618,19 +625,6 @@ def _split_tuple_annotation(annotation: str | None) -> list[str] | None:
     except (SyntaxError, ValueError):
         return None
 
-    def _name_of(node: ast.AST) -> str | None:
-        if isinstance(node, ast.Name):
-            return node.id
-
-        if isinstance(node, ast.Attribute):
-            base = _name_of(node.value)
-            if base is None:
-                return None
-
-            return f'{base}.{node.attr}'
-
-        return None
-
     if isinstance(expr, ast.Subscript):
         base_name = _name_of(expr.value)
         if base_name not in {'tuple', 'Tuple'}:
@@ -657,6 +651,63 @@ def _split_tuple_annotation(annotation: str | None) -> list[str] | None:
     return None
 
 
+def _name_of(node: ast.AST) -> str | None:
+    """
+    Return the dotted name represented by ``node`` if possible.
+    """
+    if isinstance(node, ast.Name):
+        return node.id
+
+    if isinstance(node, ast.Attribute):
+        base = _name_of(node.value)
+        if base is None:
+            return None
+
+        return f'{base}.{node.attr}'
+
+    return None
+
+
+def _unwrap_generator_annotation(annotation: str | None) -> str | None:
+    """
+    Return the first yield type when ``annotation`` is a Generator or
+    AsyncGenerator.
+
+    This is a small helper to keep ``Yields`` sections intuitive; Python
+    signatures often annotate generator functions as ``Generator[T, None,
+    None]`` but docstrings should spell out the yielded type ``T`` instead of
+    the whole container.
+    """
+    if annotation is None:
+        return None
+
+    try:
+        expr = ast.parse(annotation, mode='eval').body
+    except (SyntaxError, ValueError):
+        return None
+
+    if not isinstance(expr, ast.Subscript):
+        return None
+
+    base_name = _name_of(expr.value)
+    if base_name is None or base_name.split('.')[-1] not in {
+        'Generator',
+        'AsyncGenerator',
+    }:
+        return None
+
+    slice_node = expr.slice
+    if not isinstance(slice_node, ast.Tuple) or not slice_node.elts:
+        return None
+
+    first = slice_node.elts[0]
+    segment = ast.get_source_segment(annotation, first)
+    if segment is None:
+        segment = ast.unparse(first)
+
+    return segment.strip()
+
+
 def _detect_multiple_return_signatures(
         lines: list[str],
         start_idx: int,

{format_docstring-0.2.4 → format_docstring-0.2.5}/format_docstring.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.4
+Version: 0.2.5
 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.4 → format_docstring-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["setuptools-scm[toml]>=6.2", "setuptools>=45"]
 
 [project]
 name = "format-docstring"
-version = "0.2.4"
+version = "0.2.5"
 dependencies = [
   "click>=8.0",
   "jupyter-notebook-parser>=0.1.4",

{format_docstring-0.2.4 → format_docstring-0.2.5}/tests/test_data/end_to_end/numpy/signature_sync_yields.txt

@@ -51,6 +51,30 @@ def yield_custom_type_2() -> Iterator[tuple['MyType1', "MyType2"]]:
     yield 'value'
     yield 1
 
+
+def yield_middle_non_none() -> Generator[int, str, None]:
+    """
+    Yield with send type.
+
+    Yields
+    ------
+    str
+        Should match first annotation element, not send type.
+    """
+    yield 1
+
+
+def yield_last_non_none() -> Generator[int, None, str]:
+    """
+    Yield with return type.
+
+    Yields
+    ------
+    str
+        Should match first annotation element, not return type.
+    """
+    yield 1
+
 **********
 from collections.abc import Generator, Iterator
 
@@ -73,7 +97,7 @@ def yield_named() -> Generator[int, None, None]:
 
     Yields
     ------
-    result : Generator[int, None, None]
+    result : int
         Should match annotation.
     """
     yield 1
@@ -101,3 +125,27 @@ def yield_custom_type_2() -> Iterator[tuple['MyType1', "MyType2"]]:
     """
     yield 'value'
     yield 1
+
+
+def yield_middle_non_none() -> Generator[int, str, None]:
+    """
+    Yield with send type.
+
+    Yields
+    ------
+    int
+        Should match first annotation element, not send type.
+    """
+    yield 1
+
+
+def yield_last_non_none() -> Generator[int, None, str]:
+    """
+    Yield with return type.
+
+    Yields
+    ------
+    int
+        Should match first annotation element, not return type.
+    """
+    yield 1