fix: Fix highlighting for signature with known special names like __init__

pawamoy · pawamoy · commit 7f956868f93a · 2025-05-23T15:10:20.000+02:00
Issue-mkdocstrings-757: mkdocstrings/mkdocstrings#757
diff --git a/src/mkdocstrings_handlers/python/_internal/rendering.py b/src/mkdocstrings_handlers/python/_internal/rendering.py
@@ -185,10 +185,12 @@ def do_format_signature(
     # Pygments sees it as a function call and not a function definition.
     # The result is that the function name is not parsed as such,
     # but instead as a regular name: `n` CSS class instead of `nf`.
-    # To fix it, we replace the first occurrence of an `n` CSS class
-    # with an `nf` one, unless we found `nf` already.
-    if signature.find('class="nf"') == -1:
-        signature = signature.replace('class="n"', 'class="nf"', 1)
+    # When the function name is a known special name like `__exit__`,
+    # Pygments will set an `fm` (function -> magic) CSS class.
+    # To fix this, we replace the CSS class in the first span with `nf`,
+    # unless we already found an `nf` span.
+    if not re.search(r'<span class="nf">', signature):
+        signature = re.sub(r'<span class="[a-z]+">', '<span class="nf">', signature, count=1)
 
     if stash := env.filters["stash_crossref"].stash:
         for key, value in stash.items():
diff --git a/tests/snapshots/__init__.py b/tests/snapshots/__init__.py
@@ -8,12 +8,12 @@
             ("separate_signature", True),
             ("show_signature_annotations", False),
             ("signature_crossrefs", False),
-        ): external("4370d843cc76*.html"),
+        ): external("d03d16d1919a*.html"),
         (
             ("separate_signature", True),
             ("show_signature_annotations", True),
             ("signature_crossrefs", True),
-        ): external("261a38d7a86b*.html"),
+        ): external("e412376be64f*.html"),
         (
             ("separate_signature", False),
             ("show_signature_annotations", True),
@@ -33,12 +33,12 @@
             ("separate_signature", True),
             ("show_signature_annotations", True),
             ("signature_crossrefs", False),
-        ): external("f5ce06acbb7a*.html"),
+        ): external("74ee37cd1e94*.html"),
         (
             ("separate_signature", True),
             ("show_signature_annotations", False),
             ("signature_crossrefs", True),
-        ): external("9c0bfc0ee407*.html"),
+        ): external("4041a38e355f*.html"),
         (
             ("separate_signature", False),
             ("show_signature_annotations", True),
diff --git a/tests/snapshots/external/4041a38e355f6585a7e1265509d7c5b499fe3776aeeeb298db7589bb385ca019.html b/tests/snapshots/external/4041a38e355f6585a7e1265509d7c5b499fe3776aeeeb298db7589bb385ca019.html
@@ -36,7 +36,7 @@ <h3 class="doc doc-heading" id="signature_package.Class.__init__">
         </span>
        </h3>
        <div class="doc-signature highlight">
-        <pre><span></span><code><span class="fm">__init__</span><span class="p">(</span><span class="nf">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>
+        <pre><span></span><code><span class="nf">__init__</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>
 </code></pre>
        </div>
        <div class="doc doc-contents">
diff --git a/tests/snapshots/external/74ee37cd1e94250baa33050af088e7341495708d879ab45ee9e8ab1dcac26f2a.html b/tests/snapshots/external/74ee37cd1e94250baa33050af088e7341495708d879ab45ee9e8ab1dcac26f2a.html
@@ -36,7 +36,7 @@ <h3 class="doc doc-heading" id="signature_package.Class.__init__">
         </span>
        </h3>
        <div class="doc-signature highlight">
-        <pre><span></span><code><span class="fm">__init__</span><span class="p">(</span><span class="nf">a</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">b</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
+        <pre><span></span><code><span class="nf">__init__</span><span class="p">(</span><span class="n">a</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">b</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
 </code></pre>
        </div>
        <div class="doc doc-contents">
diff --git a/tests/snapshots/external/d03d16d1919af01db9b8d4e5bf36b007810eb3730a7283624a4d68c6fe2ce652.html b/tests/snapshots/external/d03d16d1919af01db9b8d4e5bf36b007810eb3730a7283624a4d68c6fe2ce652.html
@@ -36,7 +36,7 @@ <h3 class="doc doc-heading" id="signature_package.Class.__init__">
         </span>
        </h3>
        <div class="doc-signature highlight">
-        <pre><span></span><code><span class="fm">__init__</span><span class="p">(</span><span class="nf">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>
+        <pre><span></span><code><span class="nf">__init__</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span>
 </code></pre>
        </div>
        <div class="doc doc-contents">
diff --git a/tests/snapshots/external/e412376be64f25f3f5d2264400a83a1e693c146feec7c359855c676c4a586392.html b/tests/snapshots/external/e412376be64f25f3f5d2264400a83a1e693c146feec7c359855c676c4a586392.html
@@ -36,7 +36,7 @@ <h3 class="doc doc-heading" id="signature_package.Class.__init__">
         </span>
        </h3>
        <div class="doc-signature highlight">
-        <pre><span></span><code><span class="fm">__init__</span><span class="p">(</span><span class="nf">a</span><span class="p">:</span> <span class="n"><autoref backlink-anchor="signature_package.Class.__init__" backlink-type="used-by" identifier="int" optional="">int</autoref></span><span class="p">,</span> <span class="n">b</span><span class="p">:</span> <span class="n"><autoref backlink-anchor="signature_package.Class.__init__" backlink-type="used-by" identifier="str" optional="">str</autoref></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
+        <pre><span></span><code><span class="nf">__init__</span><span class="p">(</span><span class="n">a</span><span class="p">:</span> <span class="n"><autoref backlink-anchor="signature_package.Class.__init__" backlink-type="used-by" identifier="int" optional="">int</autoref></span><span class="p">,</span> <span class="n">b</span><span class="p">:</span> <span class="n"><autoref backlink-anchor="signature_package.Class.__init__" backlink-type="used-by" identifier="str" optional="">str</autoref></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
 </code></pre>
        </div>
        <div class="doc doc-contents">
