mkdocstrings-python 2.0.8__tar.gz → 2.0.10__tar.gz

{mkdocstrings_python-2.0.8 → mkdocstrings_python-2.0.10}/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.10](https://github.com/mkdocstrings/python/releases/tag/2.0.10) - 2026-10-19
+
+<small>[Compare with 2.0.9](https://github.com/mkdocstrings/python/compare/2.0.9...2.0.10)</small>
+
+### Build
+
+- Drop support for Python 3.10 ([aad7fc6](https://github.com/mkdocstrings/python/commit/aad7fc6efd12f096807b466e5e3175e27fa7852d) by Timothée Mazzucotelli).
+
+### Bug Fixes
+
+- Prefix code anchor/span IDs in signatures to avoid collisions ([35cde4c](https://github.com/mkdocstrings/python/commit/35cde4c1163d2d8a8fd79b34ab574888bfd30ddf) by Timothée Mazzucotelli). [Issue-200](https://github.com/mkdocstrings/python/issues/200)
+
+## [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>

{mkdocstrings_python-2.0.8 → mkdocstrings_python-2.0.10}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-python
-Version: 2.0.8
+Version: 2.0.10
 Summary: A Python handler for mkdocstrings.
-Author-Email: =?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>
+Author-Email: Timothée Mazzucotelli <dev@pawamoy.fr>
 License-Expression: ISC
 License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
@@ -10,7 +10,6 @@ Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -28,8 +27,8 @@ Project-URL: Issues, https://github.com/mkdocstrings/python/issues
 Project-URL: Discussions, https://github.com/mkdocstrings/python/discussions
 Project-URL: Gitter, https://gitter.im/mkdocstrings/python
 Project-URL: Funding, https://github.com/sponsors/pawamoy
-Requires-Python: >=3.10
-Requires-Dist: mkdocstrings>=0.30
+Requires-Python: >=3.11
+Requires-Dist: mkdocstrings>=1.0.8
 Requires-Dist: mkdocs-autorefs>=1.4
 Requires-Dist: griffelib>=2.0
 Requires-Dist: typing-extensions>=4.0; python_version < "3.11"

{mkdocstrings_python-2.0.8 → mkdocstrings_python-2.0.10}/pyproject.toml

@@ -15,7 +15,7 @@ license-files = [
     "LICENSE",
 ]
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 keywords = []
 dynamic = []
 classifiers = [
@@ -24,7 +24,6 @@ classifiers = [
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -36,12 +35,12 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "mkdocstrings>=0.30",
+    "mkdocstrings>=1.0.8",
     "mkdocs-autorefs>=1.4",
     "griffelib>=2.0",
     "typing-extensions>=4.0; python_version < '3.11'",
 ]
-version = "2.0.8"
+version = "2.0.10"
 
 [project.urls]
 Homepage = "https://mkdocstrings.github.io/python"
@@ -130,5 +129,4 @@ docs = [
     "mkdocs-section-index>=0.3",
     "mkdocstrings>=0.29",
     "pydantic>=2.10",
-    "tomli>=2.0; python_version < '3.11'",
 ]

{mkdocstrings_python-2.0.8 → mkdocstrings_python-2.0.10}/scripts/gen_credits.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import os
-import sys
 from collections import defaultdict
 from collections.abc import Iterable
 from importlib.metadata import distributions
@@ -12,16 +11,11 @@ from pathlib import Path
 from textwrap import dedent
 from typing import Union
 
+import tomllib
 from jinja2 import StrictUndefined
 from jinja2.sandbox import SandboxedEnvironment
 from packaging.requirements import Requirement
 
-# YORE: EOL 3.10: Replace block with line 2.
-if sys.version_info >= (3, 11):
-    import tomllib
-else:
-    import tomli as tomllib
-
 project_dir = Path(os.getenv("MKDOCS_CONFIG_DIR", "."))
 with project_dir.joinpath("pyproject.toml").open("rb") as pyproject_file:
     pyproject = tomllib.load(pyproject_file)

{mkdocstrings_python-2.0.8 → mkdocstrings_python-2.0.10}/scripts/make.py

@@ -14,7 +14,7 @@ if TYPE_CHECKING:
     from collections.abc import Iterator
 
 
-PYTHON_VERSIONS = os.getenv("PYTHON_VERSIONS", "3.10 3.11 3.12 3.13 3.14 3.15").split()
+PYTHON_VERSIONS = os.getenv("PYTHON_VERSIONS", "3.11 3.12 3.13 3.14 3.15").split()
 PYTHON_DEV = "3.15"
 
 

{mkdocstrings_python-2.0.8 → mkdocstrings_python-2.0.10}/src/mkdocstrings_handlers/python/_internal/config.py

@@ -3,21 +3,13 @@
 from __future__ import annotations
 
 import re
-import sys
 from dataclasses import field, fields
-from typing import TYPE_CHECKING, Annotated, Any, Literal
+from typing import TYPE_CHECKING, Annotated, Any, Literal, Self
 
 from mkdocstrings import get_logger
 
 from mkdocstrings_handlers.python._internal.rendering import Order  # noqa: TC001
 
-# YORE: EOL 3.10: Replace block with line 2.
-if sys.version_info >= (3, 11):
-    from typing import Self
-else:
-    from typing_extensions import Self
-
-
 _logger = get_logger(__name__)
 
 _DEFAULT_FILTERS = ["!^_[^_]"]

{mkdocstrings_python-2.0.8 → mkdocstrings_python-2.0.10}/src/mkdocstrings_handlers/python/_internal/handler.py

@@ -39,21 +39,7 @@ if TYPE_CHECKING:
     from mkdocs_autorefs import Backlink
 
 
-# YORE: EOL 3.10: Replace block with line 2.
-if sys.version_info >= (3, 11):
-    from contextlib import chdir
-else:
-    from contextlib import contextmanager
-
-    @contextmanager
-    def chdir(path: str) -> Iterator[None]:
-        old_wd = os.getcwd()
-        os.chdir(path)
-        try:
-            yield
-        finally:
-            os.chdir(old_wd)
-
+from contextlib import chdir
 
 _logger = get_logger(__name__)
 
@@ -365,7 +351,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 +359,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.8 → mkdocstrings_python-2.0.10}/src/mkdocstrings_handlers/python/_internal/rendering.py

@@ -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:

{mkdocstrings_python-2.0.8 → mkdocstrings_python-2.0.10}/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.8 → mkdocstrings_python-2.0.10}/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.
@@ -250,14 +250,14 @@ Context:
                 {% with init = all_members["__init__"] %}
                   <details class="mkdocstrings-source">
                     <summary>{{ lang.t("Source code in") }} <code>{{ init|source_location }}</code></summary>
-                    {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }}
+                    {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True, id_prefix=html_id ~ "--source--") }}
                   </details>
                 {% endwith %}
               {% endif %}
             {% elif class.source %}
               <details class="mkdocstrings-source">
                 <summary>{{ lang.t("Source code in") }} <code>{{ class|source_location }}</code></summary>
-                {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
+                {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True, id_prefix=html_id ~ "--source--") }}
               </details>
             {% endif %}
           {% endif %}

{mkdocstrings_python-2.0.8 → mkdocstrings_python-2.0.10}/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.8 → mkdocstrings_python-2.0.10}/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.8 → mkdocstrings_python-2.0.10}/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,
@@ -147,7 +149,7 @@ Context:
           {% if config.show_source and function.source %}
             <details class="mkdocstrings-source">
               <summary>{{ lang.t("Source code in") }} <code>{{ function|source_location }}</code></summary>
