mkdocstrings-python 1.17.0__py3-none-any.whl → 1.18.1__py3-none-any.whl

mkdocstrings_handlers/python/__init__.py

@@ -22,12 +22,14 @@ from mkdocstrings_handlers.python._internal.rendering import (
     do_as_classes_section,
     do_as_functions_section,
     do_as_modules_section,
+    do_as_type_aliases_section,
     do_backlink_tree,
     do_crossref,
     do_filter_objects,
     do_format_attribute,
     do_format_code,
     do_format_signature,
+    do_format_type_alias,
     do_get_template,
     do_multi_crossref,
     do_order_members,
@@ -55,12 +57,14 @@ __all__ = [
     "do_as_classes_section",
     "do_as_functions_section",
     "do_as_modules_section",
+    "do_as_type_aliases_section",
     "do_backlink_tree",
     "do_crossref",
     "do_filter_objects",
     "do_format_attribute",
     "do_format_code",
     "do_format_signature",
+    "do_format_type_alias",
     "do_get_template",
     "do_multi_crossref",
     "do_order_members",

mkdocstrings_handlers/python/_internal/config.py

@@ -423,6 +423,15 @@ class SummaryOption:
         ),
     ] = False
 
+    type_aliases: Annotated[
+        bool,
+        _Field(
+            group="members",
+            parent="summary",
+            description="Whether to render summaries of type aliases.",
+        ),
+    ] = False
+
 
 # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
 @dataclass(**_dataclass_options)  # type: ignore[call-overload]
@@ -797,6 +806,22 @@ class PythonInputOptions:
         ),
     ] = True
 
+    show_docstring_type_aliases: Annotated[
+        bool,
+        _Field(
+            group="docstrings",
+            description="Whether to display the 'Type Aliases' section in the object's docstring.",
+        ),
+    ] = True
+
+    show_docstring_type_parameters: Annotated[
+        bool,
+        _Field(
+            group="docstrings",
+            description="Whether to display the 'Type Parameters' section in the object's docstring.",
+        ),
+    ] = True
+
     show_docstring_warns: Annotated[
         bool,
         _Field(
@@ -888,6 +913,14 @@ class PythonInputOptions:
         ),
     ] = False
 
+    show_signature_type_parameters: Annotated[
+        bool,
+        _Field(
+            group="signatures",
+            description="Show the type parameters in generic classes, methods, functions and type aliases signatures.",
+        ),
+    ] = False
+
     show_signature: Annotated[
         bool,
         _Field(
@@ -960,6 +993,14 @@ class PythonInputOptions:
         ),
     ] = ""
 
