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

{format_docstring-0.1.6 → format_docstring-0.1.8}/CHANGELOG.md

@@ -6,6 +6,37 @@ 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
+  - Backtick fixing logic to properly distinguish between inline literals and
+    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
 
 - Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.1.6
+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.6 → 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)
@@ -415,15 +412,51 @@ def handle_single_line_docstring(
     return whole_docstring_literal
 
 
+# Precompiled regex for fixing RST backticks.
+# Pattern matches inline literals while avoiding roles, cross-references, and
+# links. See the documentation of _fix_rst_backticks() for more details.
+# The pattern allows backticks after: start of line, whitespace, parentheses,
+# 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-]+:)?`(?!_)([^`]+)`(?!`)(?!__)(?!_)'
+)
+
+
 def _fix_rst_backticks(docstring: str) -> str:
     """
-    Fix single backticks to double backticks per rST syntax.
-
-    This function converts pairs of single backticks (`) to pairs of double
-    backticks (``). It handles various edge cases:
-    - Preserves existing double backticks
-    - Handles nested backticks
-    - Preserves code blocks and literal blocks
+    Fix inline-literal single backticks to double backticks per rST syntax.
+
+    This function converts pairs of single backticks (`` `...` ``) that
+    represent inline *literals* into pairs of double backticks (`` ``...`` ``).
+    It deliberately **does not** modify other rST constructs that require
+    single backticks.
+
+    What stays untouched
+    --------------------
+    - Existing double-backtick literals: ````code````.
+    - Roles: ``:role:`text``` (e.g., ``:emphasis:`word```).
+    - 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)
+    ---------------------------
+    The pattern only upgrades a match when **all** these are true:
+    - Opening backtick is not part of an existing ````...```` (``(?<!`)``).
+    - Opening backtick is not immediately preceded by ``:`` (to avoid roles).
+    - Opening backtick is not immediately preceded by ``_`` (to avoid
+      explicit targets like ``.. _`Label`: …``).
+    - The enclosed text contains **no** backticks and **no** ``<`` (to avoid
+      inline-link forms like `` `text <url>`_ ``).
+    - 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
     ----------
@@ -433,23 +466,91 @@ def _fix_rst_backticks(docstring: str) -> str:
     Returns
     -------
     str
-        The docstring with single backticks converted to double backticks.
+        The docstring with only inline-literal backticks fixed.
 
     Examples
     --------
     >>> _fix_rst_backticks('Use `foo` to do something')
     'Use ``foo`` to do something'
+
+    >>> _fix_rst_backticks('Edge punctuation: `x`.')
+    'Edge punctuation: ``x``.'
+
+    >>> _fix_rst_backticks(':emphasis:`word`')
+    ':emphasis:`word`'
+
+    >>> _fix_rst_backticks('See `Link`_ for details')
+    'See `Link`_ for details'
+
+    >>> _fix_rst_backticks('`Python <https://www.python.org>`_')
+    '`Python <https://www.python.org>`_'
+
+    >>> _fix_rst_backticks('.. _`Special Target`: https://example.com/special')
+    '.. _`Special Target`: https://example.com/special'
+
     >>> _fix_rst_backticks('Already has ``foo`` double backticks')
     'Already has ``foo`` double backticks'
+
+    >>> _fix_rst_backticks('>>> `foo` in REPL')
+    '>>> `foo` in REPL'
     """
-    # Pattern to match single backticks that are not already part of double
-    # backticks. We look for:
-    # - A backtick not preceded by a backtick: (?<!`)
-    # - Followed by one or more non-backtick characters: ([^`]+)
-    # - Followed by a backtick not followed by another backtick: `(?!`)
-    #
-    # This pattern avoids matching backticks that are already part of ``...``
-    pattern = r'(?<!`)`([^`]+)`(?!`)'
-
-    # Replace single backtick pairs with double backtick pairs
-    return re.sub(pattern, r'``\1``', docstring)
+
+    def replace_func(match: re.Match[str]) -> str:
+        # match.group(0) is the full match
+        # match.group(1) is the content between backticks
+        full_match: str = match.group(0)
+        content: str = match.group(1)
+
+        # If the match includes a role prefix (like :emphasis:), don't replace
+        if ':' in full_match and full_match.index('`') > 0:
+            # Check if there's a role prefix before the backtick
+            before_backtick = full_match[: full_match.index('`')]
+            if ':' in before_backtick:
+                return full_match  # Keep original (it's a role)
+
+        # Check if this is an external link (contains <...> pattern)
+        # External links look like: `text <url>`_
+        if '<' in content and '>' in content:
+            # Check if < comes before > (basic validation)
+            if content.index('<') < content.rindex('>'):
+                return full_match  # Keep original (it's an external link)
+
+        # Otherwise, replace single backticks with double
+        # Keep any leading whitespace/parenthesis/punctuation
+        prefix = match.group(0)[: match.group(0).index('`')]
+        return f'{prefix}``{content}``'
+
+    # 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.6 → 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.6
+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.6 → format_docstring-0.1.8}/pyproject.toml

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

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

