format-docstring 0.1.7__tar.gz → 0.1.8__tar.gz

{format_docstring-0.1.7 → format_docstring-0.1.8}/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.1.8] - 2025-10-14
+
+- Fixed
+  - Bug in `_fix_rst_backticks()` where backtick pairs spanning multiple lines
+    (e.g., multi-line external links) were incorrectly processed
+  - Added `(?!_)` lookahead to regex pattern to prevent matching trailing
+    backticks from cross-references (e.g., `` `text`_ ``)
+- Changed
+  - Moved backtick fixing from line-by-line processing to whole-docstring
+    processing to correctly handle multi-line constructs
+  - REPL lines (starting with `>>> ` or `... `) are now protected with
+    placeholders during backtick fixing to preserve backticks in Python
+    examples
+- Added
+  - Test cases for multi-line external links in
+    `test_fix_rst_backticks_cases()`
+  - Test cases for REPL lines with backticks in
+    `test_fix_rst_backticks_cases()`
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.7...0.1.8
+
 ## [0.1.7] - 2025-10-14
 
 - Fixed
@@ -13,6 +34,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
     external links (e.g., `` `Python <https://example.org>`_ ``)
   - Refactored `_fix_rst_backticks()` to use pre-compiled regex pattern for
     better performance
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.1.6...0.1.7
 
 ## [0.1.6] - 2025-10-13
 

{format_docstring-0.1.7 → format_docstring-0.1.8}/PKG-INFO

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

@@ -37,6 +37,12 @@ def wrap_docstring_numpy(
     # This helps place the closing quotes on their own indented line later.
     docstring_: str = add_leading_indent(docstring, leading_indent)
 
+    # Apply backtick fixing to the entire docstring first, before line-by-line
+    # processing. This ensures that backtick pairs spanning multiple lines are
+    # handled correctly.
+    if fix_rst_backticks:
+        docstring_ = _fix_rst_backticks(docstring_)
+
     lines: list[str] = docstring_.splitlines()
     if not lines:
         return docstring_
@@ -132,10 +138,7 @@ def wrap_docstring_numpy(
                 continue
 
             # Description lines (typically indented): wrap if too long
-            line_to_process = (
-                _fix_rst_backticks(line) if fix_rst_backticks else line
-            )
-            collect_to_temp_output(temp_out, line_to_process)
+            collect_to_temp_output(temp_out, line)
             i += 1
             continue
 
@@ -152,18 +155,12 @@ def wrap_docstring_numpy(
                 i += 1
                 continue
 
-            line_to_process = (
-                _fix_rst_backticks(line) if fix_rst_backticks else line
-            )
-            collect_to_temp_output(temp_out, line_to_process)
+            collect_to_temp_output(temp_out, line)
             i += 1
             continue
 
         # Examples or any other section
-        line_to_process = (
-            _fix_rst_backticks(line) if fix_rst_backticks else line
-        )
-        collect_to_temp_output(temp_out, line_to_process)
+        collect_to_temp_output(temp_out, line)
         i += 1
 
     out: list[str] = process_temp_output(temp_out, width=line_length)
@@ -422,8 +419,10 @@ 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-]+:)?`([^`]+)`(?!`)(?!__)(?!_)'
+    r'(?:^|(?<=\s)|(?<=\()|(?<=[>.]))(?::[\w-]+:)?`(?!_)([^`]+)`(?!`)(?!__)(?!_)'
 )
 
 
@@ -443,6 +442,7 @@ def _fix_rst_backticks(docstring: str) -> str:
     - Cross-references: `` `text`_ `` and anonymous refs `` `text`__ ``.
     - Inline external links: `` `text <https://example.com>`_ ``.
     - Explicit hyperlink targets: ``.. _`Label`: https://example.com``.
+    - REPL lines: Lines starting with ``>>> `` or ``... `` (Python examples).
 
     How it works (regex guards)
     ---------------------------
