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

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

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

{format_docstring-0.2.3 → format_docstring-0.2.5}/.pre-commit-config.yaml

@@ -1,4 +1,5 @@
 ---
+exclude: ^tests/test_data/
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
@@ -13,7 +14,7 @@ repos:
       - id: check-yaml
       - id: name-tests-test
         args: [--pytest-test-first]
-        exclude: ^tests/test_data/|^tests/helpers\.py$
+        exclude: ^tests/helpers\.py$
       - id: check-merge-conflict
   - repo: https://github.com/jsh9/muff-pre-commit
     rev: 0.13.2
@@ -65,7 +66,7 @@ repos:
     rev: 0.1.0
     hooks:
       - id: markdown-toc-creator
-        exclude: ^tests/test_data/|^AGENTS\.md$|^CHANGELOG\.md$
+        exclude: ^AGENTS\.md$|^CHANGELOG\.md$
   - repo: https://github.com/jsh9/markdown-heading-numbering
     rev: 0.1.0
     hooks:
@@ -79,7 +80,6 @@ repos:
         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
@@ -90,7 +90,6 @@ repos:
         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

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

@@ -6,6 +6,24 @@ 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
+  - A bug where 2nd pair of backticks can't be added for dunder names (such as
+    `__init__`)
+  - A bug where input args named `default` would get treated incorrectly (the
+    tool would confuse it with the default values)
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.2.3...0.2.4
+
 ## [0.2.3] - 2025-10-22
 
 - Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.3
+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.3 → 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
@@ -464,19 +471,39 @@ def _standardize_default_value(line: str) -> str:
     >>> _standardize_default_value('arg : bool, default: True')
     'arg : bool, default=True'
     """
+    colon_idx = line.find(':')
+    if colon_idx == -1:
+        return line
+
+    # `prefix` is everything before the 1st colon (param identifier portion).
+    # We leave `prefix` untouched so arg names like `default` aren't rewritten.
+    prefix = line[: colon_idx + 1]
+    after_colon = line[colon_idx + 1 :]
+
     # Check colon format first to avoid matching colons in space-based pattern
-    match = _DEFAULT_COLON_RE.match(line)
+    match = _DEFAULT_COLON_RE.match(after_colon)
     if match:
-        before = match.group(1).rstrip()
+        before = match.group(1)
+        if before.strip() == '':
+            return line
+
         default_value = match.group(2).strip()
-        return f'{before}, default={default_value}'
+        rebuilt_suffix = f'{before.rstrip()}, default={default_value}'
+        return f'{prefix}{rebuilt_suffix}'
 
     # Try space-separated format with optional "is"
-    match = _DEFAULT_SPACE_RE.match(line)
+    match = _DEFAULT_SPACE_RE.match(after_colon)
     if match:
-        before = match.group(1).rstrip()
+        before = match.group(1)
+        if before.strip() == '':
+            return line
+
+        # ``before`` still contains any annotation text; tightening the spacing
+        # here standardizes the ``", default=..."`` suffix while preserving
+        # whatever appeared to the left.
         default_value = match.group(2).strip()
-        return f'{before}, default={default_value}'
+        rebuilt_suffix = f'{before.rstrip()}, default={default_value}'
+        return f'{prefix}{rebuilt_suffix}'
 
     return line
 
@@ -598,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'}:
@@ -637,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,
@@ -730,12 +801,20 @@ def handle_single_line_docstring(
 # or certain punctuation (like > and . for `>>> ` and `... ` literals)
 # Note: We match [^`]+ (anything except backticks) and then check in the
 # replacement function whether it's an external link (contains < followed by >)
-# The opening backtick must not be immediately followed by _ or __ (to avoid
-# matching the trailing backtick of cross-references like `text`_ or `text`__)
 _RST_BACKTICK_PATTERN = re.compile(
     r'(?:^|(?<=\s)|(?<=\()|(?<=[>.]))(?::[\w-]+:)?`(?!_)([^`]+)`(?!`)(?!__)(?!_)'
 )
 
+# 2nd-stage fixer for ``__dunder__`` names that slipped past the main pattern
+# because the literal starts with an underscore. Negative lookbehinds/aheads
+# ensure we only touch isolated single-backtick literals and leave
+# cross-references (`name`_ / `name`__) alone.
+_DUNDER_LITERAL_PATTERN = re.compile(
+    r'(?<!`)`(__[A-Za-z0-9_]+__)`(?!`)(?!_)(?!__)'
+)
+# Replacement wraps the captured dunder name (group 1) with double backticks.
+_DUNDER_LITERAL_REPLACEMENT = r'``\1``'
+
 
 def _fix_rst_backticks(docstring: str) -> str:
     """