-              {{ function.source|highlight(language="python", linestart=function.lineno or 0, linenums=True) }}
+              {{ function.source|highlight(language="python", linestart=function.lineno or 0, linenums=True, id_prefix=html_id ~ "--source--") }}
             </details>
           {% endif %}
         {% endblock source %}

{mkdocstrings_python-2.0.8 → mkdocstrings_python-2.0.10}/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.8 → mkdocstrings_python-2.0.10}/src/mkdocstrings_handlers/python/templates/readthedocs/_base/class.html.jinja

@@ -209,14 +209,14 @@ Context:
                 {% with init = class.all_members["__init__"] %}
                   <details class="quote">
                     <summary>Source code in <code>{{ init|source_location }}</code></summary>
-                    {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }}
+                    {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True, id_prefix=html_id ~ "--source--") }}
                   </details>
                 {% endwith %}
               {% endif %}
             {% elif class.source %}
               <details class="quote">
                 <summary>Source code in <code>{{ class|source_location }}</code></summary>
-                {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
+                {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True, id_prefix=html_id ~ "--source--") }}
               </details>
             {% endif %}
           {% endif %}

{mkdocstrings_python-2.0.8 → mkdocstrings_python-2.0.10}/tests/test_handler.py

@@ -15,11 +15,13 @@ import bs4
 import mkdocstrings
 import pytest
 from griffe import (
+    Alias,
     Docstring,
     DocstringSectionExamples,
     DocstringSectionKind,
     Module,
     temporary_inspected_module,
+    temporary_pypackage,
     temporary_visited_module,
 )
 from mkdocstrings import CollectionError
@@ -27,6 +29,7 @@ from mkdocstrings import CollectionError
 from mkdocstrings_handlers.python import Inventory, PythonConfig, PythonHandler, PythonOptions
 
 if TYPE_CHECKING:
