mkdocstrings-python 1.16.12__py3-none-any.whl → 1.18.0__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

@@ -186,6 +186,24 @@ class GoogleStyleOptions:
         ),
     ] = True
 
+    warn_missing_types: Annotated[
+        bool,
+        _Field(
+            group="docstrings",
+            parent="docstring_options",
+            description="Warn about missing type/annotation for parameters, return values, etc.",
+        ),
+    ] = True
+
+    warnings: Annotated[
+        bool,
+        _Field(
+            group="docstrings",
+            parent="docstring_options",
+            description="Generally enable/disable warnings when parsing docstrings.",
+        ),
+    ] = True
+
 
 # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
 @dataclass(**_dataclass_options)  # type: ignore[call-overload]
@@ -219,12 +237,57 @@ class NumpyStyleOptions:
         ),
     ] = True
 
+    warn_missing_types: Annotated[
+        bool,
+        _Field(
+            group="docstrings",
+            parent="docstring_options",
+            description="Warn about missing type/annotation for parameters, return values, etc.",
+        ),
+    ] = True
+
+    warnings: Annotated[
+        bool,
+        _Field(
+            group="docstrings",
+            parent="docstring_options",
+            description="Generally enable/disable warnings when parsing docstrings.",
+        ),
+    ] = True
+
 
 # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
 @dataclass(**_dataclass_options)  # type: ignore[call-overload]
 class SphinxStyleOptions:
     """Sphinx style docstring options."""
 
+    warn_unknown_params: Annotated[
+        bool,
+        _Field(
+            group="docstrings",
+            parent="docstring_options",
+            description="Warn about documented parameters not appearing in the signature.",
+        ),
+    ] = True
+
+    warn_missing_types: Annotated[
+        bool,
+        _Field(
+            group="docstrings",
+            parent="docstring_options",
+            description="Warn about missing type/annotation for return values.",
+        ),
+    ] = True
+
+    warnings: Annotated[
+        bool,
+        _Field(
+            group="docstrings",
+            parent="docstring_options",
+            description="Generally enable/disable warnings when parsing docstrings.",
+        ),
+    ] = True
+
 
 # YORE: EOL 3.9: Replace `**_dataclass_options` with `frozen=True, kw_only=True` within line.
 @dataclass(**_dataclass_options)  # type: ignore[call-overload]
@@ -360,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]
@@ -554,6 +626,14 @@ class PythonInputOptions:
         ),
     ] = False
 
+    overloads_only: Annotated[
+        bool,
+        _Field(
+            group="signatures",
+            description="Whether to hide the implementation signature if the overloads are shown.",
+        ),
+    ] = False
+
     parameter_headings: Annotated[
         bool,
         _Field(
@@ -614,6 +694,14 @@ class PythonInputOptions:
         ),
     ] = False
 
