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

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

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

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

@@ -6,6 +6,27 @@ 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.6] - 2025-11-21
+
+- Fixed
+  - Multiline annotations now normalize without inserting spaces inside
+    `Literal[...]` or other bracketed signatures, even when they span several
+    lines.
+  - A bug where bare `*args`/`**kwargs` signature lines (typed or untyped)
+    would be merged into previous descriptions
+  - NumPy signature syncing left the `:class:` / `:meth:` role prefixes behind,
+    producing mismatched annotations like ` : MyClass`
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.2.5...0.2.6
+
+## [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.6}/PKG-INFO

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

@@ -3,6 +3,7 @@ from __future__ import annotations
 import ast
 import io
 import operator
+import textwrap
 import tokenize
 from typing import TYPE_CHECKING
 
@@ -83,12 +84,18 @@ def _normalize_signature_segment(segment: str | None) -> str | None:
 
     normalized: str = segment.strip()
     if '\n' in normalized or '\r' in normalized or '\t' in normalized:
+        dedented: str = textwrap.dedent(normalized)
+        # Wrap in parentheses so unions split across lines
+        # (e.g. ``Literal[...] | None``)
+        # remain valid ``eval`` expressions even when indentation is uneven.
+        wrapped_for_parse = f'({dedented})'
+
         # `ast.unparse(ast.parse(...))` neatly flattens whitespace but it also
         # canonicalises string quotes to single quotes. We still rely on it for
         # whitespace normalization, so capture its output first.
         try:
-            canonical = ast.unparse(ast.parse(normalized))
-        except (SyntaxError, ValueError):
+            canonical = ast.unparse(ast.parse(wrapped_for_parse, mode='eval'))
+        except (SyntaxError, ValueError, IndentationError):
             return ' '.join(normalized.split())
 
         # Remember the exact string literal tokens from the original text. The

{format_docstring-0.2.4 → format_docstring-0.2.6}/format_docstring/line_wrap_numpy.py

@@ -170,18 +170,22 @@ def wrap_docstring_numpy(  # noqa: C901, PLR0915, TODO: https://github.com/jsh9/
             # section (indentation < 4). This prevents mis-detecting
             # description lines that happen to contain a colon (e.g., tables,
             # examples, notes) as new parameter signatures.
-            if _is_param_signature(line) and (
-                leading_indent is None or indent_length <= leading_indent
-            ):
-                fixed_line = _fix_colon_spacing(line)
-                fixed_line = _standardize_default_value(fixed_line)
-                fixed_line = _rewrite_parameter_signature(
-                    fixed_line, metadata_for_section
-                )
-                fixed_line = _standardize_default_value(fixed_line)
-                temp_out.append(fixed_line)
-                i += 1
-                continue
+            if leading_indent is None or indent_length <= leading_indent:
+                if _is_param_signature(line):
+                    fixed_line = _fix_colon_spacing(line)
+                    fixed_line = _standardize_default_value(fixed_line)
+                    fixed_line = _rewrite_parameter_signature(
+                        fixed_line, metadata_for_section
+                    )
+                    fixed_line = _standardize_default_value(fixed_line)
+                    temp_out.append(fixed_line)
+                    i += 1
+                    continue
+
+                if _is_bare_variadic_signature(line):
+                    temp_out.append(line)
+                    i += 1
+                    continue
 
             # Description lines (typically indented): wrap if too long
             collect_to_temp_output(temp_out, line)
@@ -197,6 +201,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 +228,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
@@ -334,6 +345,13 @@ _PARAM_SIGNATURE_RE = re.compile(
     rf'^\s*\*{{0,2}}{START}{CONT}*(?:\s*,\s*\*{{0,2}}{START}{CONT}*)*\s*:\s*.*$'
 )
 
+# Matches bare variadic signatures without a colon, e.g. ``**kwargs`` or
+# ``*args, **kwargs``. These should be treated like signatures so description
+# text doesn't get collapsed into the preceding entry.
+_BARE_VARIADIC_SIGNATURE_RE = re.compile(
+    rf'^\s*\*{{1,2}}{START}{CONT}*(?:\s*,\s*\*{{1,2}}{START}{CONT}*)*\s*$'
+)
+
 
 def _is_param_signature(text: str) -> bool:
     r"""
@@ -364,6 +382,16 @@ def _is_param_signature(text: str) -> bool:
     return bool(_PARAM_SIGNATURE_RE.match(text))
 
 
+def _is_bare_variadic_signature(text: str) -> bool:
+    """
+    Return True for variadic parameter lines lacking ``:`` annotations.
+
+    Handles stripped signatures such as ``**kwargs`` so they are preserved as
+    their own logical entries inside ``Parameters`` sections.
+    """
+    return bool(_BARE_VARIADIC_SIGNATURE_RE.match(text))
+
+
 def _fix_colon_spacing(line: str) -> str:
     """
     Fix spacing around colons in parameter signature lines.
@@ -618,19 +646,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 +672,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,
@@ -697,6 +769,12 @@ def _rewrite_return_signature(line: str, annotation: str) -> str:
     colon_idx = stripped.find(':')
     if colon_idx != -1:
         name = stripped[:colon_idx].rstrip()
+        # Only treat the colon as a signature separator if something precedes
+        # it. rST cross references such as ``:class:`Foo``` start with a colon,
+        # in which case we just want to output the synced annotation.
+        if not name:
+            return f'{indent}{annotation}'
+
         return f'{indent}{name} : {annotation}'
 
     return f'{indent}{annotation}'

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.4
+Version: 0.2.6
 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.6}/format_docstring.egg-info/SOURCES.txt

