mkdocstrings-python 0.10.1__py3-none-any.whl → 1.1.0__py3-none-any.whl

mkdocstrings_handlers/python/handler.py

@@ -84,6 +84,7 @@ class PythonHandler(BaseHandler):
         "show_if_no_docstring": False,
         "show_signature": True,
         "show_signature_annotations": False,
+        "signature_crossrefs": False,
         "separate_signature": False,
         "line_length": 60,
         "merge_init_into_class": False,
@@ -169,6 +170,7 @@ class PythonHandler(BaseHandler):
         line_length (int): Maximum line length when formatting code/signatures. Default: `60`.
         show_signature (bool): Show methods and functions signatures. Default: `True`.
         show_signature_annotations (bool): Show the type annotations in methods and functions signatures. Default: `False`.
+        signature_crossrefs (bool): Whether to render cross-references for type annotations in signatures. Default: `False`.
         separate_signature (bool): Whether to put the whole signature in a code block below the heading.
             If Black is installed, the signature is also formatted using it. Default: `False`.
     """
@@ -295,7 +297,8 @@ class PythonHandler(BaseHandler):
         mutabled_config = dict(copy.deepcopy(config))
         final_config = ChainMap(mutabled_config, self.default_config)
 
-        template = self.env.get_template(f"{data.kind.value}.html")
+        template_name = rendering.do_get_template(data)
+        template = self.env.get_template(template_name)
 
         # Heading level is a "state" variable, that will change at each step
         # of the rendering recursion. Therefore, it's easier to use it as a plain value
@@ -314,6 +317,9 @@ class PythonHandler(BaseHandler):
                 (re.compile(filtr.lstrip("!")), filtr.startswith("!")) for filtr in final_config["filters"]
             ]
 
+        # TODO: goal reached: remove once `signature_crossrefs` feature becomes public
+        final_config["signature_crossrefs"] = False
+
         return template.render(
             **{"config": final_config, data.kind.value: data, "heading_level": heading_level, "root": True},
         )
@@ -329,6 +335,8 @@ class PythonHandler(BaseHandler):
         self.env.filters["format_code"] = rendering.do_format_code
         self.env.filters["format_signature"] = rendering.do_format_signature
         self.env.filters["filter_objects"] = rendering.do_filter_objects
+        self.env.filters["stash_crossref"] = lambda ref, length: ref
+        self.env.filters["get_template"] = rendering.do_get_template
 
     def get_anchors(self, data: CollectorItem) -> set[str]:  # noqa: D102 (ignore missing docstring)
         try:

mkdocstrings_handlers/python/rendering.py

@@ -8,11 +8,13 @@ import sys
 from functools import lru_cache
 from typing import TYPE_CHECKING, Any, Callable, Match, Pattern, Sequence
 
+from jinja2 import pass_context
 from markupsafe import Markup
 from mkdocstrings.loggers import get_logger
 
 if TYPE_CHECKING:
-    from griffe.dataclasses import Alias, Object
+    from griffe.dataclasses import Alias, Function, Object
+    from jinja2.runtime import Context
     from mkdocstrings.handlers.base import CollectorItem
 
 logger = get_logger(__name__)
@@ -60,26 +62,17 @@ def do_format_code(code: str, line_length: int) -> str:
     return formatter(code, line_length)
 
 
-def do_format_signature(signature: str, line_length: int) -> str:
-    """Format a signature using Black.
-
-    Parameters:
-        signature: The signature to format.
-        line_length: The line length to give to Black.
-
-    Returns:
-        The same code, formatted.
-    """
-    code = signature.strip()
-    if len(code) < line_length:
-        return code
+def _format_signature(name: Markup, signature: str, line_length: int) -> str:
+    name = str(name).strip()  # type: ignore[assignment]
+    signature = signature.strip()
+    if len(name + signature) < line_length:
+        return name + signature
 
     # Black cannot format names with dots, so we replace
     # the whole name with a string of equal length
-    name_length = code.index("(")
-    name = code[:name_length]
+    name_length = len(name)
     formatter = _get_black_formatter()
-    formatable = f"def {'x' * name_length}{code[name_length:]}: pass"
+    formatable = f"def {'x' * name_length}{signature}: pass"
     formatted = formatter(formatable, line_length)
 
     # We put back the original name
@@ -87,6 +80,33 @@ def do_format_signature(signature: str, line_length: int) -> str:
     return name + formatted[4:-5].strip()[name_length:-1]
 
 
+@pass_context
+def do_format_signature(
+    context: Context,
+    callable_path: Markup,
+    function: Function,
+    line_length: int,
+    *,
+    crossrefs: bool = False,  # noqa: ARG001
+) -> str:
+    """Format a signature using Black.
+
+    Parameters:
+        callable_path: The path of the callable we render the signature of.
+        line_length: The line length to give to Black.
+        crossrefs: Whether to cross-reference types in the signature.
+
+    Returns:
+        The same code, formatted.
+    """
+    env = context.environment
+    template = env.get_template("signature.html")
+    signature = template.render(context.parent, function=function)
+    signature = _format_signature(callable_path, signature, line_length)
+    signature = str(env.filters["highlight"](signature, language="python", inline=False))
+    return signature
+
+
 def do_order_members(
     members: Sequence[Object | Alias],
     order: Order,
@@ -228,3 +248,16 @@ def _get_black_formatter() -> Callable[[str, int], str]:
         return format_str(code, mode=mode)
 
     return formatter
+
+
+def do_get_template(obj: Object) -> str:
+    """Get the template name used to render an object.
+
+    Parameters:
+        obj: A Griffe object.
+
+    Returns:
+        A template name.
+    """
+    extra_data = getattr(obj, "extra", {}).get("mkdocstrings", {})
+    return extra_data.get("template", "") or f"{obj.kind.value}.html"

mkdocstrings_handlers/python/templates/material/_base/children.html

@@ -27,7 +27,7 @@
             {% with heading_level = heading_level + extra_level %}
               {% for attribute in attributes|order_members(config.members_order, members_list) %}
                 {% if not attribute.is_alias or attribute.is_explicitely_exported %}
-                  {% include "attribute.html" with context %}
+                  {% include attribute|get_template with context %}
                 {% endif %}
               {% endfor %}
             {% endwith %}
@@ -42,7 +42,7 @@
             {% with heading_level = heading_level + extra_level %}
               {% for class in classes|order_members(config.members_order, members_list) %}
                 {% if not class.is_alias or class.is_explicitely_exported %}
-                  {% include "class.html" with context %}
+                  {% include class|get_template with context %}
                 {% endif %}
               {% endfor %}
             {% endwith %}
@@ -58,7 +58,7 @@
               {% for function in functions|order_members(config.members_order, members_list) %}
                 {% if not (obj.kind.value == "class" and function.name == "__init__" and config.merge_init_into_class) %}
                   {% if not function.is_alias or function.is_explicitely_exported %}
-                    {% include "function.html" with context %}
+                    {% include function|get_template with context %}
                   {% endif %}
                 {% endif %}
               {% endfor %}
@@ -75,7 +75,7 @@
               {% with heading_level = heading_level + extra_level %}
                 {% for module in modules|order_members(config.members_order, members_list) %}
                   {% if not module.is_alias or module.is_explicitely_exported %}
-                    {% include "module.html" with context %}
+                    {% include module|get_template with context %}
                   {% endif %}
                 {% endfor %}
               {% endwith %}
@@ -91,26 +91,26 @@
           filter_objects(filters=config.filters, members_list=members_list, keep_no_docstrings=config.show_if_no_docstring)|
           order_members(config.members_order, members_list) %}
 
-        {% if not (obj.kind.value == "class" and child.name == "__init__" and config.merge_init_into_class) %}
+        {% if not (obj.is_class and child.name == "__init__" and config.merge_init_into_class) %}
 
-          {% if child.kind.value == "attribute" %}
+          {% if child.is_attribute %}
             {% with attribute = child %}
-              {% include "attribute.html" with context %}
+              {% include attribute|get_template with context %}
             {% endwith %}
 
-          {% elif child.kind.value == "class" %}
+          {% elif child.is_class %}
             {% with class = child %}
-              {% include "class.html" with context %}
+              {% include class|get_template with context %}
             {% endwith %}
 
-          {% elif child.kind.value == "function" %}
+          {% elif child.is_function %}
             {% with function = child %}
-              {% include "function.html" with context %}
+              {% include function|get_template with context %}
             {% endwith %}
 
-          {% elif child.kind.value == "module" and config.show_submodules %}
+          {% elif child.is_module and config.show_submodules %}
             {% with module = child %}
-              {% include "module.html" with context %}
+              {% include module|get_template with context %}
             {% endwith %}
 
           {% endif %}

mkdocstrings_handlers/python/templates/material/_base/class.html

@@ -43,11 +43,8 @@
     {% if config.separate_signature and config.merge_init_into_class %}
       {% if "__init__" in class.members %}
         {% with function = class.members["__init__"] %}
-          {% filter highlight(language="python", inline=False) %}
-            {% filter format_signature(config.line_length) %}
-              {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
-              {% include "signature.html" with context %}
-            {% endfilter %}
+          {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
+            {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
           {% endfilter %}
         {% endwith %}
       {% endif %}

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

@@ -7,6 +7,8 @@
   {{ original_expression }}
 {%- else -%}
   {%- with annotation = original_expression|attr(config.annotations_path) -%}
-    <span data-autorefs-optional{% if annotation != original_expression.full %}-hover{% endif %}="{{ original_expression.full }}">{{ annotation }}</span>
+    {%- filter stash_crossref(length=annotation|length) -%}
+      <span data-autorefs-optional{% if annotation != original_expression.full %}-hover{% endif %}="{{ original_expression.full }}">{{ annotation }}</span>
+    {%- endfilter -%}
   {%- endwith -%}
 {%- endif -%}

mkdocstrings_handlers/python/templates/material/_base/function.html

@@ -37,11 +37,8 @@
     {% endfilter %}
 
     {% if config.separate_signature %}
-      {% filter highlight(language="python", inline=False) %}
-        {% filter format_signature(config.line_length) %}
-          {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}
-          {% include "signature.html" with context %}
-        {% endfilter %}
+      {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
+        {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}
       {% endfilter %}
     {% endif %}
 

mkdocstrings_handlers/python/templates/material/_base/signature.html

@@ -2,7 +2,14 @@
   {{ log.debug("Rendering signature") }}
   {%- with -%}
 
-    {%- set ns = namespace(has_pos_only=False, render_pos_only_separator=True, render_kw_only_separator=True, equal="=") -%}
+    {%- set ns = namespace(
+          has_pos_only=False,
+          render_pos_only_separator=True,
+          render_kw_only_separator=True,
+          annotation="",
+          equal="=",
+        )
+    -%}
 
     {%- if config.show_signature_annotations -%}
       {%- set ns.equal = " = " -%}
@@ -24,7 +31,13 @@
           {%- endif -%}
 
           {%- if config.show_signature_annotations and parameter.annotation is not none -%}
-            {%- set annotation = ": " + parameter.annotation|safe -%}
+            {%- if config.separate_signature and config.signature_crossrefs -%}
+              {%- with expression = parameter.annotation -%}
+                {%- set ns.annotation -%}: {% include "expression.html" with context %}{%- endset -%}
+              {%- endwith -%}
+            {%- else -%}
+              {%- set ns.annotation = ": " + parameter.annotation|safe -%}
+            {%- endif -%}
           {%- endif -%}
 
           {%- if parameter.default is not none and parameter.kind.value != "variadic positional" and parameter.kind.value != "variadic keyword" -%}
@@ -36,13 +49,18 @@
           {%- endif -%}
 
           {% if parameter.kind.value == "variadic positional" %}*{% elif parameter.kind.value == "variadic keyword" %}**{% endif -%}
-          {{ parameter.name }}{{ annotation }}{{ default }}
+          {{ parameter.name }}{{ ns.annotation }}{{ default }}
           {%- if not loop.last %}, {% endif -%}
 
         {%- endif -%}
       {%- endfor -%}
     )
-    {%- if config.show_signature_annotations and function.annotation %} -> {{ function.annotation|safe }}{%- endif -%}
+    {%- if config.show_signature_annotations and function.annotation %} -> {% if config.separate_signature and config.signature_crossrefs -%}
+        {%- with expression = function.annotation %}{% include "expression.html" with context %}{%- endwith -%}
+      {%- else -%}
+        {{ function.annotation|safe }}
+      {%- endif -%}
+    {%- endif -%}
 
   {%- endwith -%}
 {%- endif -%}

{mkdocstrings_python-0.10.1.dist-info → mkdocstrings_python-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mkdocstrings-python
-Version: 0.10.1
+Version: 1.1.0
 Summary: A Python handler for mkdocstrings.
 Author-Email: Timothée Mazzucotelli <pawamoy@pm.me>
 License: ISC
@@ -25,8 +25,8 @@ Project-URL: Changelog, https://mkdocstrings.github.io/python/changelog
 Project-URL: Repository, https://github.com/mkdocstrings/python
 Project-URL: Issues, https://github.com/mkdocstrings/python/issues
 Project-URL: Discussions, https://github.com/mkdocstrings/python/discussions
-Project-URL: Gitter, https://gitter.im/python/community
-Project-URL: Funding, https://github.com/sponsors/mkdocstrings
+Project-URL: Gitter, https://gitter.im/mkdocstrings/python
+Project-URL: Funding, https://github.com/sponsors/pawamoy
 Requires-Python: >=3.7
 Requires-Dist: mkdocstrings>=0.20
 Requires-Dist: griffe>=0.24

{mkdocstrings_python-0.10.1.dist-info → mkdocstrings_python-1.1.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
 mkdocstrings_handlers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mkdocstrings_handlers/python/__init__.py,sha256=CJT3hmg9HpEMy5dbq2jL3Y8unO6UOHND7yCLojwQrS8,326
-mkdocstrings_handlers/python/handler.py,sha256=IllqOAKlYL2-XKtiEmUWQOiXM3VU2DMCi9J77JTSLgM,17613
-mkdocstrings_handlers/python/rendering.py,sha256=YuB7Gy6YfVxzczPrxHumzOos7FHPI2tqomV4hUPaJLY,6777
+mkdocstrings_handlers/python/handler.py,sha256=VKDSxsSCFMNsTJSox4VBHLFkqaHk4A7fzUQVli2OxK0,18098
+mkdocstrings_handlers/python/rendering.py,sha256=hjj64VBYJrQlVFF3jxwkla7nG5al6rXl0YH4AsHwPiY,7871
 mkdocstrings_handlers/python/templates/material/_base/attribute.html,sha256=JXn5axcd2ssBb02kzs9OVnKvo-UINOIC1ivsGpflIdc,2532
-mkdocstrings_handlers/python/templates/material/_base/children.html,sha256=-FKVAh62bJyqZ3T1R1lgtaRmIsZPnnuAfv-Lov1Hz50,5053
-mkdocstrings_handlers/python/templates/material/_base/class.html,sha256=z4eD-2rqRGsLQd6LdGOAVP52WAHWjEjvA6ZY8_R0ULY,4186
+mkdocstrings_handlers/python/templates/material/_base/children.html,sha256=NOf0LuqOXOg3SVEwwP8ARndWjZrk8q2o-1Ajrrp4dG0,5036
+mkdocstrings_handlers/python/templates/material/_base/class.html,sha256=wtTLXZl8gvOicdfxOCQaFt_59bn754C1k2ILbE4XvlE,4078
 mkdocstrings_handlers/python/templates/material/_base/docstring.html,sha256=LZu_zGw1YyGHN1fq-loPN9eKyYwC3rDWMyQbh31hD20,1740
 mkdocstrings_handlers/python/templates/material/_base/docstring/admonition.html,sha256=wiD2FtMnGrFMZJDilURnNqzIu8bOR0zcMErUVUqbDPo,274
 mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html,sha256=NwDp0mIyCnI43glTtFUbU7g0F0QismxyGPa7KV0ia3c,2465
@@ -16,11 +16,11 @@ mkdocstrings_handlers/python/templates/material/_base/docstring/receives.html,sh
 mkdocstrings_handlers/python/templates/material/_base/docstring/returns.html,sha256=EXaLJoz2vtQWVPAtQt2kbIw8xP3Y001vv9SIZvbZaMk,3081
 mkdocstrings_handlers/python/templates/material/_base/docstring/warns.html,sha256=8J7heEPD8IGNE-lr7mXAezB8RRWZ-YoUUdGnFl9FEpE,2115
 mkdocstrings_handlers/python/templates/material/_base/docstring/yields.html,sha256=43aDbTwzyGm4xyUf_p1T02MzsSHV_sNny2Se7KvPaqs,3051
-mkdocstrings_handlers/python/templates/material/_base/expression.html,sha256=UJ-o1AkXvcb8aaCxz2fxLb1U1oR2lqz0z4Fn7CgWa8k,590
-mkdocstrings_handlers/python/templates/material/_base/function.html,sha256=rYo2A7aPfZVtGklF7NlxOHR_9tTJIpHx_8lwR1bziXM,2532
+mkdocstrings_handlers/python/templates/material/_base/expression.html,sha256=up-Z_v7N7MAmj_UKfR8Xc9TJHnBggIxcQaMXmubzRt8,674
+mkdocstrings_handlers/python/templates/material/_base/function.html,sha256=_3-qihPbyZn9ijyUdJzfHSa1wA9NzCVzMx14Pq404EU,2436
 mkdocstrings_handlers/python/templates/material/_base/labels.html,sha256=Y85VylttZ7lYqtCjIjG3UjMaBNHWEiHEmfFMF6nyv6U,245
 mkdocstrings_handlers/python/templates/material/_base/module.html,sha256=M3tjXBpTriBekJdCgPhkmaqPsDblNai-aO85vPH9paA,1852
-mkdocstrings_handlers/python/templates/material/_base/signature.html,sha256=8FyNKyaFGyIBAkvln6ROKWsBHLDwp8rKErJaQIOL71E,2055
+mkdocstrings_handlers/python/templates/material/_base/signature.html,sha256=KcdvKEAhGeJvA7qVHo0wzGhcyEKxTGHepLf13C0gT1A,2698
 mkdocstrings_handlers/python/templates/material/attribute.html,sha256=Zbo0SMrqjdlUhXunXpy_VENWITviBDLt8UBdF5EnVb0,37
 mkdocstrings_handlers/python/templates/material/children.html,sha256=xLnVaXevA0HRffVdOK0INULbekvbOYV9vKQ_zXBLyK0,36
 mkdocstrings_handlers/python/templates/material/class.html,sha256=BGYm-uj8AEDiUZtNxr6ji7I1xFrlAiyOB7cOwM7gzEM,33
@@ -53,7 +53,7 @@ mkdocstrings_handlers/python/templates/readthedocs/parameters.html,sha256=c0pfsj
 mkdocstrings_handlers/python/templates/readthedocs/returns.html,sha256=1rvLz7n3xHkhc82mOCJdjgRpGGIFdJqhmiVpv9pdxBE,494
 mkdocstrings_handlers/python/templates/readthedocs/style.css,sha256=FNcAj6sgr1H8cg9MCkqlOMoYeM2EWExIRVRCmilL9YY,600
 mkdocstrings_handlers/python/templates/readthedocs/yields.html,sha256=QLl6geeYfOHJ3xwmuRl-rAScei0DtIxFmlSgVO53Hhc,490
-mkdocstrings_python-0.10.1.dist-info/METADATA,sha256=qnnpRtY8xeR5RcKLsyLbPBO05ap1W7rW5j_C4LSmUzE,5750
-mkdocstrings_python-0.10.1.dist-info/WHEEL,sha256=7dGFtUmOf30dPBLpGD2z643cxg89joO7p3JHBAwDv6E,90
-mkdocstrings_python-0.10.1.dist-info/licenses/LICENSE,sha256=JGb4pdPEM8TTjjhr-uNCO7oXkiVrwG5Pz0JamcjNF_s,754
-mkdocstrings_python-0.10.1.dist-info/RECORD,,
+mkdocstrings_python-1.1.0.dist-info/METADATA,sha256=aLxaWwtWx69109-NNM1s2QMyr7TnhWnC0fuZjWUub4c,5747
+mkdocstrings_python-1.1.0.dist-info/WHEEL,sha256=m6kf1fJuo48rT4uxh0SeA_FsGq51BpCh_8VNBKVwYQA,90
+mkdocstrings_python-1.1.0.dist-info/licenses/LICENSE,sha256=JGb4pdPEM8TTjjhr-uNCO7oXkiVrwG5Pz0JamcjNF_s,754
+mkdocstrings_python-1.1.0.dist-info/RECORD,,

{mkdocstrings_python-0.10.1.dist-info → mkdocstrings_python-1.1.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: pdm-backend (2.0.6)
+Generator: pdm-backend (2.0.7)
 Root-Is-Purelib: true
 Tag: py3-none-any