format-docstring 0.2.2__tar.gz → 0.2.4__tar.gz

{format_docstring-0.2.2 → format_docstring-0.2.4}/.pre-commit-config.yaml

@@ -1,4 +1,5 @@
 ---
+exclude: ^tests/test_data/
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
@@ -6,23 +7,15 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
         exclude: \.json$|\.ipynb$
-      - id: debug-statements
-      - id: double-quote-string-fixer
       - id: requirements-txt-fixer
-        exclude: \.ipynb$
       - id: check-added-large-files
         args: [--maxkb=1000]
       - id: check-toml
       - id: check-yaml
       - id: name-tests-test
         args: [--pytest-test-first]
-        exclude: ^tests/test_data/|^tests/helpers\.py$
+        exclude: ^tests/helpers\.py$
       - id: check-merge-conflict
-  - repo: https://github.com/asottile/pyupgrade
-    rev: v3.20.0
-    hooks:
-      - id: pyupgrade
-        args: [--py310-plus]
   - repo: https://github.com/jsh9/muff-pre-commit
     rev: 0.13.2
     hooks:
@@ -37,11 +30,27 @@ repos:
     rev: 1.18.0
     hooks:
       - id: yamlfix
+  - repo: https://github.com/pappasam/toml-sort
+    rev: v0.24.2
+    hooks:
+      - id: toml-sort-fix
+        args:
+          - --in-place
+          - --sort-table-keys
+          - --sort-inline-tables
+          - --sort-first=name,version,dependencies,requires-python,authors,maintainers
+          - --trailing-comma-inline-array
+          - --sort-inline-arrays
+  - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
+    rev: v2.15.0
+    hooks:
+      - id: pretty-format-ini
+        args: [--autofix]
   - repo: https://github.com/hukkin/mdformat
     rev: 1.0.0
     hooks:
       - id: mdformat
-        args: [--wrap, '79', --number]
+        args: [--wrap=79, --number]
         additional_dependencies: [mdformat-gfm]
   - repo: https://github.com/jsh9/format-json
     rev: 0.1.2
@@ -54,9 +63,10 @@ repos:
           - --no-sort-keys
           - --no-eof-newline
   - repo: https://github.com/jsh9/markdown-toc-creator
-    rev: 0.0.11
+    rev: 0.1.0
     hooks:
       - id: markdown-toc-creator
+        exclude: ^AGENTS\.md$|^CHANGELOG\.md$
   - repo: https://github.com/jsh9/markdown-heading-numbering
     rev: 0.1.0
     hooks:
@@ -70,7 +80,6 @@ repos:
         args: [-m, format_docstring.main_py, --verbose, diff]
         language: python
         types: [python]
-        exclude: ^tests/test_data/
         additional_dependencies:
           - click>=8.0
           - jupyter-notebook-parser>=0.1.4
@@ -81,7 +90,6 @@ repos:
         args: [-m, format_docstring.main_jupyter, --verbose, diff]
         language: python
         files: ^.*\.ipynb$
-        exclude: ^tests/test_data/
         additional_dependencies:
           - click>=8.0
           - jupyter-notebook-parser>=0.1.4

{format_docstring-0.2.2 → format_docstring-0.2.4}/CHANGELOG.md

@@ -6,7 +6,29 @@ 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.2.2] - 2024-10-20
+## [0.2.4] - 2025-10-27
+
+- Fixed
+  - A bug where 2nd pair of backticks can't be added for dunder names (such as
+    `__init__`)
+  - A bug where input args named `default` would get treated incorrectly (the
+    tool would confuse it with the default values)
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.2.3...0.2.4
+
+## [0.2.3] - 2025-10-22
+
+- Added
+  - A lot more linters
+  - Formatters for TOML and INI config files
+- Changed
+  - A lot of code changes to pass the linter checks
+- Removed
+  - Unnecessary pre-commit hooks
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.2.2...0.2.3
+
+## [0.2.2] - 2025-10-20
 
 - Added
   - Formatting support for type hints and default values in class docstrings

