mkdocstrings-python 1.16.12__tar.gz → 1.18.0__tar.gz

{mkdocstrings_python-1.16.12 → mkdocstrings_python-1.18.0}/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.18.0](https://github.com/mkdocstrings/python/releases/tag/1.18.0) - 2025-08-26
+
+<small>[Compare with 1.17.0](https://github.com/mkdocstrings/python/compare/1.17.0...1.18.0)</small>
+
+### Features
+
+- Support PEP 695 generics ([dc8c3ad](https://github.com/mkdocstrings/python/commit/dc8c3adb23b37add6601de9e74085f76e5fc9ee5) by Victor Westerhuis). [PR-221](https://github.com/mkdocstrings/python/pull/221), Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr>
+
+### Bug Fixes
+
+- Increase maximum recursion limit in case of deeply nested ASTs (rare occurrence) ([6004ccf](https://github.com/mkdocstrings/python/commit/6004ccf3576c7a20e21c880bb2235b7b426ba382) by Timothée Mazzucotelli). [Issue-griffe-402](https://github.com/mkdocstrings/griffe/issues/402)
+
+## [1.17.0](https://github.com/mkdocstrings/python/releases/tag/1.17.0) - 2025-08-14
+
+<small>[Compare with 1.16.12](https://github.com/mkdocstrings/python/compare/1.16.12...1.17.0)</small>
+
+### Features
+
+- Support new Griffe parsing options `warn_missing_types` and `warnings` ([0e3bdb8](https://github.com/mkdocstrings/python/commit/0e3bdb857b5ede3e15aa7a9b8b87b33f68889c9e) by Timothée Mazzucotelli). [Issue-mkdocstrings-437](https://github.com/mkdocstrings/mkdocstrings/issues/437)
+- Add `skip_local_inventory` option to prevent objects from being registered in the local objects inventory ([e82c24f](https://github.com/mkdocstrings/python/commit/e82c24f17513fba4cff22e90f0a82c00a01a077d) by Bartosz Sławecki). [Issue-296](https://github.com/mkdocstrings/python/issues/296), [Issue-mkdocstrings-671](https://github.com/mkdocstrings/mkdocstrings/issues/671), [PR-297](https://github.com/mkdocstrings/python/pull/297)
+- Support hiding attribute values ([6cf34b9](https://github.com/mkdocstrings/python/commit/6cf34b9882e20d9147a6481e672ae09989a27796) by Bartosz Sławecki). Issue-292: #292, PR-293: #293
+- Support hiding implementation signature (showing overload only) ([d3b35e1](https://github.com/mkdocstrings/python/commit/d3b35e17384901e7280b8b6926f10fb033480358) by Bartosz Sławecki). [Issue-213](https://github.com/mkdocstrings/python/issues/213), [PR-286](https://github.com/mkdocstrings/python/pull/286)
+
+### Code Refactoring
+
+- Deprecate `locale` option in favor of mkdocstrings' ([17f71ba](https://github.com/mkdocstrings/python/commit/17f71babf11081869478b21b2bde1a33fc97be41) by Timothée Mazzucotelli). [PR-288](https://github.com/mkdocstrings/python/pull/288)
+
 ## [1.16.12](https://github.com/mkdocstrings/python/releases/tag/1.16.12) - 2025-06-03
 
 <small>[Compare with 1.16.11](https://github.com/mkdocstrings/python/compare/1.16.11...1.16.12)</small>

{mkdocstrings_python-1.16.12 → mkdocstrings_python-1.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-python
-Version: 1.16.12
+Version: 1.18.0
 Summary: A Python handler for mkdocstrings.
 Author-Email: =?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>
 License-Expression: ISC
@@ -30,9 +30,9 @@ Project-URL: Discussions, https://github.com/mkdocstrings/python/discussions
 Project-URL: Gitter, https://gitter.im/mkdocstrings/python
 Project-URL: Funding, https://github.com/sponsors/pawamoy
 Requires-Python: >=3.9
-Requires-Dist: mkdocstrings>=0.28.3
+Requires-Dist: mkdocstrings>=0.30
 Requires-Dist: mkdocs-autorefs>=1.4
-Requires-Dist: griffe>=1.6.2
+Requires-Dist: griffe>=1.13
 Requires-Dist: typing-extensions>=4.0; python_version < "3.11"
 Description-Content-Type: text/markdown
 

mkdocstrings_python-1.18.0/docs/snippets/package/generics.py

@@ -0,0 +1,49 @@
+"""Some module showing generics.
+
+Type Aliases:
+    SomeType: Some type alias.
+"""
+
+type SomeType[Z] = int | list[Z]
+"""Some type alias.
+
+Type parameters:
+    Z: Some type parameter.
+"""
+
+
+class MagicBag[T: (str, bytes) = str](list[T]):
+    """A magic bag of items.
+
+    Type parameters:
+        T: Some type.
+    """
+
+    def __init__[U: (int, bool)](self, *args: T, flag1: U | None = None, flag2: U | None = None) -> None:
+        """Initialize bag.
+
+        Type parameters:
+            U: Some flag type.
+
+        Parameters:
+            flag1: Some flag.
+            flag2: Some flag.
+        """
+        super().__init__(args)
+        self.flag1 = flag1
+        self.flag2 = flag2
+
+    def mutate[K](self, item: T, into: K) -> K:
+        """Shake the bag to mutate an item into something else (and eject it).
+
+        Type parameters:
+            K: Some other type.
+
+        Parameters:
+            item: The item to mutate.
+            into: Mutate the item into something like this.
+
+        Returns:
+            The mutated item.
+        """
+        ...

{mkdocstrings_python-1.16.12 → mkdocstrings_python-1.18.0}/docs/usage/configuration/docstrings.md

@@ -623,7 +623,7 @@ class ClassWithoutDocstring:
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
-Whether to render the "Attributes" sections of docstrings.
+Whether to render the "Attributes" section of docstrings.
 
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
@@ -676,7 +676,7 @@ class Class:
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
-Whether to render the "Functions" or "Methods" sections of docstrings.
+Whether to render the "Functions" or "Methods" section of docstrings.
 
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
@@ -751,7 +751,7 @@ class Class:
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
-Whether to render the "Classes" sections of docstrings.
+Whether to render the "Classes" section of docstrings.
 
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
@@ -804,13 +804,71 @@ class Class:
 ////
 ///
 
+[](){#option-show_docstring_type_aliases}
+## `show_docstring_type_aliases`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
+
+Whether to render the "Type Aliases" section of docstrings.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_docstring_type_aliases: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      show_docstring_type_aliases: false
+```
+
+```python
+"""Summary.
+
+Type Aliases:
+    TypeAlias: Some type alias.
+"""
+
+
+type TypeAlias = int
+"""Summary."""
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With type_aliases
+<h2>module</h2>
+<p>Summary.</p>
+<p><b>Type Aliases:</b></p>
+
+**Name**     | **Description**
+------------ | ----------------
+`TypeAlias`  | Some type alias.
+
+<h3><code>TypeAlias</code></h3>
+<p>Summary.</p>
+////
+
+//// tab | Without classes
+<h2>module</h2>
+<p>Summary.</p>
+<h3><code>TypeAlias</code></h3>
+<p>Summary.</p>
+////
+///
+
 [](){#option-show_docstring_modules}
 ## `show_docstring_modules`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
-Whether to render the "Modules" sections of docstrings.
+Whether to render the "Modules" section of docstrings.
 
 ```yaml title="in mkdocs.yml (global configuration)"
 plugins:
@@ -1245,6 +1303,57 @@ def rand() -> int:
 ////
 ///
 
+[](){#option-show_docstring_type_parameters}
+## `show_docstring_type_parameters`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Whether to render the "Type Parameters" section of docstrings.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_docstring_type_parameters: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      show_docstring_type_parameters: false
+```
+
+```python
+class AClass[X: (int, str) = str]:
+    """Represents something.
+
+    Type Parameters:
+        X: Something.
+    """
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With parameters
+<h2><code>AClass</code></h2>
+<p>Represents something.</p>
+<p><b>Type Parameters:</b></p>
+
+**Name**   | **Bound or Constraints** | **Description** | **Default**
+---------- | ------------------------ | --------------- | -----------
+`whatever` | `(int, str)`             | Something.      | `str`
+////
+
+//// tab | Without parameters
+<h2><code>AClass</code></h2>
+<p>Represents something.</p>
+////
+///
+
 [](){#option-show_docstring_warns}
 ## `show_docstring_warns`
 

{mkdocstrings_python-1.16.12 → mkdocstrings_python-1.18.0}/docs/usage/configuration/general.md

@@ -494,3 +494,63 @@ def some_function():
 <p>Docstring of the function.</p>
 ////
 ///
+
+[](){#option-skip_local_inventory}
+## `skip_local_inventory`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Whether to skip registering symbols in the objects inventory.
+
+With this option enabled, re-rendering docstrings for objects from external inventories is possible with their cross-references pointing to the original external inventory, not local. Similarly, it becomes possible to render the same symbol several times in the same documentation, with only one canonical location being used for cross-references (preventing confusion in mkdocs-autorefs).
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          skip_local_inventory: false
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      skip_local_inventory: true
+```
+
+/// admonition | Preview
+    type: preview
+
+
+//// tab | Without `skip_local_inventory`
+
+```md exec="on"
+::: bisect.bisect_left
+    options:
+      heading_level: 3
+      skip_local_inventory: false
+      show_docstring_description: false
+```
+
+Notice how [`bisect.bisect_left`][] now points to the section above.
+
+////
+
+//// tab | With `skip_local_inventory`
+
+```md exec="on"
+::: bisect.bisect_right
+    inventories:
+    - https://docs.python.org/3/objects.inv
+    options:
+      heading_level: 3
+      skip_local_inventory: true
+      show_docstring_description: false
+```
+
+Notice how [`bisect.bisect_right`][] points to the original Python documentation.
+
+////
+///

{mkdocstrings_python-1.16.12 → mkdocstrings_python-1.18.0}/docs/usage/configuration/headings.md

@@ -88,7 +88,7 @@ With this option enabled, each function/method parameter
 (including parameters of `__init__` methods merged in their parent class
 with the [`merge_init_into_class`][] option)
 gets a permalink, an entry in the Table of Contents,
-and an entry in the generated objects inventory.
+and an entry in the generated objects inventory (unless [`skip_local_inventory`][] is enabled).
 The permalink and inventory entry allow cross-references
 from internal and external pages.
 
@@ -682,3 +682,131 @@ NOTE: **Use with/without `heading`.** If you use this option without specifying
       heading: "My fancy module"
       toc_label: "My fancy module"
 ```
+
+[](){#option-type_parameter_headings}
+## `type_parameter_headings`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+
+Whether to render headings for generic class, function/method and type alias
+type parameters.
+
+With this option enabled, each type parameter of a generic object (including
+type parameters of `__init__` methods merged in their parent class with the
+[`merge_init_into_class`][] option) gets a permalink, an entry in the Table of
+Contents, and an entry in the generated objects inventory. The permalink and
+inventory entry allow cross-references from internal and external pages.
+
+<!-- TODO: Update when https://github.com/mkdocstrings/griffe/issues/404 is solved.
+The identifier used in the permalink and inventory is of the following form:
+`path.to.function:type_param_name`. To manually cross-reference a parameter,
+you can therefore use this Markdown syntax:
+
+```md
+- Class type parameter: [`Param`][package.module.Class[Param\]]
+- Method type parameter: [`Param`][package.module.Class.method[Param\]]
+- Function type parameter: [`Param`][package.module.function[Param\]]
+- Type alias type parameter: [`Param`][package.module.TypeAlias[Param\]]
+- Type variable tuple: [`*Args`][package.module.function[*Args\]]
+- Parameter specification: [`**Params`][package.module.function[**Params\]]
+```
+-->
+
+Enabling this option along with [`signature_crossrefs`][] will automatically
+render cross-references to type parameters in class/function/method/type alias
+signatures.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          type_parameter_headings: false
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      type_parameter_headings: true
+```
+
+/// admonition | Preview: Cross-references
+    type: preview
+
+```md exec="on"
+::: package.generics
+    options:
+      show_root_heading: false
+      heading_level: 3
+      docstring_section_style: list
+      show_bases: true
+      summary: false
+      separate_signature: true
+      show_signature_type_parameters: true
+      type_parameter_headings: true
+```
+
+///
+
+/// admonition | Preview: Type parameter sections
+    type: preview
+
+//// tab | Table style
+```md exec="on"
+::: package.generics.MagicBag
+    options:
+      members: false
+      heading_level: 3
+      show_root_heading: false
+      show_root_toc_entry: false
+      parameter_headings: true
+      docstring_section_style: table
+      show_docstring_description: false
+      show_docstring_parameters: false
+      show_docstring_returns: false
+```
+////
+
+//// tab | List style
+```md exec="on"
+::: package.generics.MagicBag
+    options:
+      members: false
+      heading_level: 3
+      show_root_heading: false
+      show_root_toc_entry: false
+      parameter_headings: true
+      docstring_section_style: list
+      show_docstring_description: false
+      show_docstring_parameters: false
+      show_docstring_returns: false
+```
+////
+
+//// tab | Spacy style
+```md exec="on"
+::: package.generics.MagicBag
+    options:
+      members: false
+      heading_level: 3
+      show_root_heading: false
+      show_root_toc_entry: false
+      parameter_headings: true
+      docstring_section_style: spacy
+      show_docstring_description: false
+      show_docstring_parameters: false
+      show_docstring_returns: false
+```
+////
+///
+
+/// admonition | Preview: Table of contents (with symbol types)
+    type: preview
+
+<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code> mutate<br>
+<code class="doc-symbol doc-symbol-toc doc-symbol-type_parameter" style="margin-left: 16px;"></code> U
+
+To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
+
+///

{mkdocstrings_python-1.16.12 → mkdocstrings_python-1.18.0}/docs/usage/configuration/members.md

@@ -585,7 +585,7 @@ package
 Whether to render summaries of modules, classes, functions (methods) and attributes.
 
 This option accepts a boolean (`yes`, `true`, `no`, `false` in YAML)
-or a dictionary with one or more of the following keys: `attributes`, `functions`, `classes`, `modules`,
+or a dictionary with one or more of the following keys: `attributes`, `functions`, `classes`, `modules`, `type_aliases`,
 with booleans as values. Class methods summary is (de)activated with the `functions` key.
 By default, `summary` is false, and by extension all values are false.
 

{mkdocstrings_python-1.16.12 → mkdocstrings_python-1.18.0}/docs/usage/configuration/signatures.md

@@ -286,6 +286,56 @@ plugins:
 
 ///
 
+[](){#option-overloads_only}
+## `overloads_only`
+
+Whether to hide the implementation signature if the overloads are shown with [`show_overloads`][].
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          overloads_only: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      overloads_only: true
+```
+
+/// admonition | Preview
+    type: preview
+//// tab | With overloads only
+<h2>function</h2>
+
+```python
+@overload
+function(param1: int): ...
+@overload
+function(param1: str): ...
+```
+Function docstring.
+
+////
+//// tab | Without overloads only
+<h2>function</h2>
+
+```python
+@overload
+function(param1: int): ...
+@overload
+function(param1: str): ...
+function(param1: str | int)
+```
+Function docstring.
+
+////
+
+///
+
 [](){#option-show_signature}
 ## `show_signature`
 
@@ -380,6 +430,61 @@ function(param1, param2=None)
 ////
 ///
 
+[](){#option-show_signature_type_parameters}
+## `show_signature_type_parameters`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Show the type parameters in generic classes, methods, functions and type aliases
+signatures.
+
+Since the heading can become quite long when type parameters are rendered, it is
+usually best to [separate the signature][separate_signature] from the heading.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          separate_signature: true
+          show_signature_annotations: true
+          show_signature_type_parameters: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      separate_signature: true
+      show_signature_annotations: true
+      show_signature_type_parameters: false
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With signature type parameters
+<h2>function</h2>
+
+```python
+function[T, *R](param: T) -> tuple[*R]
+```
+
+<p>Function docstring.</p>
+////
+
+//// tab | Without signature type parameters
+<h2>function</h2>
+
+```python
+function(param: T) -> tuple[*R]
+```
+
+<p>Function docstring.</p>
+////
+///
+
 [](){#option-separate_signature}
 ## `separate_signature`
 
@@ -433,6 +538,49 @@ function(param1, param2=None)
 ////
 ///
 
+[](){#option-show_attribute_values}
+## `show_attribute_values`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
+
+Show initial values of attributes in classes.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_attribute_values: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.object
+    options:
+      show_attribute_values: true
+```
+
+```python title="package/module.py"
+class SomeClass:
+  def __init__(self):
+      self.some_attr = 1
+```
+
+/// admonition | Preview
+    type: preview
+
+//// tab | With attribute values visible
+<h2><code>SomeClass</code></h2>
+<p>some_attr = 1</p>
+////
+
+//// tab | With attribute values hidden
+<h2><code>SomeClass</code></h2>
+<p>some_attr</p>
+////
+///
+
 [](){#option-show_overloads}
 ## `show_overloads`