@@ -60,6 +60,7 @@ 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/parameters_returns_raises_wrapping.txt
+tests/test_data/end_to_end/numpy/rST_cross_reference.txt
 tests/test_data/end_to_end/numpy/returns_signature_and_description.txt
 tests/test_data/end_to_end/numpy/section_headings_with_colons.txt
 tests/test_data/end_to_end/numpy/section_title_fixed.txt
@@ -72,6 +73,7 @@ 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/variadic_signature_without_colon.txt
 tests/test_data/end_to_end/numpy/very_long_unbreakable_word.txt
 tests/test_data/integration_test/numpy/after.ipynb
 tests/test_data/integration_test/numpy/after.py
@@ -104,4 +106,5 @@ tests/test_data/line_wrap/numpy/section_title_fixed.txt
 tests/test_data/line_wrap/numpy/sections_notes_examples.txt
 tests/test_data/line_wrap/numpy/signature_line_is_not_wrapped.txt
 tests/test_data/line_wrap/numpy/texts_are_rewrapped.txt
+tests/test_data/line_wrap/numpy/variadic_signature_without_colon.txt
 tests/test_data/line_wrap/numpy/very_long_unbreakable_word.txt

{format_docstring-0.2.4 → format_docstring-0.2.6}/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.6"
 dependencies = [
   "click>=8.0",
   "jupyter-notebook-parser>=0.1.4",

format_docstring-0.2.6/tests/test_data/end_to_end/numpy/rST_cross_reference.txt

@@ -0,0 +1,72 @@
+LINE_LENGTH: 79
+
+**********
+
+def myfunc() -> MyClass:
+    """
+    Do something
+
+    Returns
+    -------
+    :class:`MyClass`
+        An instance of MyClass
+    """
+    pass
+
+
+def uses_cross_refs(
+        thing: MyClass,
+        creator: Callable[[MyClass], MyClass],
+) -> MyClass:
+    """
+    Uses parameters and returns that reference rST roles.
+
+    Parameters
+    ----------
+    thing : :class:`MyClass`
+        Object to transform.
+    creator : :meth:`MyClass.build`
+        Callback that builds a new instance.
+
+    Returns
+    -------
+    :meth:`MyClass.build`
+        A created instance.
+    """
+    return creator(thing)
+
+
+**********
+
+def myfunc() -> MyClass:
+    """
+    Do something
+
+    Returns
+    -------
+    MyClass
+        An instance of MyClass
+    """
+    pass
+
+
+def uses_cross_refs(
+        thing: MyClass,
+        creator: Callable[[MyClass], MyClass],
+) -> MyClass:
+    """
+    Uses parameters and returns that reference rST roles.
+
+    Parameters
+    ----------
+    thing : MyClass
+        Object to transform.
+    creator : Callable[[MyClass], MyClass]
+        Callback that builds a new instance.
+
+    Returns
+    -------
+    MyClass
+        A created instance.
+    """
+    return creator(thing)

{format_docstring-0.2.4 → format_docstring-0.2.6}/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

format_docstring-0.2.6/tests/test_data/end_to_end/numpy/variadic_signature_without_colon.txt

@@ -0,0 +1,58 @@
+LINE_LENGTH: 75
+
+**********
+def function_with_variadics():
+    """
+    Parameters
+    ----------
+    arg1 : str
+        Something short
+    **kwargs
+        Keyword args that should remain on their own entry.
+    *custom_args
+        Positional extras that should wrap to their own block even without a colon.
+    **some_other_strange_name
+        Keyword extras that likewise need wrapping to stay with their entry.
+    *explicit_typed_args : tuple[int, ...]
+        Shows a variadic entry that still provides a type annotation.
+    **typed_kwargs : dict[str, int]
+        Another variadic keyword argument that uses a type hint.
+    """
+    return (
+        arg1,
+        kwargs,
+        custom_args,
+        some_other_strange_name,
+        explicit_typed_args,
+        typed_kwargs,
+    )
+
+**********
+
+def function_with_variadics():
+    """
+    Parameters
+    ----------
+    arg1 : str
+        Something short
+    **kwargs
+        Keyword args that should remain on their own entry.
+    *custom_args
+        Positional extras that should wrap to their own block even without
+        a colon.
+    **some_other_strange_name
+        Keyword extras that likewise need wrapping to stay with their
+        entry.
+    *explicit_typed_args : tuple[int, ...]
+        Shows a variadic entry that still provides a type annotation.
+    **typed_kwargs : dict[str, int]
+        Another variadic keyword argument that uses a type hint.
+    """
+    return (
+        arg1,
+        kwargs,
+        custom_args,
+        some_other_strange_name,
+        explicit_typed_args,
+        typed_kwargs,
+    )

format_docstring-0.2.6/tests/test_data/line_wrap/numpy/variadic_signature_without_colon.txt

@@ -0,0 +1,38 @@
+LINE_LENGTH: 55
+
+**********
+Parameters
+----------
+arg1 : str
+    Something short
+**kwargs
+    Keyword args that should remain on their own entry.
+*custom_args
+    Positional extras that should wrap to their own block even without a colon.
+**some_other_strange_name
+    Keyword extras that likewise need wrapping to stay with their entry.
+*explicit_typed_args : tuple[int, ...]
+    Shows a variadic entry that still provides a type annotation.
+**typed_kwargs : dict[str, int]
+    Another variadic keyword argument that uses a type hint.
+
+**********
+
+Parameters
+----------
+arg1 : str
+    Something short
+**kwargs
+    Keyword args that should remain on their own entry.
+*custom_args
+    Positional extras that should wrap to their own
+    block even without a colon.
+**some_other_strange_name
+    Keyword extras that likewise need wrapping to stay
+    with their entry.
+*explicit_typed_args : tuple[int, ...]
+    Shows a variadic entry that still provides a type
+    annotation.
+**typed_kwargs : dict[str, int]
+    Another variadic keyword argument that uses a type
+    hint.

{format_docstring-0.2.4 → format_docstring-0.2.6}/tests/test_docstring_rewriter.py

@@ -4,7 +4,6 @@ from textwrap import dedent
 
 import pytest
 
-import format_docstring.docstring_rewriter
 from format_docstring import docstring_rewriter
 
 
@@ -57,6 +56,57 @@ def test_rebuild_literal(literal: str, content: str, expected: str) -> None:
     assert docstring_rewriter.rebuild_literal(literal, content) == expected
 
 
+@pytest.mark.parametrize(
+    ('segment', 'expected'),
+    [
+        (
+            dedent(
+                """
+                Literal[
+                    'auto', 'default', 'flex', 'scale', 'priority'
+                ]
+                | None
+                | NotGiven
+                """
+            ),
+            "Literal['auto', 'default', 'flex', 'scale', 'priority'] | None | NotGiven",  # noqa: E501
+        ),
+        (
+            dedent(
+                """
+                Optional[
+                    'Widget'
+                ]
+                | None
+                """
+            ),
+            "Optional['Widget'] | None",
+        ),
+        (
+            dedent(
+                """
+                tuple[
+                    dict[str, int],
+                    list[
+                        tuple[str, float]
+                    ]
+                ]
+                """
+            ),
+            'tuple[dict[str, int], list[tuple[str, float]]]',
+        ),
+    ],
+)
+def test_normalize_signature_segment_multiline_cases(
+        segment: str, expected: str
+) -> None:
+    """
+    Multiline annotations should normalize without inserting bracket gaps.
+    """
+    normalized = docstring_rewriter._normalize_signature_segment(segment)  # noqa: SLF001
+    assert normalized == expected
+
+
 @pytest.mark.parametrize(
     ('src', 'selector', 'has_doc'),
     [
@@ -232,9 +282,7 @@ def test_wrap_docstring_numpy_parameters_and_examples() -> None:
         """  # noqa: E501
     ).strip('\n')
 
-    wrapped = format_docstring.docstring_rewriter.wrap_docstring(
-        doc, line_length=79
-    )
+    wrapped = docstring_rewriter.wrap_docstring(doc, line_length=79)
 
     temp: str = 'very very very very very very very very very very'