mkdocstrings-python 2.0.7__tar.gz → 2.0.9__tar.gz

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/CHANGELOG.md

@@ -5,6 +5,27 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 <!-- insertion marker -->
+## [2.0.9](https://github.com/mkdocstrings/python/releases/tag/2.0.9) - 2026-09-22
+
+<small>[Compare with 2.0.8](https://github.com/mkdocstrings/python/compare/2.0.8...2.0.9)</small>
+
+### Bug Fixes
+
+- Improve inventory object types (incorrectly called roles in mkdocstrings) ([d754326](https://github.com/mkdocstrings/python/commit/d754326b534a7771a5d815935976bdb869913a5f) by Timothée Mazzucotelli). [Issue-339](https://github.com/mkdocstrings/python/issues/339), [PR-340](https://github.com/mkdocstrings/python/pull/340)
+- Expand relative cross-references against the object the docstring was written on ([a9a4ca3](https://github.com/mkdocstrings/python/commit/a9a4ca3bfd8ee361cd8f7aa63a5079b232adc837) by Dev M). [Issue-341](https://github.com/mkdocstrings/python/issues/341), [PR-342](https://github.com/mkdocstrings/python/pull/342)
+
+### Performance Improvements
+
+- Small performance improvement when getting aliases and formatting/highlighting signatures ([2263163](https://github.com/mkdocstrings/python/commit/2263163f0263cb86ae9696f955213ab8fa8f5518) by Timothée Mazzucotelli).
+
+## [2.0.8](https://github.com/mkdocstrings/python/releases/tag/2.0.8) - 2026-08-31
+
+<small>[Compare with 2.0.7](https://github.com/mkdocstrings/python/compare/2.0.7...2.0.8)</small>
+
+### Performance Improvements
+
+- Make template existence test (for locale templates) faster ([c0424f2](https://github.com/mkdocstrings/python/commit/c0424f2b10f9d8cfded49e7720e95ad90e4c5b9c) by Timothée Mazzucotelli).
+
 ## [2.0.7](https://github.com/mkdocstrings/python/releases/tag/2.0.7) - 2026-08-17
 
 <small>[Compare with 2.0.6](https://github.com/mkdocstrings/python/compare/2.0.6...2.0.7)</small>

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-python
-Version: 2.0.7
+Version: 2.0.9
 Summary: A Python handler for mkdocstrings.
 Author-Email: =?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>
 License-Expression: ISC

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/config/git-changelog.toml

@@ -4,6 +4,6 @@ in-place = true
 output = "CHANGELOG.md"
 parse-refs = false
 parse-trailers = true
-sections = ["build", "deps", "feat", "fix", "refactor"]
+sections = ["build", "deps", "feat", "fix", "perf", "refactor"]
 template = "keepachangelog"
 versioning = "pep440"

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/pyproject.toml

@@ -41,7 +41,7 @@ dependencies = [
     "griffelib>=2.0",
     "typing-extensions>=4.0; python_version < '3.11'",
 ]
-version = "2.0.7"
+version = "2.0.9"
 
 [project.urls]
 Homepage = "https://mkdocstrings.github.io/python"

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/src/mkdocstrings_handlers/python/_internal/handler.py

@@ -353,7 +353,7 @@ class PythonHandler(BaseHandler):
         self.env.filters["as_modules_section"] = rendering.do_as_modules_section
         self.env.filters["backlink_tree"] = rendering.do_backlink_tree
         self.env.globals["AutorefsHook"] = rendering.AutorefsHook
-        self.env.tests["existing_template"] = lambda template_name: template_name in self.env.list_templates()
+        self.env.tests["existing_template"] = rendering._test_existing_template  # type: ignore[assignment]
 
     def get_aliases(self, identifier: str) -> tuple[str, ...]:
         """Get the aliases for the given identifier.
@@ -365,7 +365,7 @@ class PythonHandler(BaseHandler):
             The aliases.
         """
         if "(" in identifier:
-            identifier, parameter = identifier.split("(", 1)
+            identifier, _, parameter = identifier.partition("(")
             parameter = parameter.removesuffix(")")
         else:
             parameter = ""
@@ -373,15 +373,18 @@ class PythonHandler(BaseHandler):
             data = self._modules_collection[identifier]
         except (KeyError, AliasResolutionError):
             return ()
-        aliases = [data.path]
+        aliases: dict[str, object] = {data.path: None}
         try:
-            for alias in [data.canonical_path, *data.aliases]:
-                if alias not in aliases:
-                    aliases.append(alias)
+            canonical_path = data.canonical_path
+            data_aliases = data.aliases
         except AliasResolutionError:
             pass
+        else:
+            aliases[canonical_path] = None
+            aliases.update(data_aliases)
         if parameter:
-            return tuple(f"{alias}({parameter})" for alias in aliases)
+            suffix = f"({parameter})"
+            return tuple(alias + suffix for alias in aliases)
         return tuple(aliases)
 
     def normalize_extension_paths(self, extensions: Sequence) -> list[str | dict[str, Any]]:

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/src/mkdocstrings_handlers/python/_internal/rendering.py

@@ -10,7 +10,7 @@ import sys
 from collections import defaultdict
 from contextlib import suppress
 from dataclasses import replace
-from functools import lru_cache
+from functools import cache, lru_cache
 from pathlib import Path
 from re import Pattern
 from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal, TypeVar
@@ -32,7 +32,7 @@ from griffe import (
     Object,
     TypeAlias,
 )
-from jinja2 import pass_context
+from jinja2 import Environment, pass_context, pass_environment
 from markupsafe import Markup
 from mkdocs_autorefs import AutorefsHookInterface, Backlink, BacklinkCrumb
 from mkdocstrings import get_logger
@@ -125,6 +125,15 @@ class _StashCrossRefFilter:
 do_stash_crossref = _StashCrossRefFilter()
 """Filter to stash cross-references (and restore them after formatting and highlighting)."""
 
+_highlighting_span_re = re.compile(r'<span class="[a-z]{1,2}">')
+_crossref_key_re = re.compile(r"\b_[A-Za-z0-9]{2,}\b")
+
+
+def _restore_crossrefs(text: str, stash: dict[str, str]) -> str:
+    text = _crossref_key_re.sub(lambda match: stash.get(match[0], match[0]), text)
+    stash.clear()
+    return text
+
 
 def _format_signature(name: Markup, signature: str, line_length: int) -> str:
     name = str(name).strip()  # type: ignore[assignment]
@@ -199,13 +208,11 @@ def do_format_signature(
     # 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]{1,2}">', '<span class="nf">', signature, count=1)
+    if '<span class="nf">' not in signature:
+        signature = _highlighting_span_re.sub('<span class="nf">', signature, count=1)
 
     if stash := env.filters["stash_crossref"].stash:
-        for key, value in stash.items():
-            signature = re.sub(rf"\b{key}\b", value, signature)
-        stash.clear()
+        signature = _restore_crossrefs(signature, stash)
 
     return signature
 
@@ -267,9 +274,7 @@ def do_format_attribute(
     )
 
     if stash := env.filters["stash_crossref"].stash:
-        for key, value in stash.items():
-            signature = re.sub(rf"\b{key}\b", value, signature)
-        stash.clear()
+        signature = _restore_crossrefs(signature, stash)
 
     return signature
 
@@ -322,13 +327,11 @@ def do_format_type_alias(
     # but instead as a regular name: `n` CSS class instead of `nc`.
     # To fix it, we replace the first occurrence of an `n` CSS class
     # with an `nc` one, unless we found `nc` already.
-    if not re.search(r'<span class="nc">', signature):
-        signature = re.sub(r'<span class="[a-z]{1,2}">', '<span class="nc">', signature, count=1)
+    if '<span class="nc">' not in signature:
+        signature = _highlighting_span_re.sub('<span class="nc">', signature, count=1)
 
     if stash := env.filters["stash_crossref"].stash:
-        for key, value in stash.items():
-            signature = re.sub(rf"\b{key}\b", value, signature)
-        stash.clear()
+        signature = _restore_crossrefs(signature, stash)
 
     return signature
 
@@ -805,6 +808,11 @@ class AutorefsHook(AutorefsHookInterface):
         if self.config.relative_crossrefs and identifier.startswith("."):  # type: ignore[attr-defined]
             identifier = identifier[1:]
             obj = self.current_object
+            # Anchor on the docstring's parent: for inherited members the current
+            # object is an alias living under the inheriting class, while the
+            # docstring was written on the defining object in another tree.
+            if self.current_object.docstring is not None and self.current_object.docstring.parent is not None:
+                obj = self.current_object.docstring.parent
             while identifier and identifier[0] == ".":
                 identifier = identifier[1:]
                 if obj.parent is None:
@@ -898,3 +906,9 @@ def do_backlink_tree(backlinks: list[Backlink]) -> Tree[BacklinkCrumb]:
         A tree of backlinks.
     """
     return _compact_tree(_tree(backlink.crumbs for backlink in backlinks))
+
+
+@cache
+@pass_environment
+def _test_existing_template(env: Environment, path: str) -> bool:
+    return path in env.list_templates()

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja

@@ -33,10 +33,13 @@ Context:
 
     {% set attribute_name = attribute.path if show_full_path else attribute.name %}
 
+    {% set object_type = "data" if attribute.parent.is_module else "property" if "property" in attribute.labels else "attribute" %}
+    {#- Object type in objects inventory. -#}
+
     {% if not root or config.show_root_heading %}
       {% filter heading(
           heading_level,
-          role="data" if attribute.parent.kind.value == "module" else "attr",
+          role=object_type,
           id=html_id,
           class="doc doc-heading",
           toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute.name),
@@ -89,7 +92,7 @@ Context:
 
       {% if config.show_root_toc_entry %}
         {% filter heading(heading_level,
-            role="data" if attribute.parent.kind.value == "module" else "attr",
+            role=object_type,
             id=html_id,
             toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute_name),
             hidden=True,

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja

@@ -158,7 +158,7 @@ Context:
 
         {% block inheritance_diagram scoped %}
           {#- Inheritance diagram block.
-          
+
           This block renders the inheritance diagram for the class,
           using Mermaid syntax and a bit of JavaScript to make the nodes clickable,
           linking to the corresponding class documentation.

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja

@@ -38,7 +38,7 @@ Context:
               {% if config.parameter_headings %}
                 {% filter heading(
                     heading_level + 1,
-                    role="param",
+                    role="parameter",
                     id=html_id ~ "(" ~ parameter.name ~ ")",
                     class="doc doc-heading doc-heading-parameter",
                     toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + parameter.name,
@@ -86,7 +86,7 @@ Context:
           {% if config.parameter_headings %}
             {% filter heading(
                 heading_level + 1,
-                role="param",
+                role="parameter",
                 id=html_id ~ "(" ~ parameter.name ~ ")",
                 class="doc doc-heading doc-heading-parameter",
                 toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + parameter.name,
@@ -132,7 +132,7 @@ Context:
               {% if config.parameter_headings %}
                 {% filter heading(
                     heading_level + 1,
-                    role="param",
+                    role="parameter",
                     id=html_id ~ "(" ~ parameter.name ~ ")",
                     class="doc doc-heading doc-heading-parameter",
                     toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + parameter.name,

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/src/mkdocstrings_handlers/python/templates/material/_base/docstring/type_parameters.html.jinja

@@ -42,7 +42,7 @@ Context:
               {% if config.type_parameter_headings %}
                 {% filter heading(
                     heading_level + 1,
-                    role="typeparam",
+                    role="typeparameter",
                     id=obj.path ~ "[" ~ type_parameter.name ~ "]",
                     class="doc doc-heading doc-heading-type_parameter",
                     toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-type_parameter"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + type_parameter.name,
@@ -93,7 +93,7 @@ Context:
           {% if config.type_parameter_headings %}
             {% filter heading(
                 heading_level + 1,
-                role="typeparam",
+                role="typeparameter",
                 id=obj.path ~ "[" ~ type_parameter.name ~ "]",
                 class="doc doc-heading doc-heading-type_parameter",
                 toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-type_parameter"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + type_parameter.name,
@@ -156,7 +156,7 @@ Context:
               {% if config.type_parameter_headings %}
                 {% filter heading(
                     heading_level + 1,
-                    role="typeparam",
+                    role="typeparameter",
                     id=obj.path ~ "[" ~ type_parameter.name ~ "]",
                     class="doc doc-heading doc-heading-type_parameter",
                     toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-type_parameter"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + type_parameter.name,

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja

@@ -37,11 +37,13 @@ Context:
     {#- Brief or full function name depending on configuration. -#}
     {% set symbol_type = "method" if function.parent.is_class else "function" %}
     {#- Symbol type: method when parent is a class, function otherwise. -#}
+    {% set object_type = symbol_type %}
+    {#- Object type in objects inventory. -#}
 
     {% if not root or config.show_root_heading %}
       {% filter heading(
           heading_level,
-          role="function",
+          role=object_type,
           id=html_id,
           class="doc doc-heading",
           toc_label=(('<code class="doc-symbol doc-symbol-toc doc-symbol-' + symbol_type + '"></code>&nbsp;')|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else function.name),
@@ -106,7 +108,7 @@ Context:
       {% if config.show_root_toc_entry %}
         {% filter heading(
             heading_level,
-            role="function",
+            role=object_type,
             id=html_id,
             toc_label=(('<code class="doc-symbol doc-symbol-toc doc-symbol-' + symbol_type + '"></code>&nbsp;')|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else function.name),
             hidden=True,

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/src/mkdocstrings_handlers/python/templates/material/_base/type_alias.html.jinja

@@ -35,7 +35,7 @@ Context:
     {% if not root or config.show_root_heading %}
       {% filter heading(
           heading_level,
-          role="typealias",
+          role="type",
           id=html_id,
           class="doc doc-heading",
           toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-type_alias"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + type_alias.name,
@@ -83,7 +83,7 @@ Context:
     {% else %}
       {% if config.show_root_toc_entry %}
         {% filter heading(heading_level,
-            role="typealias",
+            role="type",
             id=html_id,
             toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-type_alias"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + type_alias.name,
             hidden=True,

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/tests/test_handler.py

@@ -15,6 +15,7 @@ import bs4
 import mkdocstrings
 import pytest
 from griffe import (
+    Alias,
     Docstring,
     DocstringSectionExamples,
     DocstringSectionKind,
@@ -52,6 +53,32 @@ def test_collect_with_null_parser(handler: PythonHandler) -> None:
     assert handler.collect("mkdocstrings", PythonOptions(docstring_style=None))
 
 
+def test_get_aliases(handler: PythonHandler) -> None:
+    """Assert aliases are unique, ordered, and extended with parameter identifiers."""
+    with temporary_visited_module(
+        "def target(parameter): ...",
+        module_name="package",
+        modules_collection=handler._modules_collection,
+    ) as module:
+        target = module["target"]
+        module["alias"] = Alias("alias", target=target)
+        module["other_alias"] = Alias("other_alias", target=target)
+        module["unresolved"] = Alias("unresolved", target="missing.target")
+
+        assert handler.get_aliases("package.target") == (
+            "package.target",
+            "package.alias",
+            "package.other_alias",
+        )
+        assert handler.get_aliases("package.alias(parameter)") == (
+            "package.alias(parameter)",
+            "package.target(parameter)",
+            "package.other_alias(parameter)",
+        )
+        assert handler.get_aliases("package.unresolved") == ("package.unresolved",)
+        assert handler.get_aliases("package.missing") == ()
+
+
 @pytest.mark.parametrize(
     "handler",
     [

{mkdocstrings_python-2.0.7 → mkdocstrings_python-2.0.9}/tests/test_rendering.py

@@ -4,12 +4,14 @@ from __future__ import annotations
 
 import re
 from dataclasses import dataclass
+from types import SimpleNamespace
 from typing import TYPE_CHECKING, Any, Callable, cast
 
 import pytest
 from griffe import Alias, ModulesCollection, Object, temporary_visited_module
 
 from mkdocstrings_handlers.python._internal import rendering
+from mkdocstrings_handlers.python._internal.rendering import AutorefsHook
 
 if TYPE_CHECKING:
     from markupsafe import Markup
@@ -54,6 +56,16 @@ def test_format_signature(name: Markup, signature: str) -> None:
         assert rendering._format_signature(name, signature, length)
 
 
+def test_restore_crossrefs() -> None:
+    """Restore multiple stashed cross-references without replacing partial keys."""
+    stash = {"_short": "<autoref>short</autoref>", "_shorter": "<autoref>shorter</autoref>"}
+
+    restored = rendering._restore_crossrefs("_short + _shorter + x_short + _shorterx", stash)
+
+    assert restored == "<autoref>short</autoref> + <autoref>shorter</autoref> + x_short + _shorterx"
+    assert not stash
+
+
 @dataclass
 class _FakeObject:
     name: str
@@ -174,3 +186,42 @@ def test_ordering_members(order: rendering.Order, members_list: list[str | None]
     members = [Obj("a", 10, is_alias=True), Obj("b", 9, is_alias=False), Obj("c", 8, is_alias=True)]
     ordered = rendering.do_order_members(members, order, members_list)  # type: ignore[arg-type]
     assert [obj.name for obj in ordered] == expected_names
+
+
+def test_expand_identifier_relative_crossref_in_inherited_member() -> None:
+    """Relative cross-references in inherited members expand against the defining object.
+
+    The docstring of an inherited member is rendered in the docs of the inheriting
+    class, where the current object is an alias living under that class. Dots in
+    relative references must still climb the tree of the class the docstring was
+    written on, not the consumer's tree.
+    """
+    collection = ModulesCollection()
+    with temporary_visited_module(
+        '''
+        class Base:
+            MAPPING = {}
+            """The mapping to use for each [`Thing`][....Thing]."""
+        ''',
+        module_name="pkga",
+        modules_collection=collection,
+    ) as module:
+        collection["pkga"] = module
+        with temporary_visited_module(
+            """
+            from pkga import Base
+
+            class Derived(Base): ...
+            """,
+            module_name="pkgb",
+            modules_collection=collection,
+        ) as module_b:
+            collection["pkgb"] = module_b
+            config = SimpleNamespace(relative_crossrefs=True, scoped_crossrefs=False)
+            # Control: a non-inherited object expands relative references in its own tree.
+            direct = AutorefsHook(collection["pkga"]["Base"]["MAPPING"], config)  # type: ignore[arg-type]
+            assert direct.expand_identifier("....Thing") == "pkga.Thing"
+            # Inherited member: the current object is an alias under pkgb.Derived,
+            # but the docstring was written on pkga.Base.MAPPING.
+            inherited = AutorefsHook(collection["pkgb"]["Derived"]["MAPPING"], config)  # type: ignore[arg-type]
+            assert inherited.expand_identifier("....Thing") == "pkga.Thing"