+    show_attribute_values: Annotated[
+        bool,
+        _Field(
+            group="signatures",
+            description="Show initial values of attributes in classes.",
+        ),
+    ] = True
+
     show_bases: Annotated[
         bool,
         _Field(
@@ -718,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(
@@ -809,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(
@@ -849,6 +961,14 @@ class PythonInputOptions:
         ),
     ] = False
 
+    skip_local_inventory: Annotated[
+        bool,
+        _Field(
+            group="general",
+            description="Whether to prevent objects from being registered in the local objects inventory.",
+        ),
+    ] = False
+
     signature_crossrefs: Annotated[
         bool,
         _Field(
@@ -873,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(
@@ -914,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
@@ -941,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]:
@@ -1019,7 +1153,9 @@ class PythonInputConfig:
 
     locale: Annotated[
         str | None,
-        _Field(description="The locale to use when translating template strings."),
+        _Field(
+            description="Deprecated. Use mkdocstrings' own `locale` setting instead. The locale to use when translating template strings.",
+        ),
     ] = None
 
     @classmethod

mkdocstrings_handlers/python/_internal/handler.py

@@ -278,12 +278,13 @@ class PythonHandler(BaseHandler):
 
         return doc_object
 
-    def render(self, data: CollectorItem, options: PythonOptions) -> str:
+    def render(self, data: CollectorItem, options: PythonOptions, locale: str | None = None) -> str:
         """Render the collected data.
 
         Parameters:
             data: The collected data.
             options: The options to use for rendering.
+            locale: The locale to use for rendering (default is "en").
 
         Returns:
             The rendered data (HTML).
@@ -300,7 +301,8 @@ class PythonHandler(BaseHandler):
                 # than as an item in a dictionary.
                 "heading_level": options.heading_level,
                 "root": True,
-                "locale": self.config.locale,
+                # YORE: Bump 2: Regex-replace ` or .+` with ` or "en",` within line.
+                "locale": locale or self.config.locale,
             },
         )
 
@@ -320,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
@@ -360,7 +364,7 @@ class PythonHandler(BaseHandler):
             return tuple(f"{alias}({parameter})" for alias in aliases)
         return tuple(aliases)
 
-    def normalize_extension_paths(self, extensions: Sequence) -> Sequence:
+    def normalize_extension_paths(self, extensions: Sequence) -> list[str | dict[str, Any]]:
         """Resolve extension paths relative to config file.
 
         Parameters:
@@ -369,7 +373,7 @@ class PythonHandler(BaseHandler):
         Returns:
             The normalized extensions.
         """
-        normalized = []
+        normalized: list[str | dict[str, Any]] = []
 
         for ext in extensions:
             if isinstance(ext, dict):
@@ -401,10 +405,15 @@ def get_handler(
     Parameters:
         handler_config: The handler configuration.
         tool_config: The tool (SSG) configuration.
+        **kwargs: Additional arguments to pass to the 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"](
@@ -208,6 +215,7 @@ def do_format_attribute(
     line_length: int,
     *,
     crossrefs: bool = False,  # noqa: ARG001
+    show_value: bool = True,
 ) -> str:
     """Format an attribute.
 
@@ -235,7 +243,7 @@ def do_format_attribute(
             backlink_type="returned-by",
         )
         signature += f": {annotation}"
-    if attribute.value:
+    if show_value and attribute.value:
         value = template.render(context.parent, expression=attribute.value, signature=True, backlink_type="used-by")
         signature += f" = {value}"
 
@@ -258,10 +266,71 @@ 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],
-    members_list: bool | list[str] | None,
+    members_list: bool | list[str] | None,  # noqa: FBT001
 ) -> Sequence[Object | Alias]:
     """Order members given an ordering method.
 
@@ -522,7 +591,7 @@ def _get_formatter() -> Callable[[str, int], str]:
 
 def _get_ruff_formatter() -> Callable[[str, int], str] | None:
     try:
-        from ruff.__main__ import find_ruff_bin
+        from ruff.__main__ import find_ruff_bin  # noqa: PLC0415
     except ImportError:
         return None
 
@@ -558,7 +627,7 @@ def _get_ruff_formatter() -> Callable[[str, int], str] | None:
 
 def _get_black_formatter() -> Callable[[str, int], str] | None:
     try:
-        from black import InvalidInput, Mode, format_str
+        from black import InvalidInput, Mode, format_str  # noqa: PLC0415
     except ModuleNotFoundError:
         return None
 
@@ -591,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")
@@ -638,7 +707,7 @@ def do_as_attributes_section(
                 name=attribute.name,
                 description=_parse_docstring_summary(attribute),
                 annotation=attribute.annotation,
-                value=attribute.value,  # type: ignore[arg-type]
+                value=attribute.value,
             )
             for attribute in attributes
             if not check_public or attribute.is_public
@@ -731,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/attribute.html.jinja

@@ -40,6 +40,7 @@ Context:
           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),
+          skip_inventory=config.skip_local_inventory,
         ) %}
 
         {% block heading scoped %}
@@ -55,7 +56,7 @@ Context:
           {% else %}
             {%+ filter highlight(language="python", inline=True) %}
               {{ attribute_name }}{% if attribute.annotation and config.show_signature_annotations %}: {{ attribute.annotation }}{% endif %}
-              {% if attribute.value %} = {{ attribute.value }}{% endif %}
+              {% if config.show_attribute_values and attribute.value %} = {{ attribute.value }}{% endif %}
             {% endfilter %}
           {% endif %}
         {% endblock heading %}
@@ -79,7 +80,7 @@ Context:
         This block renders the signature for the attribute.
         -#}
         {% if config.separate_signature %}
-          {% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs) %}
+          {% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs, show_value=config.show_attribute_values) %}
             {{ attribute.name }}
           {% endfilter %}
         {% endif %}
@@ -93,6 +94,7 @@ Context:
             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,
+            skip_inventory=config.skip_local_inventory,
           ) %}
         {% endfilter %}
       {% endif %}

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

@@ -45,7 +45,7 @@ Context:
           ) %}
           {% if attributes %}
             {% if config.show_category_heading %}
-              {% filter heading(heading_level, id=html_id ~ "-attributes") %}Attributes{% endfilter %}
+              {% filter heading(heading_level, id=html_id ~ "-attributes", skip_inventory=config.skip_local_inventory) %}Attributes{% endfilter %}
             {% endif %}
             {% with heading_level = heading_level + extra_level %}
               {% for attribute in attributes|order_members(config.members_order, members_list) %}
@@ -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,
@@ -65,7 +85,7 @@ Context:
           ) %}
           {% if classes %}
             {% if config.show_category_heading %}
-              {% filter heading(heading_level, id=html_id ~ "-classes") %}Classes{% endfilter %}
+              {% filter heading(heading_level, id=html_id ~ "-classes", skip_inventory=config.skip_local_inventory) %}Classes{% endfilter %}
             {% endif %}
             {% with heading_level = heading_level + extra_level %}
               {% for class in classes|order_members(config.members_order, members_list) %}
@@ -85,7 +105,7 @@ Context:
           ) %}
           {% if functions %}
             {% if config.show_category_heading %}
-              {% filter heading(heading_level, id=html_id ~ "-functions") %}Functions{% endfilter %}
+              {% filter heading(heading_level, id=html_id ~ "-functions", skip_inventory=config.skip_local_inventory) %}Functions{% endfilter %}
             {% endif %}
             {% with heading_level = heading_level + extra_level %}
               {% for function in functions|order_members(config.members_order, members_list) %}
@@ -108,7 +128,7 @@ Context:
             ) %}
             {% if modules %}
               {% if config.show_category_heading %}
-                {% filter heading(heading_level, id=html_id ~ "-modules") %}Modules{% endfilter %}
+                {% filter heading(heading_level, id=html_id ~ "-modules", skip_inventory=config.skip_local_inventory) %}Modules{% endfilter %}
               {% endif %}
               {% with heading_level = heading_level + extra_level %}
                 {% for module in modules|order_members("alphabetical", 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 %}