@@ -41,6 +41,15 @@ def process_data(data, config=None):
     When `mode` is set to `'advanced'`, additional processing steps are
     applied. The `threshold` parameter controls filtering behavior.
 
+    For rST roles like :emphasis:`important` and :sup:`2`, the single backticks
+    should remain. Cross-references like `Section`_ and anonymous refs like
+    `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}]
@@ -98,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
@@ -123,6 +132,15 @@ def process_data(data, config=None):
     When ``mode`` is set to ``'advanced'``, additional processing steps are
     applied. The ``threshold`` parameter controls filtering behavior.
 
+    For rST roles like :emphasis:`important` and :sup:`2`, the single backticks
+    should remain. Cross-references like `Section`_ and anonymous refs like
+    `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}]
@@ -149,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.6 → format_docstring-0.1.8}/tests/test_data/line_wrap/numpy/fix_rst_backticks.txt

@@ -29,6 +29,18 @@ Notes
 When using `special_value`, ensure that `config` is set properly. The
 `default_value` is `None` by default.
 
+This section also contains rST roles like :emphasis:`word` and :strong:`bold`
+that should remain unchanged. Cross-references like `Section`_ should not be
+modified, nor should anonymous refs like `Docs`__. External links like `Python
+<https://www.python.org>`_ must also stay as-is.
+
+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}]
@@ -47,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
@@ -67,6 +79,18 @@ Notes
 When using ``special_value``, ensure that ``config`` is set properly. The
 ``default_value`` is ``None`` by default.
 
+This section also contains rST roles like :emphasis:`word` and :strong:`bold`
+that should remain unchanged. Cross-references like `Section`_ should not be
+modified, nor should anonymous refs like `Docs`__. External links like `Python
+<https://www.python.org>`_ must also stay as-is.
+
+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.6 → format_docstring-0.1.8}/tests/test_line_wrap_numpy.py

@@ -5,6 +5,7 @@ import pytest
 from format_docstring.docstring_rewriter import wrap_docstring
 from format_docstring.line_wrap_numpy import (
     _fix_colon_spacing,
+    _fix_rst_backticks,
     _get_section_heading_title,
     _is_hyphen_underline,
     _is_param_signature,
@@ -243,6 +244,81 @@ def test_standardize_default_value(line: str, expected: str) -> None:
     assert _standardize_default_value(line) == expected
 
 
+@pytest.mark.parametrize(
+    'src, expected',
+    [
+        # --- should fix (inline literals) ---
+        ('Use `foo` to do something', 'Use ``foo`` to do something'),
+        ('Edge punctuation: `x`.', 'Edge punctuation: ``x``.'),
+        (
+            'Multiple inline literals: `a` and `b`.',
+            'Multiple inline literals: ``a`` and ``b``.',
+        ),
+        (
+            'Underscores inside literal are fine: `foo_bar`.',
+            'Underscores inside literal are fine: ``foo_bar``.',
+        ),
+        (
+            'Adjacent to parentheses: (`call_me`) and `ok`',
+            'Adjacent to parentheses: (``call_me``) and ``ok``',
+        ),
+        # Edge cases: literals that contain special characters -> should fix
+        ('`>>> `', '``>>> ``'),
+        ('`... `', '``... ``'),
+        # --- should not fix (roles) ---
+        (':emphasis:`word`', ':emphasis:`word`'),
+        (':strong:`bold`', ':strong:`bold`'),
+        (':sup:`2`', ':sup:`2`'),
+        (
+            ':title-reference:`The Great Book`',
+            ':title-reference:`The Great Book`',
+        ),
+        # --- should not fix (cross-references & links) ---
+        ('See `Section`_ for details', 'See `Section`_ for details'),
+        (
+            'See `Docs`__ for the anonymous reference',
+            'See `Docs`__ for the anonymous reference',
+        ),
+        (
+            '`Python <https://www.python.org>`_',
+            '`Python <https://www.python.org>`_',
+        ),
+        # --- should not fix (already correct literals) ---
+        (
+            'Already has ``double`` backticks',
+            'Already has ``double`` backticks',
+        ),
+        # --- should not fix (explicit hyperlink target) ---
+        (
+            '.. _`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:
+    assert _fix_rst_backticks(src) == expected
+
+
 @pytest.mark.parametrize(
     'fix_rst_backticks, input_docstring, expected_docstring',
     [
@@ -258,10 +334,10 @@ def test_standardize_default_value(line: str, expected: str) -> None:
         ),
     ],
 )
-def test_fix_rst_backticks(
+def test_fix_rst_backticks_option_on_and_off(
         fix_rst_backticks: bool, input_docstring: str, expected_docstring: str
 ) -> None:
-    """Test that backticks are fixed or preserved based on fix_rst_backticks"""
+    """Verify the `fix_rst_backticks` option can be correctly turned on/off"""
     result = wrap_docstring(
         input_docstring,
         line_length=79,