+    type_parameter_headings: Annotated[
+        bool,
+        _Field(
+            group="headings",
+            description="Whether to render headings for type parameters (therefore showing type parameters in the ToC).",
+        ),
+    ] = False
+
     unwrap_annotated: Annotated[
         bool,
         _Field(
@@ -1001,9 +1042,15 @@ class PythonInputOptions:
         if "summary" in data:
             summary = data["summary"]
             if summary is True:
-                summary = SummaryOption(attributes=True, functions=True, classes=True, modules=True)
+                summary = SummaryOption(attributes=True, functions=True, classes=True, modules=True, type_aliases=True)
             elif summary is False:
-                summary = SummaryOption(attributes=False, functions=False, classes=False, modules=False)
+                summary = SummaryOption(
+                    attributes=False,
+                    functions=False,
+                    classes=False,
+                    modules=False,
+                    type_aliases=False,
+                )
             else:
                 summary = SummaryOption(**summary)
             data["summary"] = summary
@@ -1028,7 +1075,7 @@ class PythonOptions(PythonInputOptions):  # type: ignore[override,unused-ignore]
     """A list of filters, or `"public"`."""
 
     summary: SummaryOption = field(default_factory=SummaryOption)
-    """Whether to render summaries of modules, classes, functions (methods) and attributes."""
+    """Whether to render summaries of modules, classes, functions (methods), attributes and type aliases."""
 
     @classmethod
     def coerce(cls, **data: Any) -> MutableMapping[str, Any]:

mkdocstrings_handlers/python/_internal/handler.py

@@ -322,12 +322,14 @@ class PythonHandler(BaseHandler):
         self.env.filters["format_code"] = rendering.do_format_code
         self.env.filters["format_signature"] = rendering.do_format_signature
         self.env.filters["format_attribute"] = rendering.do_format_attribute
+        self.env.filters["format_type_alias"] = rendering.do_format_type_alias
         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["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
+        self.env.filters["as_type_aliases_section"] = rendering.do_as_type_aliases_section
         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
@@ -408,6 +410,10 @@ def get_handler(
     Returns:
         An instance of `PythonHandler`.
     """
+    # In rare cases, Griffe hits the recursion limit because of deeply-nested ASTs.
+    # We therefore increase the limit here, once, before Griffe is used to collect or render stuff.
+    sys.setrecursionlimit(max(sys.getrecursionlimit(), 2000))
+
     base_dir = Path(tool_config.config_file_path or "./mkdocs.yml").parent
     if "inventories" not in handler_config and "import" in handler_config:
         warn("The 'import' key is renamed 'inventories' for the Python handler", FutureWarning, stacklevel=1)

mkdocstrings_handlers/python/_internal/rendering.py

@@ -28,7 +28,10 @@ from griffe import (
     DocstringSectionClasses,
     DocstringSectionFunctions,
     DocstringSectionModules,
+    DocstringSectionTypeAliases,
+    DocstringTypeAlias,
     Object,
+    TypeAlias,
 )
 from jinja2 import TemplateNotFound, pass_context, pass_environment
 from markupsafe import Markup
@@ -160,8 +163,10 @@ def do_format_signature(
         The same code, formatted.
     """
     env = context.environment
+    # YORE: Bump 2: Replace `do_get_template(env, "type_parameters")` with `"type_parameters.html.jinja"` within line.
+    type_params_template = env.get_template(do_get_template(env, "type_parameters"))
     # YORE: Bump 2: Replace `do_get_template(env, "signature")` with `"signature.html.jinja"` within line.
-    template = env.get_template(do_get_template(env, "signature"))
+    signature_template = env.get_template(do_get_template(env, "signature"))
 
     if annotations is None:
         new_context = context.parent
@@ -169,7 +174,9 @@ def do_format_signature(
         new_context = dict(context.parent)
         new_context["config"] = replace(new_context["config"], show_signature_annotations=annotations)
 
-    signature = template.render(new_context, function=function, signature=True)
+    signature = type_params_template.render(context.parent, obj=function, signature=True)
+    signature += signature_template.render(new_context, function=function, signature=True)
+
     signature = _format_signature(callable_path, signature, line_length)
     signature = str(
         env.filters["highlight"](
@@ -259,6 +266,67 @@ def do_format_attribute(
     return signature
 
 
+@pass_context
+def do_format_type_alias(
+    context: Context,
+    type_alias_path: Markup,
+    type_alias: TypeAlias,
+    line_length: int,
+    *,
+    crossrefs: bool = False,  # noqa: ARG001
+) -> str:
+    """Format a type alias.
+
+    Parameters:
+        context: Jinja context, passed automatically.
+        type_alias_path: The path of the type alias we render the signature of.
+        type_alias: The type alias we render the signature of.
+        line_length: The line length.
+        crossrefs: Whether to cross-reference types in the signature.
+
+    Returns:
+        The same code, formatted.
+    """
+    env = context.environment
+    # YORE: Bump 2: Replace `do_get_template(env, "type_parameters")` with `"type_parameters.html.jinja"` within line.
+    type_params_template = env.get_template(do_get_template(env, "type_parameters"))
+    # YORE: Bump 2: Replace `do_get_template(env, "expression")` with `"expression.html.jinja"` within line.
+    expr_template = env.get_template(do_get_template(env, "expression"))
+
+    signature = str(type_alias_path).strip()
+    signature += type_params_template.render(context.parent, obj=type_alias, signature=True)
+    value = expr_template.render(context.parent, expression=type_alias.value, signature=True)
+    signature += f" = {value}"
+
+    signature = do_format_code(signature, line_length)
+    signature = str(
+        env.filters["highlight"](
+            Markup.escape(signature),
+            language="python",
+            inline=False,
+            classes=["doc-signature"],
+            linenums=False,
+        ),
+    )
+
+    # Since we highlight the signature without `type`,
+    # Pygments sees only an assignment, not a type alias definition
+    # (at the moment it does not understand type alias definitions anyway).
+    # The result is that the type alias name is not parsed as such,
+    # 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 stash := env.filters["stash_crossref"].stash:
+        for key, value in stash.items():
+            signature = re.sub(rf"\b{key}\b", value, signature)
+        stash.clear()
+
+    return signature
+
+
 def do_order_members(
     members: Sequence[Object | Alias],
     order: Order | list[Order],
@@ -592,7 +660,7 @@ def do_get_template(env: Environment, obj: str | Object) -> str:
         extra_data = getattr(obj, "extra", {}).get("mkdocstrings", {})
         if name := extra_data.get("template", ""):
             return name
-        name = obj.kind.value
+        name = obj.kind.value.replace(" ", "_")
     # YORE: Bump 2: Replace block with `return f"{name}.html.jinja"`.
     try:
         template = env.get_template(f"{name}.html")
@@ -732,6 +800,34 @@ def do_as_modules_section(
     )
 
 
+@pass_context
+def do_as_type_aliases_section(
+    context: Context,  # noqa: ARG001
+    type_aliases: Sequence[TypeAlias],
+    *,
+    check_public: bool = True,
+) -> DocstringSectionTypeAliases:
+    """Build a type aliases section from a list of type aliases.
+
+    Parameters:
+        type_aliases: The type aliases to build the section from.
+        check_public: Whether to check if the type_alias is public.
+
+    Returns:
+        A type aliases docstring section.
+    """
+    return DocstringSectionTypeAliases(
+        [
+            DocstringTypeAlias(
+                name=type_alias.name,
+                description=type_alias.docstring.value.split("\n", 1)[0] if type_alias.docstring else "",
+            )
+            for type_alias in type_aliases
+            if not check_public or type_alias.is_public
+        ],
+    )
+
+
 class AutorefsHook(AutorefsHookInterface):
     """Autorefs hook.
 

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

@@ -57,6 +57,26 @@ Context:
           {% endif %}
         {% endwith %}
 
+        {% with type_aliases = obj.type_aliases|filter_objects(
+            filters=config.filters,
+            members_list=members_list,
+            inherited_members=config.inherited_members,
+            keep_no_docstrings=config.show_if_no_docstring,
+          ) %}
+          {% if type_aliases %}
+            {% if config.show_category_heading %}
+              {% filter heading(heading_level, id=html_id ~ "-type_aliases") %}Type Aliases{% endfilter %}
+            {% endif %}
+            {% with heading_level = heading_level + extra_level %}
+              {% for type_alias in type_aliases|order_members(config.members_order, members_list) %}
+                {% if config.filters == "public" or members_list is not none or (not type_alias.is_imported or type_alias.is_public) %}
+                  {% include type_alias|get_template with context %}
+                {% endif %}
+              {% endfor %}
+            {% endwith %}
+          {% endif %}
+        {% endwith %}
+
         {% with classes = obj.classes|filter_objects(
             filters=config.filters,
             members_list=members_list,
@@ -143,6 +163,11 @@ Context:
                 {% include attribute|get_template with context %}
               {% endwith %}
 
+            {% elif child.is_type_alias %}
+              {% with type_alias = child %}
+                {% include type_alias|get_template with context %}
+              {% endwith %}
+
             {% elif child.is_class %}
               {% with class = child %}
                 {% include class|get_template with context %}

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

@@ -54,12 +54,18 @@ Context:
             <span class="doc doc-object-name doc-class-name">{{ class_name }}</span>
           {% elif config.merge_init_into_class and "__init__" in all_members %}
             {% with function = all_members["__init__"] %}
-              {%+ filter highlight(language="python", inline=True) -%}
+              {%+ filter highlight(language="python", inline=True) %}
+                {{ class_name -}}
+                {%- with obj = function -%}
+                  {#- YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. -#}
+                  {%- include "type_parameters"|get_template with context -%}
+                {%- endwith -%}
                 {#- YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. -#}
-                {{ class_name }}{% include "signature"|get_template with context %}
-              {%- endfilter %}
+                {%- include "signature"|get_template with context -%}
+              {% endfilter %}
             {% endwith %}
           {% else %}
+            {# TODO: Maybe render type parameters here. #}
             <code>{{ class_name }}</code>
           {% endif %}
         {% endblock heading %}
@@ -83,26 +89,30 @@ Context:
         This block renders the signature for the class.
         Overloads of the `__init__` method are rendered if `merge_init_into_class` is enabled.
         The actual `__init__` method signature is only rendered if `separate_signature` is also enabled.
+
+        If the class is generic, but the `__init__` method isn't or `merge_init_into_class` is disabled,
+        the class signature is rendered if `separate_signature` and `show_signature_type_parameters` are enabled.
+
+        If the `__init__` method or any overloads are generic, they are rendered as methods if
+        `merge_init_into_class`, `separate_signature` and `show_signature_type_parameters` are enabled.
         -#}
-        {% if config.merge_init_into_class %}
-          {% if "__init__" in all_members %}
-            {% with function = all_members["__init__"] %}
-              {% if function.overloads and config.show_overloads %}
-                <div class="doc-overloads">
-                  {% for overload in function.overloads %}
-                    {% filter format_signature(overload, config.line_length, annotations=True, crossrefs=config.signature_crossrefs) %}
-                      {{ class.name }}
-                    {% endfilter %}
-                  {% endfor %}
-                </div>
-              {% endif %}
-              {% if config.separate_signature %}
-                {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
-                  {{ class.name }}
-                {% endfilter %}
-              {% endif %}
-            {% endwith %}
-          {% endif %}
+        {% if config.merge_init_into_class and "__init__" in all_members %}
+          {% with function = all_members["__init__"] %}
+            {% if function.overloads and config.show_overloads %}
+              <div class="doc-overloads">
+                {% for overload in function.overloads %}
+                  {% filter format_signature(overload, config.line_length, annotations=True, crossrefs=config.signature_crossrefs) %}
+                    {{ class.name }}
+                  {% endfilter %}
+                {% endfor %}
+              </div>
+            {% endif %}
+            {% if config.separate_signature and not (config.show_overloads and function.overloads and config.overloads_only) %}
+              {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %}
+                {{ class.name }}
+              {% endfilter %}
+            {% endif %}
+          {% endwith %}
         {% endif %}
       {% endblock signature %}
 

mkdocstrings_handlers/python/templates/material/_base/docstring/type_aliases.html

@@ -0,0 +1,10 @@
+{# YORE: Bump 2: Remove file. #}
+{% extends "_base/docstring/type_aliases.html.jinja" %}
+
+{% block logs scoped %}
+  {{ super() }}
+  {{ log.warning(
+        "DeprecationWarning: Extending '_base/docstring/type_aliases.html' is deprecated, extend '_base/docstring/type_aliases.html.jinja' instead. ",
+        once=True,
+      ) }}
+{% endblock logs %}

mkdocstrings_handlers/python/templates/material/_base/docstring/type_aliases.html.jinja

@@ -0,0 +1,86 @@
+{#- Template for "Type Aliases" sections in docstrings.
+
+This template renders a list of documented type aliases in the format
+specified with the [`docstring_section_style`][] configuration option.
+
+Context:
+  section (griffe.DocstringSectionTypeAliases): The section to render.
+-#}
+
+{% block logs scoped %}
+  {#- Logging block.
+
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
+  {{ log.debug("Rendering type aliases section") }}
+{% endblock logs %}
+
+{% import "language"|get_template as lang with context %}
+{#- Language module providing the `t` translation method. -#}
+
+{% if config.docstring_section_style == "table" %}
+  {% block table_style scoped %}
+    {#- Block for the `table` section style. -#}
+    <p><span class="doc-section-title">{{ section.title or lang.t("Type Aliases:") }}</span></p>
+    <table>
+      <thead>
+        <tr>
+          <th>{{ lang.t("Name") }}</th>
+          <th>{{ lang.t("Description") }}</th>
+        </tr>
+      </thead>
+      <tbody>
+        {% for type_alias in section.value %}
+          <tr class="doc-section-item">
+            <td><code><autoref identifier="{{ obj.path }}.{{ type_alias.name }}" optional hover>{{ type_alias.name }}</autoref></code></td>
+            <td>
+              <div class="doc-md-description">
+                {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+              </div>
+            </td>
+          </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+  {% endblock table_style %}
+{% elif config.docstring_section_style == "list" %}
+  {% block list_style scoped %}
+    {#- Block for the `list` section style. -#}
+    <p><span class="doc-section-title">{{ section.title or lang.t("Type Aliases:") }}</span></p>
+    <ul>
+      {% for type_alias in section.value %}
+        <li class="doc-section-item field-body">
+          <b><code><autoref identifier="{{ obj.path }}.{{ type_alias.name }}" optional hover>{{ type_alias.name }}</autoref></code></b>
+          –
+          <div class="doc-md-description">
+            {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+          </div>
+        </li>
+      {% endfor %}
+    </ul>
+  {% endblock list_style %}
+{% elif config.docstring_section_style == "spacy" %}
+  {% block spacy_style scoped %}
+    {#- Block for the `spacy` section style. -#}
+    <table>
+      <thead>
+        <tr>
+          <th><span class="doc-section-title">{{ (section.title or lang.t("TYPE ALIAS")).rstrip(":").upper() }}</span></th>
+          <th><span>{{ lang.t("DESCRIPTION") }}</span></th>
+        </tr>
+      </thead>
+      <tbody>
+        {% for type_alias in section.value %}
+          <tr class="doc-section-item">
+            <td><code><autoref identifier="{{ obj.path }}.{{ type_alias.name }}" optional hover>{{ type_alias.name }}</autoref></code></td>
+            <td class="doc-type_alias-details">
+              <div class="doc-md-description">
+                {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }}
+              </div>
+            </td>
+          </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+  {% endblock spacy_style %}
+{% endif %}

mkdocstrings_handlers/python/templates/material/_base/docstring/type_parameters.html

@@ -0,0 +1,10 @@
+{# YORE: Bump 2: Remove file. #}
+{% extends "_base/docstring/type_parameters.html.jinja" %}
+
+{% block logs scoped %}
+  {{ super() }}
+  {{ log.warning(
+        "DeprecationWarning: Extending '_base/docstring/type_parameters.html' is deprecated, extend '_base/docstring/type_parameters.html.jinja' instead. ",
+        once=True,
+      ) }}
+{% endblock logs %}