+    from markdown import Markdown
     from mkdocstrings import MkdocstringsPlugin
 
 
@@ -52,6 +55,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",
     [
@@ -177,6 +206,130 @@ def test_rendering_object_source_without_lineno(handler: PythonHandler) -> None:
         assert handler.render(module, PythonOptions(show_source=True))
 
 
+@pytest.mark.parametrize(
+    ("handler", "merge_init_into_class"),
+    [
+        (
+            {
+                "theme": theme,
+                "markdown_extensions": [
+                    {
+                        "pymdownx.highlight": {
+                            "anchor_linenums": True,
+                            "line_spans": "custom-span",
+                            "line_anchors": "custom-line",
+                            "linenums_style": linenums_style,
+                        },
+                    },
+                    {"pymdownx.superfences": {}},
+                ],
+            },
+            merge_init_into_class,
+        )
+        for theme in ("material", "readthedocs", "mkdocs")
+        for linenums_style in ("table", "inline")
+        for merge_init_into_class in (True, False)
+    ],
+    indirect=["handler"],
+)
+def test_source_code_ids_are_unique(
+    handler: PythonHandler,
+    ext_markdown: Markdown,
+    merge_init_into_class: bool,
+) -> None:
+    """Keep source line IDs unique across modules, overlapping sources, and inherited methods."""
+    # Both modules put their source at the same line numbers. Class source also overlaps method source.
+    code = '''
+        class Base:
+            """Base class."""
+
+            def __init__(self):
+                """Initialize the base class."""
+                self.value = 1
+
+            def method(self):
+                """Return a value."""
+                return self.value
+
+        class Derived(Base):
+            """Derived class."""
+    '''
+    markdown = f"""
+::: source_ids.first
+    options:
+      show_source: true
+      inherited_members: true
+      merge_init_into_class: {str(merge_init_into_class).lower()}
+
+::: source_ids.second
+    options:
+      show_source: true
+      inherited_members: true
+      merge_init_into_class: {str(merge_init_into_class).lower()}
+"""
+    with temporary_pypackage("source_ids", {"first.py": code, "second.py": code}) as package:
+        handler._paths = [str(package.tmpdir)]
+
+        html = ext_markdown.convert(markdown)
+
+    soup = bs4.BeautifulSoup(html, "html.parser")
+    source_blocks = soup.select("details.mkdocstrings-source, details.quote")
+    assert len(source_blocks) == (8 if merge_init_into_class else 12)
+
+    # Every source ID is unique, including methods repeated under Derived.
+    ids = [element["id"] for block in source_blocks for element in block.select("[id]")]
+    assert ids
+    assert len(ids) == len(set(ids))
+    assert all(
+        str(identifier).startswith("source_ids.") and "--source--custom-" in str(identifier) for identifier in ids
+    )
+
+    # Line-number links and legacy anchor names still point to IDs in their own source block.
+    for block in source_blocks:
+        block_ids = {element["id"] for element in block.select("[id]")}
+        links = block.select('a[href^="#"]')
+        assert links
+        assert all(str(link["href"])[1:] in block_ids for link in links)
+        assert all(anchor["name"] == anchor["id"] for anchor in block.select("a[name]"))
+
+
+@pytest.mark.parametrize(
+    "handler",
+    [
+        {
+            "markdown_extensions": [
+                {"pymdownx.highlight": {"anchor_linenums": True, "line_spans": "__span"}},
+                {"pymdownx.superfences": {}},
+            ],
+        },
+    ],
+    indirect=True,
+)
+def test_source_and_docstring_code_ids_do_not_collide(handler: PythonHandler) -> None:
+    """Keep source and docstring code IDs distinct."""
+    # Both the function's source and the fenced example start at line 1.
+    code = '''def function():
+    """An example.
+
+    ```python linenums="1"
+    print("example")
+    ```
+    """
+    return 1
+'''
+    with temporary_visited_module(code, module_name="code_ids") as module:
+        html = handler.render(module["function"], handler.get_options({"show_source": True}))
+
+    soup = bs4.BeautifulSoup(html, "html.parser")
+    ids = [element["id"] for element in soup.select("[id]")]
+
+    assert len(ids) == len(set(ids))
+    assert "code_ids.function--__span-0-1" in ids
+    assert "code_ids.function--source--__span-0-1" in ids
+    assert "code_ids.function--__codelineno-0-1" in ids
+    assert "code_ids.function--source--__codelineno-0-1" in ids
+
+
 def test_give_precedence_to_user_paths() -> None:
     """Assert user paths take precedence over default paths."""
     last_sys_path = sys.path[-1]