@@ -857,6 +936,11 @@ def _fix_rst_backticks(docstring: str) -> str:
     # Process the entire docstring (with REPL lines protected)
     protected_docstring = ''.join(protected_lines)
     processed = _RST_BACKTICK_PATTERN.sub(replace_func, protected_docstring)
+    # Upgrade remaining single-backtick ``__dunder__`` literals to double
+    # backticks; they are safe literals (not targets or refs) after the guards.
+    processed = _DUNDER_LITERAL_PATTERN.sub(
+        _DUNDER_LITERAL_REPLACEMENT, processed
+    )
 
     # Restore REPL lines
     result_lines = processed.splitlines(keepends=True)

{format_docstring-0.2.3 → 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.3
+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.3 → format_docstring-0.2.5}/format_docstring.egg-info/SOURCES.txt

@@ -39,6 +39,7 @@ tests/test_main_py.py
 tests/test_playground.py
 tests/test_data/playground.py
 tests/test_data/end_to_end/numpy/README.md
+tests/test_data/end_to_end/numpy/arg_name_is_default.txt
 tests/test_data/end_to_end/numpy/colon_spacing_fix.txt
 tests/test_data/end_to_end/numpy/contents_that_are_not_wrapped.txt
 tests/test_data/end_to_end/numpy/default_value_standardization.txt

{format_docstring-0.2.3 → 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.3"
+version = "0.2.5"
 dependencies = [
   "click>=8.0",
   "jupyter-notebook-parser>=0.1.4",

format_docstring-0.2.5/tests/test_data/end_to_end/numpy/arg_name_is_default.txt

@@ -0,0 +1,44 @@
+LINE_LENGTH: 79
+
+**********
+def func1(arg1: str, default: int = 2, _default: str = "value", default_: list[int] | None = None) -> None:
+    """
+    Do something
+
+    Parameters
+    ----------
+    arg1 : str
+        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 very very very very very
+        very very very very very very very
+    default : int
+        Quite quite quite quite quite quite quite quite quite quite quite quite quite quite quite quite
+        quite quite quite quite quite quite quite quite quite quite quite quite quite quite quite quite long
+    _default : str default is "value"
+        Placeholder description for _default parameter.
+    default_ : list[int] | None default None
+        Placeholder description for default_ parameter.
+    """
+    pass
+
+**********
+def func1(arg1: str, default: int = 2, _default: str = "value", default_: list[int] | None = None) -> None:
+    """
+    Do something
+
+    Parameters
+    ----------
+    arg1 : str
+        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 very
+        very very very very very very very very very very very
+    default : int, default=2
+        Quite quite quite quite quite quite quite quite quite quite quite quite
+        quite quite quite quite quite quite quite quite quite quite quite quite
+        quite quite quite quite quite quite quite quite long
+    _default : str, default="value"
+        Placeholder description for _default parameter.
+    default_ : list[int] | None, default=None
+        Placeholder description for default_ parameter.
+    """
+    pass

{format_docstring-0.2.3 → 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

{format_docstring-0.2.3 → format_docstring-0.2.5}/tests/test_line_wrap_numpy.py

@@ -238,6 +238,8 @@ def test_fix_colon_spacing(line: str, expected: str) -> None:
         ('arg : int', 'arg : int'),
         ('arg : str', 'arg : str'),
         ('  arg : bool', '  arg : bool'),
+        ('default : int', 'default : int'),
+        ('    default : int', '    default : int'),
         # Case insensitive "default"
         ('arg : int Default 10', 'arg : int, default=10'),
         ('arg : int DEFAULT 10', 'arg : int, default=10'),
@@ -262,6 +264,14 @@ def test_standardize_default_value(line: str, expected: str) -> None:
             'Underscores inside literal are fine: `foo_bar`.',
             'Underscores inside literal are fine: ``foo_bar``.',
         ),
+        (
+            'Dunder names should be wrapped: `__init__`',
+            'Dunder names should be wrapped: ``__init__``',
+        ),
+        (
+            'Dunder names should be wrapped: `__init123__`',
+            'Dunder names should be wrapped: ``__init123__``',
+        ),
         (
             'Adjacent to parentheses: (`call_me`) and `ok`',
             'Adjacent to parentheses: (``call_me``) and ``ok``',