{format_docstring-0.2.2 → format_docstring-0.2.4}/PKG-INFO

@@ -1,32 +1,32 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.2
+Version: 0.2.4
 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>
 License: MIT
 Project-URL: Homepage, https://github.com/your/repo
-Project-URL: Repository, https://github.com/your/repo.git
 Project-URL: Issues, https://github.com/your/repo/issues
-Keywords: formatter,code-style,docstring,python
+Project-URL: Repository, https://github.com/your/repo.git
+Keywords: code-style,docstring,formatter,python
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: jupyter-notebook-parser>=0.1.4
 Requires-Dist: click>=8.0
+Requires-Dist: jupyter-notebook-parser>=0.1.4
 Requires-Dist: tomli>=1.1.0; python_version < "3.11"
 Dynamic: license-file
 
@@ -34,11 +34,11 @@ Dynamic: license-file
 
 A Python formatter to automatically format numpy-style docstrings.
 
-______________________________________________________________________
+<!--TOC-->
 
-**Table of Contents:**
+______________________________________________________________________
 
-<!--TOC-->
+**Table of Contents**
 
 - [1. Overview](#1-overview)
 - [2. Before vs After Examples](#2-before-vs-after-examples)
@@ -59,10 +59,10 @@ ______________________________________________________________________
   - [5.3. `pyproject.toml` Configuration](#53-pyprojecttoml-configuration)
 - [6. Caveat](#6-caveat)
 
-<!--TOC-->
-
 ______________________________________________________________________
 
+<!--TOC-->
+
 ## 1. Overview
 
 `format-docstring` is a tool that automatically formats and wraps docstring

{format_docstring-0.2.2 → format_docstring-0.2.4}/README.md

@@ -2,11 +2,11 @@
 
 A Python formatter to automatically format numpy-style docstrings.
 
-______________________________________________________________________
+<!--TOC-->
 
-**Table of Contents:**
+______________________________________________________________________
 
-<!--TOC-->
+**Table of Contents**
 
 - [1. Overview](#1-overview)
 - [2. Before vs After Examples](#2-before-vs-after-examples)
@@ -27,10 +27,10 @@ ______________________________________________________________________
   - [5.3. `pyproject.toml` Configuration](#53-pyprojecttoml-configuration)
 - [6. Caveat](#6-caveat)
 
-<!--TOC-->
-
 ______________________________________________________________________
 
+<!--TOC-->
+
 ## 1. Overview
 
 `format-docstring` is a tool that automatically formats and wraps docstring

{format_docstring-0.2.2 → format_docstring-0.2.4}/format_docstring/base_fixer.py

@@ -42,7 +42,7 @@ class BaseFixer:
             if not should_exclude_file(f, self.exclude_pattern)
         ]
 
-    def _print_diff(self, filename: str, before: str, after: str) -> None:
+    def print_diff(self, filename: str, before: str, after: str) -> None:
         """Print a unified diff when verbose mode is enabled."""
         if self.verbose != 'diff':
             return

{format_docstring-0.2.2 → format_docstring-0.2.4}/format_docstring/config.py

@@ -4,9 +4,10 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-import click
+if TYPE_CHECKING:
+    import click
 
 if sys.version_info >= (3, 11):
     import tomllib
@@ -132,7 +133,7 @@ def load_config_from_file(config_file: Path) -> dict[str, Any]:
         return {}
 
     try:
-        with open(config_file, 'rb') as fp:
+        with Path(config_file).open('rb') as fp:
             raw_config = tomllib.load(fp)
 
         # Extract [tool.format_docstring] section
@@ -144,7 +145,7 @@ def load_config_from_file(config_file: Path) -> dict[str, Any]:
         return {
             k.replace('-', '_'): v for k, v in format_docstring_section.items()
         }
-    except Exception:
+    except Exception:  # noqa: BLE001
         # If there's any error reading/parsing the file, return empty config
         return {}
 

{format_docstring-0.2.2 → format_docstring-0.2.4}/format_docstring/docstring_rewriter.py

@@ -2,14 +2,18 @@ from __future__ import annotations
 
 import ast
 import io
+import operator
 import tokenize
+from typing import TYPE_CHECKING
 
 from format_docstring.line_wrap_google import wrap_docstring_google
 from format_docstring.line_wrap_numpy import (
     handle_single_line_docstring,
     wrap_docstring_numpy,
 )
-from format_docstring.line_wrap_utils import ParameterMetadata
+
+if TYPE_CHECKING:
+    from format_docstring.line_wrap_utils import ParameterMetadata
 
 ModuleClassOrFunc = (
     ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef
@@ -91,11 +95,13 @@ def _normalize_signature_segment(segment: str | None) -> str | None:
         # iterator order mirrors the unparse traversal so we can reapply them.
         original_strings: list[str] = []
         try:
-            for tok in tokenize.generate_tokens(
-                io.StringIO(normalized).readline
-            ):
-                if tok.type == tokenize.STRING:
-                    original_strings.append(tok.string)
+            original_strings.extend(
+                tok.string
+                for tok in tokenize.generate_tokens(
+                    io.StringIO(normalized).readline
+                )
+                if tok.type == tokenize.STRING
+            )
         except tokenize.TokenError:
             original_strings = []
 
@@ -105,6 +111,7 @@ def _normalize_signature_segment(segment: str | None) -> str | None:
             for tok in tokenize.generate_tokens(
                 io.StringIO(canonical).readline
             ):
+                current_tok: tokenize.TokenInfo = tok
                 if tok.type == tokenize.STRING:
                     replacement = next(string_iter, None)
                     if replacement is not None:
@@ -116,12 +123,12 @@ def _normalize_signature_segment(segment: str | None) -> str | None:
                             if ast.literal_eval(
                                 replacement
                             ) == ast.literal_eval(tok.string):
-                                tok = tok._replace(string=replacement)
-                        except Exception:
+                                current_tok = tok._replace(string=replacement)
+                        except Exception:  # noqa: BLE001
                             pass
 
-                rebuilt_tokens.append(tok)
-                if tok.type == tokenize.ENDMARKER:
+                rebuilt_tokens.append(current_tok)
+                if current_tok.type == tokenize.ENDMARKER:
                     break
 
             # Untokenize the rebuilt stream while trimming the leading/trailing
@@ -305,16 +312,17 @@ def fix_src(
     tree: ast.Module = ast.parse(source_code, type_comments=True)
     line_starts: list[int] = calc_line_starts(source_code)
 
+    # Store (start, end, replacement text) tuples
     replacements: list[tuple[int, int, str]] = []
 
     # Module-level docstring
     replacement = build_replacement_docstring(
         tree,
-        source_code,
-        line_starts,
-        line_length,
-        docstring_style,
-        fix_rst_backticks,
+        source_code=source_code,
+        line_starts=line_starts,
+        line_length=line_length,
+        docstring_style=docstring_style,
+        fix_rst_backticks=fix_rst_backticks,
     )
     if replacement is not None:
         replacements.append(replacement)
@@ -326,11 +334,11 @@ def fix_src(
         ):
             replacement = build_replacement_docstring(
                 node,
-                source_code,
-                line_starts,
-                line_length,
-                docstring_style,
-                fix_rst_backticks,
+                source_code=source_code,
+                line_starts=line_starts,
+                line_length=line_length,
+                docstring_style=docstring_style,
+                fix_rst_backticks=fix_rst_backticks,
             )
             if replacement is not None:
                 replacements.append(replacement)
@@ -339,7 +347,8 @@ def fix_src(
     if not replacements:
         return source_code
 
-    replacements.sort(key=lambda x: x[0], reverse=True)
+    # Sort by starting index descending
+    replacements.sort(key=operator.itemgetter(0), reverse=True)
     new_src = source_code
     for start, end, text in replacements:
         new_src = new_src[:start] + text + new_src[end:]
@@ -371,6 +380,7 @@ def calc_line_starts(source_code: str) -> list[int]:
 
 def build_replacement_docstring(
         node: ModuleClassOrFunc,
+        *,
         source_code: str,
         line_starts: list[int],
         line_length: int,
@@ -411,7 +421,7 @@ def build_replacement_docstring(
         return None
 
     start: int = calc_abs_pos(line_starts, val.lineno, val.col_offset)
-    end: int = calc_abs_pos(line_starts, val.end_lineno, val.end_col_offset)  # type: ignore[arg-type]  # noqa: LN002
+    end: int = calc_abs_pos(line_starts, val.end_lineno, val.end_col_offset)  # type: ignore[arg-type]
     original_literal = source_code[start:end]
 
     if _has_inline_no_format_comment(source_code, end):
@@ -554,10 +564,10 @@ def rebuild_literal(original_literal: str, content: str) -> str | None:
     prefix = original_literal[:i]
 
     delim = ''
-    if original_literal[i : i + 3] in ('"""', "'''"):
+    if original_literal[i : i + 3] in {'"""', "'''"}:
         delim = original_literal[i : i + 3]
         i += 3
-    elif i < n and original_literal[i] in ('"', "'"):
+    elif i < n and original_literal[i] in {'"', "'"}:
         delim = original_literal[i]
         i += 1
     else:
@@ -576,6 +586,7 @@ def wrap_docstring(
         line_length: int = 79,
         docstring_style: str = 'numpy',
         leading_indent: int = 0,
+        *,
         fix_rst_backticks: bool = True,
         function_param_metadata: ParameterMetadata | None = None,
         function_return_annotation: str | None = None,
@@ -622,7 +633,7 @@ def wrap_docstring(
     if style == 'google':
         return wrap_docstring_google(
             docstring,
-            line_length,
+            line_length=line_length,
             leading_indent=leading_indent,
             fix_rst_backticks=fix_rst_backticks,
             parameter_metadata=function_param_metadata,
@@ -632,7 +643,7 @@ def wrap_docstring(
     # Default to NumPy-style for unknown/unspecified styles to be permissive.
     return wrap_docstring_numpy(
         docstring,
-        line_length,
+        line_length=line_length,
         leading_indent=leading_indent,
         fix_rst_backticks=fix_rst_backticks,
         parameter_metadata=function_param_metadata,

format_docstring-0.2.4/format_docstring/line_wrap_google.py

@@ -0,0 +1,15 @@
+from format_docstring.line_wrap_utils import ParameterMetadata
+
+
+def wrap_docstring_google(
+        docstring: str,  # noqa: ARG001
+        *,
+        line_length: int,  # noqa: ARG001
+        leading_indent: int | None = None,  # noqa: ARG001
+        fix_rst_backticks: bool = True,  # noqa: ARG001
+        parameter_metadata: ParameterMetadata | None = None,  # noqa: ARG001
+        return_annotation: str | None = None,  # noqa: ARG001
+        attribute_metadata: ParameterMetadata | None = None,  # noqa: ARG001
+) -> str:
+    """A placeholder for now."""  # noqa: D401
+    return ''

{format_docstring-0.2.2 → format_docstring-0.2.4}/format_docstring/line_wrap_numpy.py

@@ -13,8 +13,9 @@ from format_docstring.line_wrap_utils import (
 )
 
 
-def wrap_docstring_numpy(
+def wrap_docstring_numpy(  # noqa: C901, PLR0915, TODO: https://github.com/jsh9/format-docstring/issues/17
         docstring: str,
+        *,
         line_length: int,
         leading_indent: int | None = None,
         fix_rst_backticks: bool = False,
@@ -53,8 +54,7 @@ def wrap_docstring_numpy(
     if not lines:
         return docstring_
 
-    # Track section state
-    SECTION_PARAMS = {
+    section_params = {
         'parameters',
         'parameters:',
         'parameter',  # tolerate typo
@@ -68,14 +68,13 @@ def wrap_docstring_numpy(
         'other parameter',  # tolerate typo
         'other parameter:',
     }
-    SECTION_ATTRIBUTES = {
+    section_attributes = {
         'attributes',
         'attributes:',
         'attribute',  # tolerate typo
         'attribute:',
     }
-    SECTION_SIGNABLE = SECTION_PARAMS | SECTION_ATTRIBUTES
-    SECTION_RETURNS_YIELDS = {
+    section_returns_yields = {
         'returns',
         'returns:',
         'return',  # tolerate typo
@@ -85,13 +84,13 @@ def wrap_docstring_numpy(
         'yield',  # tolerate typo
         'yield:',
     }
-    SECTION_RAISES = {
+    section_raises = {
         'raises',
         'raises:',
         'raise',  # tolerate typo
         'raise:',
     }
-    SECTION_EXAMPLES = {
+    section_examples = {
         'examples',
         'examples:',
         'example',  # tolerate typo
@@ -138,9 +137,8 @@ def wrap_docstring_numpy(
             heading: str | None = _get_section_heading_title(lines, i)
             if heading:
                 current_section = heading
-                in_examples = heading in SECTION_EXAMPLES
-                temp_out.append(line)
-                temp_out.append(lines[i + 1])
+                in_examples = heading in section_examples
+                temp_out.extend((line, lines[i + 1]))
                 i += 2
                 continue
 
@@ -151,18 +149,16 @@ def wrap_docstring_numpy(
             continue
 
         # In Examples, skip wrapping and backtick fixing for REPL lines
-        if in_examples and (
-            stripped.startswith('>>> ') or stripped.startswith('... ')
-        ):
+        if in_examples and stripped.startswith(('>>> ', '... ')):
             temp_out.append(line)
             i += 1
             continue
 
         # Parameters-like sections
         section_lower_case: str = current_section.lower()
-        if section_lower_case in SECTION_SIGNABLE:
+        if section_lower_case in section_params | section_attributes:
             metadata_for_section = parameter_metadata
-            if section_lower_case in SECTION_ATTRIBUTES:
+            if section_lower_case in section_attributes:
                 metadata_for_section = attribute_metadata or parameter_metadata
 
             if line.strip() == '':
@@ -193,7 +189,7 @@ def wrap_docstring_numpy(
             continue
 
         # Returns/Yields sections
-        if section_lower_case in SECTION_RETURNS_YIELDS:
+        if section_lower_case in section_returns_yields:
             if line.strip() == '':
                 temp_out.append(line)
                 i += 1
@@ -245,7 +241,7 @@ def wrap_docstring_numpy(
             continue
 
         # Raises section
-        if section_lower_case in SECTION_RAISES:
+        if section_lower_case in section_raises:
             if line.strip() == '':
                 temp_out.append(line)
                 i += 1
@@ -294,8 +290,9 @@ def _is_hyphen_underline(s: str) -> bool:
     >>> _is_hyphen_underline(' - - ')
     False
     """
-    t = s.strip()
-    return len(t) >= 2 and set(t) <= {'-'}
+    t: str = s.strip()
+    min_hyphens_in_section_header: int = 2
+    return len(t) >= min_hyphens_in_section_header and set(t) <= {'-'}
 
 
 def _get_section_heading_title(lines: list[str], idx: int) -> str | None:
@@ -467,19 +464,39 @@ def _standardize_default_value(line: str) -> str:
     >>> _standardize_default_value('arg : bool, default: True')
     'arg : bool, default=True'
     """
+    colon_idx = line.find(':')
+    if colon_idx == -1:
+        return line
+
+    # `prefix` is everything before the 1st colon (param identifier portion).
+    # We leave `prefix` untouched so arg names like `default` aren't rewritten.
+    prefix = line[: colon_idx + 1]
+    after_colon = line[colon_idx + 1 :]
+
     # Check colon format first to avoid matching colons in space-based pattern
-    match = _DEFAULT_COLON_RE.match(line)
+    match = _DEFAULT_COLON_RE.match(after_colon)
     if match:
-        before = match.group(1).rstrip()
+        before = match.group(1)
+        if before.strip() == '':
+            return line
+
         default_value = match.group(2).strip()
-        return f'{before}, default={default_value}'
+        rebuilt_suffix = f'{before.rstrip()}, default={default_value}'
+        return f'{prefix}{rebuilt_suffix}'
 
     # Try space-separated format with optional "is"
-    match = _DEFAULT_SPACE_RE.match(line)
+    match = _DEFAULT_SPACE_RE.match(after_colon)
     if match:
-        before = match.group(1).rstrip()
+        before = match.group(1)
+        if before.strip() == '':
+            return line
+
+        # ``before`` still contains any annotation text; tightening the spacing
+        # here standardizes the ``", default=..."`` suffix while preserving
+        # whatever appeared to the left.
         default_value = match.group(2).strip()
-        return f'{before}, default={default_value}'
+        rebuilt_suffix = f'{before.rstrip()}, default={default_value}'
+        return f'{prefix}{rebuilt_suffix}'
 
     return line
 
@@ -560,11 +577,10 @@ def _rewrite_parameter_signature(
     core, tail = _extract_signature_tail(line[colon_idx + 1 :])
 
     existing_annotation_text = core.strip()
-    if existing_annotation_text:
-        if ', default=' in existing_annotation_text:
-            existing_annotation_text = existing_annotation_text.split(
-                ', default=', 1
-            )[0].rstrip(', ')
+    if existing_annotation_text and ', default=' in existing_annotation_text:
+        existing_annotation_text = existing_annotation_text.split(
+            ', default=', 1
+        )[0].rstrip(', ')
 
     existing_annotation_text = existing_annotation_text.strip()
 
@@ -624,7 +640,8 @@ def _split_tuple_annotation(annotation: str | None) -> list[str] | None:
         if not isinstance(slice_node, ast.Tuple):
             return None
 
-        if len(slice_node.elts) < 2:
+        min_elements_for_an_actual_tuple: int = 2
+        if len(slice_node.elts) < min_elements_for_an_actual_tuple:
             return None
 
         parts: list[str] = []
@@ -733,12 +750,20 @@ 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-]+:)?`(?!_)([^`]+)`(?!`)(?!__)(?!_)'
 )
 
+# 2nd-stage fixer for ``__dunder__`` names that slipped past the main pattern
+# because the literal starts with an underscore. Negative lookbehinds/aheads
+# ensure we only touch isolated single-backtick literals and leave
+# cross-references (`name`_ / `name`__) alone.
+_DUNDER_LITERAL_PATTERN = re.compile(
+    r'(?<!`)`(__[A-Za-z0-9_]+__)`(?!`)(?!_)(?!__)'
+)
+# Replacement wraps the captured dunder name (group 1) with double backticks.
+_DUNDER_LITERAL_REPLACEMENT = r'``\1``'
+
 
 def _fix_rst_backticks(docstring: str) -> str:
     """
@@ -824,7 +849,7 @@ def _fix_rst_backticks(docstring: str) -> str:
 
         # Check if this is an external link (contains <...> pattern)
         # External links look like: `text <url>`_
-        if '<' in content and '>' in content:
+        if '<' in content and '>' in content:  # noqa: SIM102
             # Check if < comes before > (basic validation)
             if content.index('<') < content.rindex('>'):
                 return full_match  # Keep original (it's an external link)
@@ -846,7 +871,7 @@ def _fix_rst_backticks(docstring: str) -> 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('... '):
+        if stripped.startswith(('>>> ', '... ')):
             repl_lines[i] = line
             # Use a placeholder that won't be matched by the regex
             protected_lines.append(
@@ -860,6 +885,11 @@ def _fix_rst_backticks(docstring: str) -> str:
     # Process the entire docstring (with REPL lines protected)
     protected_docstring = ''.join(protected_lines)
     processed = _RST_BACKTICK_PATTERN.sub(replace_func, protected_docstring)
+    # Upgrade remaining single-backtick ``__dunder__`` literals to double
+    # backticks; they are safe literals (not targets or refs) after the guards.
+    processed = _DUNDER_LITERAL_PATTERN.sub(
+        _DUNDER_LITERAL_REPLACEMENT, processed
+    )
 
     # Restore REPL lines
     result_lines = processed.splitlines(keepends=True)