Merge branch 'main' into backlinks

Author: pawamoy

CHANGELOG.md

@@ -5,6 +5,50 @@ 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 -->
+## [1.15.0](https://github.com/mkdocstrings/python/releases/tag/1.15.0) - 2025-02-11
+
+<small>[Compare with 1.14.6](https://github.com/mkdocstrings/python/compare/1.14.6...1.15.0)</small>
+
+### Features
+
+- Support cross-referencing constructor parameters in instance attribute values ([f07bf58](https://github.com/mkdocstrings/python/commit/f07bf58a7358dea106032c7da27098e7617eefa0) by Timothée Mazzucotelli).
+
+## [1.14.6](https://github.com/mkdocstrings/python/releases/tag/1.14.6) - 2025-02-07
+
+<small>[Compare with 1.14.5](https://github.com/mkdocstrings/python/compare/1.14.5...1.14.6)</small>
+
+### Bug Fixes
+
+- Catch alias resolution errors when getting aliases for an identifier ([0aaa260](https://github.com/mkdocstrings/python/commit/0aaa260139afe2e3ab85d62224c90a389df64978) by Timothée Mazzucotelli). [Issue-358](https://github.com/mkdocstrings/griffe/discussions/358)
+
+### Code Refactoring
+
+- Improve translations for Simplified Chinese and Japanese ([753a0df](https://github.com/mkdocstrings/python/commit/753a0df8f91f1cf42fb7e56b7fdd312b2bd652ab) by Zhikang Yan). [PR-244](https://github.com/mkdocstrings/python/pull/244)
+
+## [1.14.5](https://github.com/mkdocstrings/python/releases/tag/1.14.5) - 2025-02-05
+
+<small>[Compare with 1.14.4](https://github.com/mkdocstrings/python/compare/1.14.4...1.14.5)</small>
+
+### Bug Fixes
+
+- Remove type from property docstring summary in summary sections ([15f2cd4](https://github.com/mkdocstrings/python/commit/15f2cd48b79a1f062086a47ea0c6bc52d89786d8) by Uchechukwu Orji). [PR-242](https://github.com/mkdocstrings/python/pull/242)
+
+## [1.14.4](https://github.com/mkdocstrings/python/releases/tag/1.14.4) - 2025-02-04
+
+<small>[Compare with 1.14.3](https://github.com/mkdocstrings/python/compare/1.14.3...1.14.4)</small>
+
+### Bug Fixes
+
+- Deactivate Pydantic validation on Python 3.9 is `eval-type-backport` is not available (for modern typing syntax support) ([0de0e5e](https://github.com/mkdocstrings/python/commit/0de0e5e57f8f22e039b0d19aad6341ce7ab3da9f) by Timothée Mazzucotelli). [Issue-241](https://github.com/mkdocstrings/python/issues/241)
+
+## [1.14.3](https://github.com/mkdocstrings/python/releases/tag/1.14.3) - 2025-02-04
+
+<small>[Compare with 1.14.2](https://github.com/mkdocstrings/python/compare/1.14.2...1.14.3)</small>
+
+### Bug Fixes
+
+- Let dataclass implement `__init__` method, set extra fields in `get_options` ([477b9e4](https://github.com/mkdocstrings/python/commit/477b9e447ef9717c6edcb14bd4c53f9cacc555b8) by Timothée Mazzucotelli).
+
 ## [1.14.2](https://github.com/mkdocstrings/python/releases/tag/1.14.2) - 2025-02-03
 
 <small>[Compare with 1.14.1](https://github.com/mkdocstrings/python/compare/1.14.1...1.14.2)</small>

scripts/mkdocs_hooks.py

@@ -1,7 +1,7 @@
 """Generate a JSON schema of the Python handler configuration."""
 
 import json
-from dataclasses import fields
+from dataclasses import dataclass, fields
 from os.path import join
 from typing import Any
 
@@ -25,7 +25,12 @@ def on_post_build(config: MkDocsConfig, **kwargs: Any) -> None:  # noqa: ARG001
     if TypeAdapter is None:
         logger.info("Pydantic is not installed, skipping JSON schema generation")
         return
-    adapter = TypeAdapter(PythonInputConfig)
+
+    @dataclass
+    class PythonHandlerSchema:
+        python: PythonInputConfig
+
+    adapter = TypeAdapter(PythonHandlerSchema)
     schema = adapter.json_schema()
     schema["$schema"] = "https://json-schema.org/draft-07/schema"
     with open(join(config.site_dir, "schema.json"), "w") as file:

src/mkdocstrings_handlers/python/config.py

@@ -7,12 +7,18 @@
 from dataclasses import field, fields
 from typing import TYPE_CHECKING, Annotated, Any, Literal
 
+from mkdocstrings.loggers import get_logger
+
 # 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__)
+
+
 try:
     # When Pydantic is available, use it to validate options (done automatically).
     # Users can therefore opt into validation by installing Pydantic in development/CI.
@@ -30,6 +36,17 @@
     if getattr(pydantic, "__version__", "1.").startswith("1."):
         raise ImportError  # noqa: TRY301
 
+    if sys.version_info < (3, 10):
+        try:
+            import eval_type_backport  # noqa: F401
+        except ImportError:
+            logger.debug(
+                "Pydantic needs the `eval-type-backport` package to be installed "
+                "for modern type syntax to work on Python 3.9. "
+                "Deactivating Pydantic validation for Python handler options.",
+            )
+            raise
+
     from inspect import cleandoc
 
     from pydantic import Field as BaseField
@@ -843,15 +860,6 @@ def _extract_extra(cls, data: dict[str, Any]) -> tuple[dict[str, Any], dict[str,
         copy = data.copy()
         return {name: copy.pop(name) for name in data if name not in field_names}, copy
 
-    # YORE: Bump 2: Remove block.
-    def __init__(self, **kwargs: Any) -> None:
-        """Initialize the instance."""
-        extra_fields = self._extract_extra(kwargs)
-        for name, value in kwargs.items():
-            object.__setattr__(self, name, value)
-        if extra_fields:
-            object.__setattr__(self, "_extra", extra_fields)
-
     @classmethod
     def coerce(cls, **data: Any) -> MutableMapping[str, Any]:
         """Coerce data."""

src/mkdocstrings_handlers/python/handler.py

@@ -188,12 +188,17 @@ def get_options(self, local_options: Mapping[str, Any]) -> HandlerOptions:
 
         extra = {**self.global_options.get("extra", {}), **local_options.get("extra", {})}
         options = {**self.global_options, **local_options, "extra": extra}
-        # YORE: Bump 2: Replace `, **unknown_extra` with `` within line.
         try:
-            return PythonOptions.from_data(**options, **unknown_extra)
+            # YORE: Bump 2: Replace `opts =` with `return` within line.
+            opts = PythonOptions.from_data(**options)
         except Exception as error:
             raise PluginError(f"Invalid options: {error}") from error
 
+        # YORE: Bump 2: Remove block.
+        for key, value in unknown_extra.items():
+            object.__setattr__(opts, key, value)
+        return opts
+
     def collect(self, identifier: str, options: PythonOptions) -> CollectorItem:  # noqa: D102
         module_name = identifier.split(".", 1)[0]
         unknown_module = module_name not in self._modules_collection
@@ -307,17 +312,24 @@ def update_env(self, config: Any) -> None:  # noqa: ARG002
         self.env.tests["existing_template"] = lambda template_name: template_name in self.env.list_templates()
 
     def get_aliases(self, identifier: str) -> tuple[str, ...]:  # noqa: D102 (ignore missing docstring)
+        if "(" in identifier:
+            identifier, parameter = identifier.split("(", 1)
+            parameter.removesuffix(")")
+        else:
+            parameter = ""
         try:
             data = self._modules_collection[identifier]
-        except KeyError:
+        except (KeyError, AliasResolutionError):
             return ()
         aliases = [data.path]
         try:
             for alias in [data.canonical_path, *data.aliases]:
                 if alias not in aliases:
                     aliases.append(alias)
         except AliasResolutionError:
-            return tuple(aliases)
+            pass
+        if parameter:
+            return tuple(f"{alias}({parameter})" for alias in aliases)
         return tuple(aliases)
 
     def normalize_extension_paths(self, extensions: Sequence) -> Sequence:

src/mkdocstrings_handlers/python/rendering.py

@@ -32,7 +32,7 @@
 from mkdocstrings.loggers import get_logger
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Iterator, Sequence
 
     from griffe import Attribute, Class, Function, Module
     from jinja2 import Environment, Template
@@ -326,26 +326,47 @@ def repl(match: Match) -> str:
     return Markup(text).format(**variables)
 
 
-def do_split_path(path: str, full_path: str) -> list[tuple[str, str]]:
+_split_path_re = re.compile(r"([.(]?)([\w]+)(\))?")
+_splitable_re = re.compile(r"[().]")
+
+
+def do_split_path(path: str, full_path: str) -> Iterator[tuple[str, str, str, str]]:
     """Split object paths for building cross-references.
 
     Parameters:
         path: The path to split.
+        full_path: The full path, used to compute correct paths for each part of the path.
 
-    Returns:
-        A list of pairs (title, full path).
+    Yields:
+        4-tuples: prefix, word, full path, suffix.
     """
-    if "." not in path:
-        return [(path, full_path)]
-    pairs = []
-    full_path = ""
-    for part in path.split("."):
-        if full_path:
-            full_path += f".{part}"
-        else:
-            full_path = part
-        pairs.append((part, full_path))
-    return pairs
+    # Path is a single word, yield full path directly.
+    if not _splitable_re.search(path):
+        yield ("", path, full_path, "")
+        return
+
+    current_path = ""
+    if path == full_path:
+        # Split full path and yield directly without storing data in a dict.
+        for match in _split_path_re.finditer(full_path):
+            prefix, word, suffix = match.groups()
+            current_path = f"{current_path}{prefix}{word}{suffix or ''}" if current_path else word
+            yield prefix or "", word, current_path, suffix or ""
+        return
+
+    # Split full path first to store tuples in a dict.
+    elements = {}
+    for match in _split_path_re.finditer(full_path):
+        prefix, word, suffix = match.groups()
+        current_path = f"{current_path}{prefix}{word}{suffix or ''}" if current_path else word
+        elements[word] = (prefix or "", word, current_path, suffix or "")
+
+    # Then split path and pick tuples from the dict.
+    first = True
+    for match in _split_path_re.finditer(path):
+        prefix, word, current_path, suffix = elements[match.group(2)]
+        yield "" if first else prefix, word, current_path, suffix
+        first = False
 
 
 def _keep_object(name: str, filters: Sequence[tuple[Pattern, bool]]) -> bool:
@@ -539,11 +560,20 @@ def do_as_attributes_section(
     Returns:
         An attributes docstring section.
     """
+
+    def _parse_docstring_summary(attribute: Attribute) -> str:
+        if attribute.docstring is None:
+            return ""
+        line = attribute.docstring.value.split("\n", 1)[0]
+        if ":" in line and attribute.docstring.parser_options.get("returns_type_in_property_summary", False):
+            _, line = line.split(":", 1)
+        return line
+
     return DocstringSectionAttributes(
         [
             DocstringAttribute(
                 name=attribute.name,
-                description=attribute.docstring.value.split("\n", 1)[0] if attribute.docstring else "",
+                description=_parse_docstring_summary(attribute),
                 annotation=attribute.annotation,
                 value=attribute.value,  # type: ignore[arg-type]
             )

src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja

@@ -31,7 +31,8 @@ which is a tree-like structure representing a Python expression.
     {%- elif annotation_path == "full" -%}
       {%- set annotation = full -%}
     {%- endif -%}
-    {%- for title, path in annotation|split_path(full) -%}
+    {%- for prefix, title, path, suffix in annotation|split_path(full) -%}
+      {{ prefix }}
       {%- if not signature -%}
         {#- Always render cross-references outside of signatures. We don't need to stash them. -#}
         <autoref identifier="{{ path }}"{% if backlink_type %} backlink-type="{{ backlink_type }}" backlink-anchor="{{ html_id }}"{% endif %} optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
@@ -44,7 +45,7 @@ which is a tree-like structure representing a Python expression.
         {#- We're in a signature but cross-references are disabled, we just render the title. -#}
         {{ title }}
       {%- endif -%}
-      {%- if not loop.last -%}.{%- endif -%}
+      {{ suffix }}
     {%- endfor -%}
   {%- endwith -%}
 {%- endmacro -%}

src/mkdocstrings_handlers/python/templates/material/_base/languages/ja.html.jinja

@@ -10,20 +10,20 @@
 {% macro t(key) %}{{ {
   "ATTRIBUTE": "属性",
   "Attributes:": "属性：",
-  "Classes:": "",
-  "CLASS": "",
+  "Classes:": "クラス：",
+  "CLASS": "クラス",
   "DEFAULT:": "デフォルト：",
   "Default": "デフォルト",
   "default:": "デフォルト：",
   "DESCRIPTION": "デスクリプション",
   "Description": "デスクリプション",
   "Examples:": "例：",
-  "Functions:": "",
-  "FUNCTION": "",
-  "Methods:": "",
-  "METHOD": "",
-  "Modules:": "",
-  "MODULE": "",
+  "Functions:": "関数：",
+  "FUNCTION": "関数",
+  "Methods:": "メソッド：",
+  "METHOD": "メソッド",
+  "Modules:": "モジュール：",
+  "MODULE": "モジュール",
   "Name": "名前",
   "Other Parameters:": "他の引数：",
   "PARAMETER": "引数",

src/mkdocstrings_handlers/python/templates/material/_base/languages/zh.html.jinja

@@ -10,20 +10,20 @@
 {% macro t(key) %}{{ {
   "ATTRIBUTE": "属性",
   "Attributes:": "属性：",
-  "Classes:": "",
-  "CLASS": "",
+  "Classes:": "类：",
+  "CLASS": "类",
   "DEFAULT:": "默认：",
   "Default": "默认",
   "default:": "默认：",
   "DESCRIPTION": "描述",
   "Description": "描述",
   "Examples:": "示例：",
-  "Functions:": "",
-  "FUNCTION": "",
-  "Methods:": "",
-  "METHOD": "",
-  "Modules:": "",
-  "MODULE": "",
+  "Functions:": "函数：",
+  "FUNCTION": "函数",
+  "Methods:": "方法：",
+  "METHOD": "方法",
+  "Modules:": "模块：",
+  "MODULE": "模块",
   "Name": "名称",
   "Other Parameters:": "其他参数：",
   "PARAMETER": "参数",

src/mkdocstrings_handlers/python/templates/readthedocs/_base/languages/ja.html.jinja

@@ -4,20 +4,20 @@
 {% macro t(key) %}{{ {
   "ATTRIBUTE": "属性",
   "Attributes:": "属性：",
-  "Classes:": "",
-  "CLASS": "",
+  "Classes:": "クラス：",
+  "CLASS": "クラス",
   "DEFAULT:": "デフォルト：",
   "Default": "デフォルト",
   "default:": "デフォルト：",
   "DESCRIPTION": "デスクリプション",
   "Description": "デスクリプション",
   "Examples:": "例：",
-  "Functions:": "",
-  "FUNCTION": "",
-  "Methods:": "",
-  "METHOD": "",
-  "Modules:": "",
-  "MODULE": "",
+  "Functions:": "関数：",
+  "FUNCTION": "関数",
+  "Methods:": "メソッド：",
+  "METHOD": "メソッド",
+  "Modules:": "モジュール：",
+  "MODULE": "モジュール",
   "Name": "名前",
   "Other Parameters:": "他の引数：",
   "PARAMETER": "引数",