format-docstring 0.1.1__tar.gz → 0.1.3__tar.gz

{format_docstring-0.1.1 → format_docstring-0.1.3}/.pre-commit-config.yaml

@@ -37,6 +37,6 @@ repos:
         args: [--wrap, '79', --number]
         additional_dependencies: [mdformat-tables]
   - repo: https://github.com/jsh9/markdown-toc-creator
-    rev: 0.0.10
+    rev: 0.0.11
     hooks:
       - id: markdown-toc-creator

{format_docstring-0.1.1 → format_docstring-0.1.3}/CHANGELOG.md

@@ -6,6 +6,20 @@ 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.1.3] - 2025-10-12
+
+- Fixed
+  - A bug in counting line length for single-line docstrings
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.2...0.1.3
+
+## [0.1.2] - 2025-10-08
+
+- Added
+  - Support for 1 blank line after `::`
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.1...0.1.2
+
 ## [0.1.1] - 2025-10-06
 
 - Fixed

{format_docstring-0.1.1 → format_docstring-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.1.1
+Version: 0.1.3
 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>
@@ -109,7 +109,8 @@ def example_function(param1, param2, option='default'):
 
     Examples
     --------
-    Code examples with >>> prompts are preserved without wrapping:
+    Within the "Examples" section, code with >>> prompts are preserved without
+    wrapping:
 
     >>> result = example_function('test', 42, option='custom_value_with_a_very_long_name_that_exceeds_line_length')
     >>> print(result)
@@ -124,11 +125,16 @@ def example_function(param1, param2, option='default'):
     Params       Yes                 Signature lines preserved
     ===========  ==================  ===============================
 
-    Content following double colons (::) is preserved::
+    Contents following double colons (`::`) are preserved::
 
-        - This indented block after :: is not wrapped
-        - Even if lines are very long they stay intact
-        - Useful for code blocks or literal content
+                  P(B|A) P(A)
+        P(A|B) = -------------
+                      P(B)
+
+    Even if there isn't an extra blank line after `::`, the contents are still
+    preserved::
+            _______
+       σ = √ Var(X)
 
     Regular bullet lists are also preserved:
 

{format_docstring-0.1.1 → format_docstring-0.1.3}/README.md

@@ -76,7 +76,8 @@ def example_function(param1, param2, option='default'):
 
     Examples
     --------
-    Code examples with >>> prompts are preserved without wrapping:
+    Within the "Examples" section, code with >>> prompts are preserved without
+    wrapping:
 
     >>> result = example_function('test', 42, option='custom_value_with_a_very_long_name_that_exceeds_line_length')
     >>> print(result)
@@ -91,11 +92,16 @@ def example_function(param1, param2, option='default'):
     Params       Yes                 Signature lines preserved
     ===========  ==================  ===============================
 
-    Content following double colons (::) is preserved::
+    Contents following double colons (`::`) are preserved::
 
-        - This indented block after :: is not wrapped
-        - Even if lines are very long they stay intact
-        - Useful for code blocks or literal content
+                  P(B|A) P(A)
+        P(A|B) = -------------
+                      P(B)
+
+    Even if there isn't an extra blank line after `::`, the contents are still
+    preserved::
+            _______
+       σ = √ Var(X)
 
     Regular bullet lists are also preserved:
 

{format_docstring-0.1.1 → format_docstring-0.1.3}/format_docstring/line_wrap_numpy.py

@@ -377,7 +377,7 @@ def handle_single_line_docstring(
     if '\n' in whole_docstring_literal:  # multi-line: do not handle
         return whole_docstring_literal
 
-    if docstring_ending_col >= line_length:  # whole docstring exceeds limit
+    if docstring_ending_col > line_length:  # whole docstring exceeds limit
         num_leading_indent: int = docstring_starting_col
         parts: list[str] = whole_docstring_literal.split(docstring_content)
         prefix: str = parts[0]

{format_docstring-0.1.1 → format_docstring-0.1.3}/format_docstring/line_wrap_utils.py

@@ -66,14 +66,79 @@ def process_temp_output(
         temp_out: list[str | list[str]],
         width: int,
 ) -> list[str]:
-    """Wrap the `list[str]` elements in `temp_out`."""
+    """
+    Wrap the `list[str]` elements in `temp_out`.
+
+    To preserve literal blocks indicated by ``::``, the function first scans
+    ``temp_out`` for the pattern ``<line ending with '::'>``, followed by
+    ``''`` (exactly 1 empty line), followed by non-empty content. When found,
+    those three entries are merged into
+    a single ``list[str]`` so the literal block (including the separating blank
+    line) is wrapped as one unit.
+    """
+
+    def _to_list(element: str | list[str]) -> list[str]:
+        return [element] if isinstance(element, str) else list(element)
+
+    def _ends_with_literal_block_marker(element: str | list[str]) -> bool:
+        if isinstance(element, str):
+            return element.endswith('::')
+
+        if not element:
+            return False
+
+        return element[-1].endswith('::')
+
+    def _is_empty_string(element: str | list[str]) -> bool:
+        return isinstance(element, str) and element == ''
+
+    def _has_content(element: str | list[str]) -> bool:
+        if isinstance(element, str):
+            return element != ''
+
+        return any(line != '' for line in element)
+
+    merged_temp_out: list[str | list[str]] = []
+    idx = 0
+    while idx < len(temp_out):
+        current = temp_out[idx]
+        next_idx = idx + 1
+        next_next_idx = idx + 2
+
+        if (
+            _ends_with_literal_block_marker(current)
+            and next_next_idx < len(temp_out)
+            and _is_empty_string(temp_out[next_idx])
+            and _has_content(temp_out[next_next_idx])
+        ):
+            merged_element: list[str] = []
+            merged_element.extend(_to_list(current))
+            merged_element.extend(_to_list(temp_out[next_idx]))
+            merged_element.extend(_to_list(temp_out[next_next_idx]))
+            merged_temp_out.append(merged_element)
+            idx += 3
+            continue
+
+        merged_temp_out.append(current)
+        idx += 1
+
     out: list[str] = []
 
-    for element in temp_out:
+    for element in merged_temp_out:
         if isinstance(element, str):
             out.append(element)
         elif isinstance(element, list):
             wrapped: list[str] = wrap_preserving_indent(element, width)
+            if (
+                '' in element
+                and '' not in wrapped
+                and element.index('') < len(element) - 1
+            ):
+                insertion_idx = min(element.index(''), len(wrapped))
+                wrapped = (
+                    wrapped[:insertion_idx] + [''] + wrapped[insertion_idx:]
+                )
+
             out.extend(wrapped)
         else:
             raise RuntimeError("Something's wrong. Please contact the author.")
@@ -185,7 +250,31 @@ def _wrap_text_segment(lines: list[str], width: int) -> list[str]:
     if result and result[-1] == '':
         result.pop()
 
-    return result if result else lines
+    result_: list[str] = result if result else lines
+
+    return _add_back_leading_or_trailing_newline(
+        original_lines=lines,
+        wrapped_lines=result_,
+    )
+
+
+def _add_back_leading_or_trailing_newline(
+        original_lines: list[str],
+        wrapped_lines: list[str],
+) -> list[str]:
+    if len(original_lines) == 0 or len(wrapped_lines) == 0:
+        return wrapped_lines
+
+    new_result: list[str] = []
+    if original_lines[0] == '':
+        new_result = [''] + wrapped_lines
+    else:
+        new_result = wrapped_lines
+
+    if original_lines[-1] == '':
+        return new_result + ['']
+
+    return new_result
 
 
 def merge_lines_and_strip(text: str) -> str:

{format_docstring-0.1.1 → format_docstring-0.1.3}/format_docstring.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.1.1
+Version: 0.1.3
 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>
@@ -109,7 +109,8 @@ def example_function(param1, param2, option='default'):
 
     Examples
     --------
-    Code examples with >>> prompts are preserved without wrapping:
+    Within the "Examples" section, code with >>> prompts are preserved without
+    wrapping:
 
     >>> result = example_function('test', 42, option='custom_value_with_a_very_long_name_that_exceeds_line_length')
     >>> print(result)
@@ -124,11 +125,16 @@ def example_function(param1, param2, option='default'):
     Params       Yes                 Signature lines preserved
     ===========  ==================  ===============================
 
-    Content following double colons (::) is preserved::
+    Contents following double colons (`::`) are preserved::
 
-        - This indented block after :: is not wrapped
-        - Even if lines are very long they stay intact
-        - Useful for code blocks or literal content
+                  P(B|A) P(A)
+        P(A|B) = -------------
+                      P(B)
+
+    Even if there isn't an extra blank line after `::`, the contents are still
+    preserved::
+            _______
+       σ = √ Var(X)
 
     Regular bullet lists are also preserved:
 

{format_docstring-0.1.1 → format_docstring-0.1.3}/pyproject.toml

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

{format_docstring-0.1.1 → format_docstring-0.1.3}/tests/test_data/end_to_end/numpy/contents_that_are_not_wrapped.txt

@@ -7,6 +7,7 @@ def func1():
         def func3():
             """
             Below is a formula that should not be wrapped. Here are some more contents that are arbitrary just to make the line length quite long so that we can test how it can be wrapped. This paragraph would end with two colons to signal that the contents below should not be wrapped::
+
                                     x^alpha * beta
                     y(x) = --------------------------------
                                 1       gamma^a * tau
@@ -59,6 +60,7 @@ def func1():
             so that we can test how it can be wrapped. This paragraph would end
             with two colons to signal that the contents below should not be
             wrapped::
+
                                     x^alpha * beta
                     y(x) = --------------------------------
                                 1       gamma^a * tau

{format_docstring-0.1.1 → format_docstring-0.1.3}/tests/test_data/end_to_end/numpy/single_line_docstring.txt

@@ -25,6 +25,16 @@ def func3():
                     """
                     pass
 
+
+def func4():
+    """This line has the right number of chars that it does not exceed limit"""
+    pass
+
+
+def func5():
+    r"""This line has the right number of chars that it exceeds limit by 1..."""
+    pass
+
 **********
 def func1():
     """
@@ -53,3 +63,15 @@ def func3():
                     This line is already formatted so we should not re-wrap it.
                     """
                     pass
+
+
+def func4():
+    """This line has the right number of chars that it does not exceed limit"""
+    pass
+
+
+def func5():
+    r"""
+    This line has the right number of chars that it exceeds limit by 1...
+    """
+    pass

{format_docstring-0.1.1 → format_docstring-0.1.3}/tests/test_data/line_wrap/numpy/contents_that_are_not_wrapped.txt

@@ -3,6 +3,7 @@ LINE_LENGTH: 79
 **********
 
 Below is a formula that should not be wrapped. Here are some more contents that are arbitrary just to make the line length quite long so that we can test how it can be wrapped. This paragraph would end with two colons to signal that the contents below should not be wrapped::
+
                         x^alpha * beta
         y(x) = --------------------------------
                       1       gamma^a * tau
@@ -48,6 +49,7 @@ Below is a formula that should not be wrapped. Here are some more contents that
 are arbitrary just to make the line length quite long so that we can test how
 it can be wrapped. This paragraph would end with two colons to signal that the
 contents below should not be wrapped::
+
                         x^alpha * beta
         y(x) = --------------------------------
                       1       gamma^a * tau

{format_docstring-0.1.1 → format_docstring-0.1.3}/tests/test_line_wrap_numpy.py

@@ -35,7 +35,7 @@ def test_wrap_docstring_single_case() -> None:
     the test case file that's producing errors.
     """
     filename, length, before, after = load_case_from_file(
-        DATA_DIR / 'mismatched_underlines_two_dashes.txt'
+        DATA_DIR / 'contents_that_are_not_wrapped.txt'
     )
     out = wrap_docstring(before, line_length=length, docstring_style='numpy')
     assert out.strip('\n') == after.strip('\n')

{format_docstring-0.1.1 → format_docstring-0.1.3}/tests/test_line_wrap_utils.py

@@ -9,6 +9,7 @@ from format_docstring.line_wrap_utils import (
     is_bulleted_list,
     is_rST_table,
     merge_lines_and_strip,
+    process_temp_output,
     segment_lines_by_wrappability,
     wrap_preserving_indent,
 )
@@ -125,7 +126,7 @@ from format_docstring.line_wrap_utils import (
         # Test with rST table (should be preserved)
         (
             [
-                'Here is some text that should wrap.',
+                'Here is some text that should wrap. 1.',
                 '',
                 '+------+-----+',
                 '| Name | Age |',
@@ -138,12 +139,14 @@ from format_docstring.line_wrap_utils import (
             20,
             [
                 'Here is some text',
-                'that should wrap.',
+                'that should wrap. 1.',
+                '',
                 '+------+-----+',
                 '| Name | Age |',
                 '+------+-----+',
                 '| John | 25  |',
                 '+------+-----+',
+                '',
                 'More text that',
                 'should wrap.',
             ],
@@ -151,7 +154,7 @@ from format_docstring.line_wrap_utils import (
         # Test with bulleted list (should be preserved)
         (
             [
-                'This is a very long line of text that should be wrapped.',
+                'This is a very long line of text that should be wrapped. 2',
                 '',
                 '- First list item that is quite long',
                 '- Second list item that is also long',
@@ -162,9 +165,11 @@ from format_docstring.line_wrap_utils import (
             [
                 'This is a very long line',
                 'of text that should be',
-                'wrapped.',
+                'wrapped. 2',
+                '',
                 '- First list item that is quite long',
                 '- Second list item that is also long',
+                '',
                 'Another long line that',
                 'should be wrapped.',
             ],
@@ -218,6 +223,103 @@ def test_finalize_lines(
     assert finalize_lines(lines, leading_indent) == expected
 
 
+@pytest.mark.parametrize(
+    'temp_out,width,expected',
+    [
+        (
+            [
+                'Examples::',
+                '',
+                ['    code line 1', '    code line 2'],
+            ],
+            20,
+            [
+                'Examples::',
+                '',
+                '    code line 1',
+                '    code line 2',
+            ],
+        ),
+        (
+            [
+                'Examples::',
+                '',
+                [
+                    '    literal block with long text that should remain'
+                    ' on one line even though width is short'
+                ],
+            ],
+            30,
+            [
+                'Examples::',
+                '',
+                (
+                    '    literal block with long text that should remain'
+                    ' on one line even though width is short'
+                ),
+            ],
+        ),
+        (
+            [
+                'Examples::',
+                '',
+                '',  # 2 empty lines: not protected by `::` above -> will wrap
+                [
+                    (
+                        '    literal block with long text that should remain'
+                        ' on one line even though width is short'
+                    )
+                ],
+            ],
+            30,
+            [
+                'Examples::',
+                '',
+                '',
+                '    literal block with long',
+                '    text that should remain on',
+                '    one line even though width',
+                '    is short',
+            ],
+        ),
+        (
+            [
+                'Examples::',
+                'no blank separator',
+                ['    code line 1', '    code line 2'],
+            ],
+            40,
+            [
+                'Examples::',
+                'no blank separator',
+                '    code line 1 code line 2',
+            ],
+        ),
+        (
+            [
+                'Examples::',
+                '',
+                '',
+                'Trailing text',
+            ],
+            25,
+            [
+                'Examples::',
+                '',
+                '',
+                'Trailing text',
+            ],
+        ),
+    ],
+)
+def test_process_temp_output_merges_literal_block(
+        temp_out: list[str | list[str]],
+        width: int,
+        expected: list[str],
+) -> None:
+    assert process_temp_output(temp_out, width) == expected
+
+
 @pytest.mark.parametrize(
     'text,expected',
     [