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

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

@@ -5,6 +5,22 @@ 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.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>
+
+### Bug Fixes
+
+- Don't render environment paths in source block labels ([84ba73e](https://github.com/mkdocstrings/python/commit/84ba73e8ca4e54afd29a4fe67b8bfb022e76c794) by Chris Wilson). [Issue-333](https://github.com/mkdocstrings/python/issues/333), [PR-338](https://github.com/mkdocstrings/python/pull/338)
+
 ## [2.0.6](https://github.com/mkdocstrings/python/releases/tag/2.0.6) - 2026-08-16
 
 <small>[Compare with 2.0.5](https://github.com/mkdocstrings/python/compare/2.0.5...2.0.6)</small>

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-python
-Version: 2.0.6
+Version: 2.0.8
 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.6 → mkdocstrings_python-2.0.8}/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.6 → mkdocstrings_python-2.0.8}/pyproject.toml

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

{mkdocstrings_python-2.0.6 → mkdocstrings_python-2.0.8}/src/mkdocstrings_handlers/python/__init__.py

@@ -31,6 +31,7 @@ from mkdocstrings_handlers.python._internal.rendering import (
     do_format_type_alias,
     do_get_template,
     do_order_members,
+    do_source_location,
     do_split_path,
     do_stash_crossref,
 )
