format-docstring 0.1.0__tar.gz → 0.1.2__tar.gz

format_docstring-0.1.2/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+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.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
+  - A bug where single-line docstrings exceeding length limit aren't handled
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.0...0.1.1
+
+## [0.1.0] - 2025-10-06
+
+- Added
+  - Initial release of format-docstring
+  - Support for NumPy-style docstring formatting
+  - Limited support for Google-style docstrings
+  - CLI tools: `format-docstring` and `format-docstring-jupyter`
+  - Configuration via `pyproject.toml` with `[tool.format_docstring]` section
+  - Options for line length, docstring style, and file exclusion patterns
+  - Pre-commit hooks for Python files and Jupyter notebooks
+  - Comprehensive test suite with pytest
+  - Type checking with mypy
+  - Support for Python 3.10-3.12
+- Full diff
+  - N/A

{format_docstring-0.1.0 → format_docstring-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.1.0
+Version: 0.1.2
 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>
@@ -126,9 +126,9 @@ def example_function(param1, param2, option='default'):
 
     Content following double colons (::) is 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)
 
     Regular bullet lists are also preserved:
 

{format_docstring-0.1.0 → format_docstring-0.1.2}/README.md

@@ -93,9 +93,9 @@ def example_function(param1, param2, option='default'):
 
     Content following double colons (::) is 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)
 
     Regular bullet lists are also preserved:
 

{format_docstring-0.1.0 → format_docstring-0.1.2}/format_docstring/docstring_rewriter.py

@@ -4,7 +4,7 @@ import ast
 
 from format_docstring.line_wrap_google import wrap_docstring_google
 from format_docstring.line_wrap_numpy import (
-    handle_single_line_docstring_that_is_a_bit_too_long,
+    handle_single_line_docstring,
     wrap_docstring_numpy,
 )
 
@@ -168,7 +168,7 @@ def build_replacement_docstring(
 
     new_literal: str | None = rebuild_literal(original_literal, wrapped)
 
-    new_literal = handle_single_line_docstring_that_is_a_bit_too_long(
+    new_literal = handle_single_line_docstring(
         whole_docstring_literal=new_literal,
         docstring_content=wrapped,
         docstring_starting_col=val.col_offset,

{format_docstring-0.1.0 → format_docstring-0.1.2}/format_docstring/line_wrap_numpy.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import re
+import textwrap
 
 from format_docstring.line_wrap_utils import (
     add_leading_indent,
@@ -358,7 +359,7 @@ def _standardize_default_value(line: str) -> str:
     return line
 
 
-def handle_single_line_docstring_that_is_a_bit_too_long(
+def handle_single_line_docstring(
         whole_docstring_literal: str | None,
         docstring_content: str,
         docstring_starting_col: int,
@@ -382,6 +383,18 @@ def handle_single_line_docstring_that_is_a_bit_too_long(
         prefix: str = parts[0]
         postfix: str = parts[-1]
         indent: str = ' ' * num_leading_indent
-        return f'{prefix}\n{indent}{docstring_content}\n{indent}{postfix}'
+
+        # We need to wrap `docstring_content` here because single-line
+        # docstrings don't get wrapped anywhere else.
+        tw: textwrap.TextWrapper = textwrap.TextWrapper(
+            width=line_length - num_leading_indent,
+            break_long_words=False,
+            break_on_hyphens=False,
+            replace_whitespace=False,
+            drop_whitespace=True,
+        )
+        wrapped_list: list[str] = tw.wrap(docstring_content)
+        wrapped: str = textwrap.indent('\n'.join(wrapped_list), indent)
+        return f'{prefix}\n{wrapped}\n{indent}{postfix}'
 
     return whole_docstring_literal

{format_docstring-0.1.0 → format_docstring-0.1.2}/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.0 → format_docstring-0.1.2}/format_docstring.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.1.0
+Version: 0.1.2
 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>
@@ -126,9 +126,9 @@ def example_function(param1, param2, option='default'):
 
     Content following double colons (::) is 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)
 
     Regular bullet lists are also preserved:
 

{format_docstring-0.1.0 → format_docstring-0.1.2}/pyproject.toml

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

{format_docstring-0.1.0 → format_docstring-0.1.2}/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.0 → format_docstring-0.1.2}/tests/test_data/end_to_end/numpy/new_lines_before_and_after.txt

@@ -61,6 +61,12 @@ def func8():
     nf of pf qf rf sf tf uf vf wf xf yf zf 1f 2f 3f 4f 5f 6f 7f 8f 9f 0f af bf cf df ef ff gf hf if jf kf lf mf"""
     pass
 
+
+def func9():
+    def get_scores(self) -> np.ndarray:
+        """Return entire score array, with 'None' for scores that haven't been calculated."""
+        return self.scores
+
 **********
 
 def func1():
@@ -133,3 +139,12 @@ def func8():
     df ef ff gf hf if jf kf lf mf
     """
     pass
+
+
+def func9():
+    def get_scores(self) -> np.ndarray:
+        """
+        Return entire score array, with 'None' for scores that haven't been
+        calculated.
+        """
+        return self.scores

{format_docstring-0.1.0 → format_docstring-0.1.2}/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.0 → format_docstring-0.1.2}/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.0 → format_docstring-0.1.2}/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',
     [

format_docstring-0.1.0/CHANGELOG.md

@@ -1,14 +0,0 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-
-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.0] - 2025-09-07
-
-- Added
-  - Initial release
-- Full diff
-  - N/A