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

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

@@ -6,6 +6,14 @@ 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.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
+
 ## [0.1.6] - 2025-10-13
 
 - Added

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

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

@@ -415,15 +415,47 @@ 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 >)
+_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``.
+
+    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).
 
     Parameters
     ----------
@@ -433,23 +465,55 @@ 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'
     """
-    # 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}``'
+
+    return _RST_BACKTICK_PATTERN.sub(replace_func, docstring)

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

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

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

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

@@ -41,6 +41,11 @@ 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.
+
     Examples
     --------
     >>> data = [{'id': 1, 'value': 10}]
@@ -123,6 +128,11 @@ 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.
+
     Examples
     --------
     >>> data = [{'id': 1, 'value': 10}]

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

@@ -29,6 +29,14 @@ 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.
+
 Examples
 --------
 >>> data = [{'id': 1, 'value': 10}]
@@ -67,6 +75,14 @@ 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.
+
 Examples
 --------
 >>> data = [{'id': 1, 'value': 10}]

{format_docstring-0.1.6 → format_docstring-0.1.7}/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,61 @@ 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',
+        ),
+    ],
+)
+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 +314,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,