@@ -64,6 +65,7 @@ __all__ = [
     "do_format_type_alias",
     "do_get_template",
     "do_order_members",
+    "do_source_location",
     "do_split_path",
     "do_stash_crossref",
     "get_handler",

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

@@ -345,6 +345,7 @@ class PythonHandler(BaseHandler):
         self.env.filters["filter_objects"] = rendering.do_filter_objects
         self.env.filters["stash_crossref"] = rendering.do_stash_crossref
         self.env.filters["get_template"] = rendering.do_get_template
+        self.env.filters["source_location"] = rendering.do_source_location
         self.env.filters["as_attributes_section"] = rendering.do_as_attributes_section
         self.env.filters["as_functions_section"] = rendering.do_as_functions_section
         self.env.filters["as_classes_section"] = rendering.do_as_classes_section
@@ -352,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.

{mkdocstrings_python-2.0.6 → mkdocstrings_python-2.0.8}/src/mkdocstrings_handlers/python/_internal/rendering.py

@@ -10,7 +10,8 @@ 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
 
@@ -31,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
@@ -590,6 +591,30 @@ def do_get_template(obj: Object | Alias) -> str:
     return f"{name}.html.jinja"
 
 
+def do_source_location(obj: Object | Alias) -> Path:
+    """Get the file path displayed in an object's source block label.
+
+    Environment paths are never displayed: when the object's file lives in
+    a `site-packages` directory (for example a virtual environment inside
+    the current working directory), the path below `site-packages` is
+    returned instead.
+
+    Parameters:
+        obj: A Griffe object.
+
+    Returns:
+        The file path to display.
+    """
+    relative_filepath = obj.relative_filepath
+    parts = relative_filepath.parts
+    if "site-packages" in parts:
+        anchor = len(parts) - 1 - parts[::-1].index("site-packages")
+        return Path(*parts[anchor + 1 :])
+    if relative_filepath.is_absolute():
+        return obj.relative_package_filepath
+    return relative_filepath
+
+
 @pass_context
 def do_as_attributes_section(
     context: Context,  # noqa: ARG001
@@ -873,3 +898,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.6 → mkdocstrings_python-2.0.8}/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja

@@ -36,7 +36,7 @@ Context:
     {% if not root or config.show_root_heading %}
       {% filter heading(
           heading_level,
-          role="data" if attribute.parent.kind.value == "module" else "attr",
+          role=("data" if attribute.parent.kind.value == "module" else "attr"),
           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 +89,7 @@ Context:
 
       {% if config.show_root_toc_entry %}
         {% filter heading(heading_level,
-            role="data" if attribute.parent.kind.value == "module" else "attr",
+            role=("data" if attribute.parent.kind.value == "module" else "attr"),
             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.6 → mkdocstrings_python-2.0.8}/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja

@@ -249,26 +249,14 @@ Context:
               {% if "__init__" in all_members and all_members["__init__"].source %}
                 {% with init = all_members["__init__"] %}
                   <details class="mkdocstrings-source">
-                    <summary>{{ lang.t("Source code in") }} <code>
-                      {%- if init.relative_filepath.is_absolute() -%}
-                        {{ init.relative_package_filepath }}
-                      {%- else -%}
-                        {{ init.relative_filepath }}
-                      {%- endif -%}
-                    </code></summary>
+                    <summary>{{ lang.t("Source code in") }} <code>{{ init|source_location }}</code></summary>
                     {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }}
                   </details>
                 {% endwith %}
               {% endif %}
             {% elif class.source %}
               <details class="mkdocstrings-source">
-                <summary>{{ lang.t("Source code in") }} <code>
-                  {%- if class.relative_filepath.is_absolute() -%}
-                    {{ class.relative_package_filepath }}
-                  {%- else -%}
-                    {{ class.relative_filepath }}
-                  {%- endif -%}
-                </code></summary>
+                <summary>{{ lang.t("Source code in") }} <code>{{ class|source_location }}</code></summary>
                 {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
               </details>
             {% endif %}

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

@@ -146,13 +146,7 @@ Context:
           -#}
           {% if config.show_source and function.source %}
             <details class="mkdocstrings-source">
-              <summary>{{ lang.t("Source code in") }} <code>
-                {%- if function.relative_filepath.is_absolute() -%}
-                  {{ function.relative_package_filepath }}
-                {%- else -%}
-                  {{ function.relative_filepath }}
-                {%- endif -%}
-              </code></summary>
+              <summary>{{ lang.t("Source code in") }} <code>{{ function|source_location }}</code></summary>
               {{ function.source|highlight(language="python", linestart=function.lineno or 0, linenums=True) }}
             </details>
           {% endif %}

{mkdocstrings_python-2.0.6 → mkdocstrings_python-2.0.8}/src/mkdocstrings_handlers/python/templates/readthedocs/_base/class.html.jinja

@@ -208,26 +208,14 @@ Context:
               {% if "__init__" in class.all_members and class.all_members["__init__"].source %}
                 {% with init = class.all_members["__init__"] %}
                   <details class="quote">
-                    <summary>Source code in <code>
-                      {%- if init.relative_filepath.is_absolute() -%}
-                        {{ init.relative_package_filepath }}
-                      {%- else -%}
-                        {{ init.relative_filepath }}
-                      {%- endif -%}
-                    </code></summary>
+                    <summary>Source code in <code>{{ init|source_location }}</code></summary>
                     {{ init.source|highlight(language="python", linestart=init.lineno or 0, linenums=True) }}
                   </details>
                 {% endwith %}
               {% endif %}
             {% elif class.source %}
               <details class="quote">
-                <summary>Source code in <code>
-                  {%- if class.relative_filepath.is_absolute() -%}
-                    {{ class.relative_package_filepath }}
-                  {%- else -%}
-                    {{ class.relative_filepath }}
-                  {%- endif -%}
-                </code></summary>
+                <summary>Source code in <code>{{ class|source_location }}</code></summary>
                 {{ class.source|highlight(language="python", linestart=class.lineno or 0, linenums=True) }}
               </details>
             {% endif %}

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

@@ -11,6 +11,7 @@ from pathlib import Path
 from textwrap import dedent
 from typing import TYPE_CHECKING
 
+import bs4
 import mkdocstrings
 import pytest
 from griffe import (
@@ -333,3 +334,77 @@ def test_specifying_inventory_base_url(handler: PythonHandler) -> None:
     # Assert the URL is based on the provided base URL
     msg = "Expected inventory URL to start with base_url"
     assert item_url.startswith(base_url), msg
+
+
+def _source_labels(html: str) -> list[Path]:
+    soup = bs4.BeautifulSoup(html, features="html.parser")
+    labels = []
+    for summary in soup.find_all("summary"):
+        if "Source code in" in summary.get_text():
+            code_tag = summary.find("code")
+            assert code_tag is not None
+            labels.append(Path(code_tag.get_text(strip=True)))
+    return labels
+
+
+def _write_site_packages_package(tmp_path: Path, *, single_module: bool) -> None:
+    """Lay out the issue-333 scenario: a package installed in a virtual environment inside the project.
+
+    The environment's `site-packages` directory is relative to the current
+    working directory, so the package's `relative_filepath` is relative too,
+    slipping past `is_absolute()` checks.
+    """
+    code = """
+    class Model:
+        '''Model docstring.'''
+
+        def __init__(self) -> None:
+            '''Init docstring.'''
+            self.model_attribute = 0
+
+        def method(self) -> None:
+            '''Method docstring.'''
+    """
+    site = tmp_path / "site-packages"
+    module_path = site / "pkg.py" if single_module else site / "pkg" / "__init__.py"
+    module_path.parent.mkdir(parents=True)
+    module_path.write_text(dedent(code), encoding="utf-8")
+
+
+@pytest.mark.parametrize(
+    "handler",
+    [
+        {"theme": "readthedocs"},
+        {"theme": {"name": "material"}},
+    ],
+    indirect=["handler"],
+)
+@pytest.mark.parametrize(
+    ("single_module", "extra_options", "expected_label"),
+    [
+        pytest.param(False, {"merge_init_into_class": True}, Path("pkg", "__init__.py"), id="merged-init"),
+        pytest.param(False, {}, Path("pkg", "__init__.py"), id="class-and-methods"),
+        pytest.param(True, {"merge_init_into_class": True}, Path("pkg.py"), id="single-module"),
+    ],
+)
+def test_no_environment_path_in_source_labels(
+    *,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    handler: PythonHandler,
+    single_module: bool,
+    extra_options: dict,
+    expected_label: Path,
+) -> None:
+    """Assert source labels never show an environment path."""
+    _write_site_packages_package(tmp_path, single_module=single_module)
+    monkeypatch.chdir(tmp_path)
+    # `collect()` reads the search paths lazily from this attribute.
+    handler._paths = [str(tmp_path / "site-packages")]
+    options = handler.get_options({"show_source": True, **extra_options})
+    html = handler.render(handler.collect("pkg.Model", options), options)
+    labels = _source_labels(html)
+    assert labels
+    assert set(labels) == {expected_label}
+    # The source bodies themselves are still rendered.
+    assert "model_attribute" in html