@@ -456,6 +456,7 @@ def _fix_rst_backticks(docstring: str) -> str:
     - Closing backtick is not part of ````...```` (``(?!`)``).
     - Closing backtick is not followed by ``__`` or ``_`` (to avoid
       anonymous/named references).
+    - The line does not start with ``>>> `` or ``... `` (Python REPL).
 
     Parameters
     ----------
@@ -489,6 +490,9 @@ def _fix_rst_backticks(docstring: str) -> str:
 
     >>> _fix_rst_backticks('Already has ``foo`` double backticks')
     'Already has ``foo`` double backticks'
+
+    >>> _fix_rst_backticks('>>> `foo` in REPL')
+    '>>> `foo` in REPL'
     """
 
     def replace_func(match: re.Match[str]) -> str:
@@ -516,4 +520,37 @@ def _fix_rst_backticks(docstring: str) -> str:
         prefix = match.group(0)[: match.group(0).index('`')]
         return f'{prefix}``{content}``'
 
-    return _RST_BACKTICK_PATTERN.sub(replace_func, docstring)
+    # Protect REPL lines (>>> and ...) from backtick fixing by temporarily
+    # replacing them with placeholders, then restoring after processing.
+    # This allows multi-line backtick pairs (such as external links spanning
+    # lines) to be handled correctly while still preserving backticks in REPL
+    # comments.
+    lines = docstring.splitlines(keepends=True)
+    repl_lines: dict[int, str] = {}
+    protected_lines: list[str] = []
+
+    for i, line in enumerate(lines):
+        stripped = line.lstrip()
+        # Protect REPL lines (>>> or ...) - don't fix backticks in these
+        if stripped.startswith('>>> ') or stripped.startswith('... '):
+            repl_lines[i] = line
+            # Use a placeholder that won't be matched by the regex
+            protected_lines.append(
+                '\x00REPL_LINE\x00\n'
+                if line.endswith('\n')
+                else '\x00REPL_LINE\x00'
+            )
+        else:
+            protected_lines.append(line)
+
+    # Process the entire docstring (with REPL lines protected)
+    protected_docstring = ''.join(protected_lines)
+    processed = _RST_BACKTICK_PATTERN.sub(replace_func, protected_docstring)
+
+    # Restore REPL lines
+    result_lines = processed.splitlines(keepends=True)
+    for i, original_line in repl_lines.items():
+        if i < len(result_lines):
+            result_lines[i] = original_line
+
+    return ''.join(result_lines)

{format_docstring-0.1.7 → format_docstring-0.1.8}/format_docstring.egg-info/PKG-INFO

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

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

{format_docstring-0.1.7 → format_docstring-0.1.8}/tests/test_data/end_to_end/numpy/fix_rst_backticks.txt

@@ -46,6 +46,10 @@ def process_data(data, config=None):
     `Link`__ should not be modified. External links such as `Python
     <https://www.python.org>`_ must stay as-is.
 
+    Here's another example where long URLs extend to the next line `Here is the
+    Link <https://www.this-is-a-url-that-is-long.com>`_ and `Another One
+    <https://www.this-is-another-url-that-is-long.com>`_.
+
     Examples
     --------
     >>> data = [{'id': 1, 'value': 10}]
@@ -103,14 +107,14 @@ def process_data(data, config=None):
     config : dict, optional
         Configuration dictionary. Valid keys are ``mode``, ``threshold``, and
         ``output_format``. Default is ``None``.
-    processor : `DataProcessor`
+    processor : ``DataProcessor``
         The ``processor`` instance to use for data transformation.
 
     Returns
     -------
     dict
         Processed data with keys ``results``, ``metadata``, and ``status``.
-    `ProcessedData`
+    ``ProcessedData``
         Alternative format with ``data`` and ``errors`` fields.
 
     Raises
@@ -133,6 +137,10 @@ def process_data(data, config=None):
     `Link`__ should not be modified. External links such as `Python
     <https://www.python.org>`_ must stay as-is.
 
+    Here's another example where long URLs extend to the next line `Here is the
+    Link <https://www.this-is-a-url-that-is-long.com>`_ and `Another One
+    <https://www.this-is-another-url-that-is-long.com>`_.
+
     Examples
     --------
     >>> data = [{'id': 1, 'value': 10}]
@@ -159,7 +167,7 @@ class DataProcessor:
         ``'advanced'``.
     pipelines : list
         List of ``Pipeline`` objects to apply.
-    config : `ConfigDict`
+    config : ``ConfigDict``
         Configuration for the ``processor`` with ``settings`` dictionary.
     """
 

{format_docstring-0.1.7 → format_docstring-0.1.8}/tests/test_data/line_wrap/numpy/fix_rst_backticks.txt

@@ -37,6 +37,10 @@ modified, nor should anonymous refs like `Docs`__. External links like `Python
 Explicit targets like shown in the directive ``.. _`Special Target`:
 https://example.com/special`` should not be touched.
 
+Here's another example where long URLs extend to the next line `Here is perhaps
+the Link <https://www.this-is-a-url-that-is-long.com>`_ and `Another One
+<https://www.this-is-another-url-that-is-long.com>`_.
+
 Examples
 --------
 >>> data = [{'id': 1, 'value': 10}]
@@ -55,14 +59,14 @@ arg1 : str
     Use ``method_name`` to access this value.
 arg2 : int
     The value should be between ``1`` and ``100``.
-config : `ConfigType`
+config : ``ConfigType``
     A ``Config`` object for settings.
 
 Returns
 -------
 dict
     A dictionary with keys ``result`` and ``status``.
-`ResultDict`
+``ResultDict``
     An alternative return format with ``data`` field.
 
 See Also
@@ -83,6 +87,10 @@ modified, nor should anonymous refs like `Docs`__. External links like `Python
 Explicit targets like shown in the directive ``.. _`Special Target`:
 https://example.com/special`` should not be touched.
 
+Here's another example where long URLs extend to the next line `Here is perhaps
+the Link <https://www.this-is-a-url-that-is-long.com>`_ and `Another One
+<https://www.this-is-another-url-that-is-long.com>`_.
+
 Examples
 --------
 >>> data = [{'id': 1, 'value': 10}]

{format_docstring-0.1.7 → format_docstring-0.1.8}/tests/test_line_wrap_numpy.py

@@ -293,6 +293,26 @@ def test_standardize_default_value(line: str, expected: str) -> None:
             '.. _`Special Target`: https://example.com/special',
             '.. _`Special Target`: https://example.com/special',
         ),
+        # --- should not fix (multi-line external links) ---
+        (
+            "Here's another example where long URLs"
+            ' extend to the next line `Here is perhaps\n'
+            'the Link <https://www.this-is-a-url-that-is-long.com>`_'
+            ' and `Another One\n'
+            '<https://www.this-is-another-url-that-is-long.com>`_.',
+            "Here's another example where long URLs extend to"
+            ' the next line `Here is perhaps\n'
+            'the Link <https://www.this-is-a-url-that-is-long.com>`_'
+            ' and `Another One\n'
+            '<https://www.this-is-another-url-that-is-long.com>`_.',
+        ),
+        # --- should not fix (REPL lines with backticks) ---
+        (
+            '>>> # Use `config` parameter to customize `mode`\n'
+            '... # and set the `threshold` value',
+            '>>> # Use `config` parameter to customize `mode`\n'
+            '... # and set the `threshold` value',
+        ),
     ],
 )
 def test_fix_rst_backticks_cases(src: str, expected: str) -> None: