mkdocstrings-python 1.16.6__py3-none-any.whl → 1.16.8__py3-none-any.whl

mkdocstrings_handlers/python/_internal/config.py

@@ -9,6 +9,8 @@ from typing import TYPE_CHECKING, Annotated, Any, Literal
 
 from mkdocstrings import get_logger
 
+from mkdocstrings_handlers.python._internal.rendering import Order  # noqa: TC001
+
 # YORE: EOL 3.10: Replace block with line 2.
 if sys.version_info >= (3, 11):
     from typing import Self
@@ -432,14 +434,24 @@ class PythonInputOptions:
     ] = field(default_factory=list)
 
     filters: Annotated[
-        list[str],
+        list[str] | Literal["public"],
         _Field(
             group="members",
-            description="""A list of filters applied to filter objects based on their name.
+            description="""A list of filters, or `"public"`.
+
+            **List of filters**
 
             A filter starting with `!` will exclude matching objects instead of including them.
             The `members` option takes precedence over `filters` (filters will still be applied recursively
             to lower members in the hierarchy).
+
+            **Filtering methods**
+
+            [:octicons-heart-fill-24:{ .pulse } Sponsors only](../insiders/index.md){ .insiders } —
+            [:octicons-tag-24: Insiders 1.11.0](../insiders/changelog.md#1.11.0)
+
+            The `public` method will include only public objects:
+            those added to `__all__` or not starting with an underscore (except for special methods/attributes).
             """,
         ),
     ] = field(default_factory=lambda: _DEFAULT_FILTERS.copy())
@@ -510,13 +522,18 @@ class PythonInputOptions:
     ] = None
 
     members_order: Annotated[
-        Literal["alphabetical", "source"],
+        Order | list[Order],
         _Field(
             group="members",
             description="""The members ordering to use.
 
-            - `alphabetical`: order by the members names,
+            - `__all__`: order members according to `__all__` module attributes, if declared;
+            - `alphabetical`: order members alphabetically;
             - `source`: order members as they appear in the source file.
+
+            Since `__all__` is a module-only attribute, it can't be used to sort class members,
+            therefore the `members_order` option accepts a list of ordering methods,
+            indicating ordering preferences.
             """,
         ),
     ] = "alphabetical"
@@ -916,12 +933,12 @@ class PythonInputOptions:
 class PythonOptions(PythonInputOptions):  # type: ignore[override,unused-ignore]
     """Final options passed as template context."""
 
-    filters: list[tuple[re.Pattern, bool]] = field(  # type: ignore[assignment]
+    filters: list[tuple[re.Pattern, bool]] | Literal["public"] = field(  # type: ignore[assignment]
         default_factory=lambda: [
             (re.compile(filtr.removeprefix("!")), filtr.startswith("!")) for filtr in _DEFAULT_FILTERS
         ],
     )
-    """A list of filters applied to filter objects based on their name."""
+    """A list of filters, or `"public"`."""
 
     summary: SummaryOption = field(default_factory=SummaryOption)
     """Whether to render summaries of modules, classes, functions (methods) and attributes."""
@@ -930,6 +947,11 @@ class PythonOptions(PythonInputOptions):  # type: ignore[override,unused-ignore]
     def coerce(cls, **data: Any) -> MutableMapping[str, Any]:
         """Create an instance from a dictionary."""
         if "filters" in data:
+            # Non-insiders: transform back to default filters.
+            # Next: `if "filters" in data and not isinstance(data["filters"], str):`.
+            if data["filters"] == "public":
+                data["filters"] = _DEFAULT_FILTERS
+            # Filters are `None` or a sequence of strings (tests use tuples).
             data["filters"] = [
                 (re.compile(filtr.removeprefix("!")), filtr.startswith("!")) for filtr in data["filters"] or ()
             ]

mkdocstrings_handlers/python/_internal/rendering.py

@@ -9,6 +9,7 @@ import subprocess
 import sys
 import warnings
 from collections import defaultdict
+from contextlib import suppress
 from dataclasses import replace
 from functools import lru_cache
 from pathlib import Path
@@ -17,6 +18,8 @@ from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal, TypeVar
 
 from griffe import (
     Alias,
+    AliasResolutionError,
+    CyclicAliasError,
     DocstringAttribute,
     DocstringClass,
     DocstringFunction,
@@ -43,26 +46,35 @@ if TYPE_CHECKING:
 _logger = get_logger(__name__)
 
 
-def _sort_key_alphabetical(item: CollectorItem) -> Any:
-    # chr(sys.maxunicode) is a string that contains the final unicode
-    # character, so if 'name' isn't found on the object, the item will go to
-    # the end of the list.
+def _sort_key_alphabetical(item: CollectorItem) -> str:
+    # `chr(sys.maxunicode)` is a string that contains the final unicode character,
+    # so if `name` isn't found on the object, the item will go to the end of the list.
     return item.name or chr(sys.maxunicode)
 
 
-def _sort_key_source(item: CollectorItem) -> Any:
-    # if 'lineno' is none, the item will go to the start of the list.
+def _sort_key_source(item: CollectorItem) -> float:
+    # If `lineno` is none, the item will go to the end of the list.
     if item.is_alias:
-        return item.alias_lineno if item.alias_lineno is not None else -1
-    return item.lineno if item.lineno is not None else -1
+        return item.alias_lineno if item.alias_lineno is not None else float("inf")
+    return item.lineno if item.lineno is not None else float("inf")
 
 
-Order = Literal["alphabetical", "source"]
-"""Ordering methods."""
+def _sort__all__(item: CollectorItem) -> float:  # noqa: ARG001
+    raise ValueError("Not implemented in public version of mkdocstrings-python")
 
-_order_map = {
+
+Order = Literal["__all__", "alphabetical", "source"]
+"""Ordering methods.
+
+- `__all__`: order members according to `__all__` module attributes, if declared;
+- `alphabetical`: order members alphabetically;
+- `source`: order members as they appear in the source file.
+"""
+
+_order_map: dict[str, Callable[[Object | Alias], str | float]] = {
     "alphabetical": _sort_key_alphabetical,
     "source": _sort_key_source,
+    "__all__": _sort__all__,
 }
 
 
@@ -148,7 +160,7 @@ def do_format_signature(
         The same code, formatted.
     """
     env = context.environment
-    # YORE: Bump 2: Replace `do_get_template(env, "signature")` with `"signature.html.jinja"`.
+    # YORE: Bump 2: Replace `do_get_template(env, "signature")` with `"signature.html.jinja"` within line.
     template = env.get_template(do_get_template(env, "signature"))
 
     if annotations is None:
@@ -208,7 +220,7 @@ def do_format_attribute(
         The same code, formatted.
     """
     env = context.environment
-    # YORE: Bump 2: Replace `do_get_template(env, "expression")` with `"expression.html.jinja"`.
+    # YORE: Bump 2: Replace `do_get_template(env, "expression")` with `"expression.html.jinja"` within line.
     template = env.get_template(do_get_template(env, "expression"))
     annotations = context.parent["config"].show_signature_annotations
 
@@ -246,7 +258,7 @@ def do_format_attribute(
 
 def do_order_members(
     members: Sequence[Object | Alias],
-    order: Order,
+    order: Order | list[Order],
     members_list: bool | list[str] | None,
 ) -> Sequence[Object | Alias]:
     """Order members given an ordering method.
@@ -266,7 +278,12 @@ def do_order_members(
             if name in members_dict:
                 sorted_members.append(members_dict[name])
         return sorted_members
-    return sorted(members, key=_order_map[order])
+    if isinstance(order, str):
+        order = [order]
+    for method in order:
+        with suppress(ValueError):
+            return sorted(members, key=_order_map[method])
+    return members
 
 
 # YORE: Bump 2: Remove block.
@@ -396,10 +413,33 @@ def _keep_object(name: str, filters: Sequence[tuple[Pattern, bool]]) -> bool:
     return keep
 
 
+def _parents(obj: Alias) -> set[str]:
+    parent: Object | Alias = obj.parent  # type: ignore[assignment]
+    parents = {obj.path, parent.path}
+    if parent.is_alias:
+        parents.add(parent.final_target.path)  # type: ignore[union-attr]
+    while parent.parent:
+        parent = parent.parent
+        parents.add(parent.path)
+        if parent.is_alias:
+            parents.add(parent.final_target.path)  # type: ignore[union-attr]
+    return parents
+
+
+def _remove_cycles(objects: list[Object | Alias]) -> Iterator[Object | Alias]:
+    suppress_errors = suppress(AliasResolutionError, CyclicAliasError)
+    for obj in objects:
+        if obj.is_alias:
+            with suppress_errors:
+                if obj.final_target.path in _parents(obj):  # type: ignore[arg-type,union-attr]
+                    continue
+        yield obj
+
+
 def do_filter_objects(
     objects_dictionary: dict[str, Object | Alias],
     *,
-    filters: Sequence[tuple[Pattern, bool]] | None = None,
+    filters: Sequence[tuple[Pattern, bool]] | Literal["public"] | None = None,
     members_list: bool | list[str] | None = None,
     inherited_members: bool | list[str] = False,
     keep_no_docstrings: bool = True,
@@ -408,7 +448,7 @@ def do_filter_objects(
 
     Parameters:
         objects_dictionary: The dictionary of objects.
-        filters: Filters to apply, based on members' names.
+        filters: Filters to apply, based on members' names, or `"public"`.
             Each element is a tuple: a pattern, and a boolean indicating whether
             to reject the object if the pattern matches.
         members_list: An optional, explicit list of members to keep.
@@ -449,14 +489,20 @@ def do_filter_objects(
         ]
 
     # Use filters and docstrings.
-    if filters:
+    if filters == "public":
+        objects = [obj for obj in objects if obj.is_public]
+    elif filters:
         objects = [
             obj for obj in objects if _keep_object(obj.name, filters) or (inherited_members_specified and obj.inherited)
         ]
-    if keep_no_docstrings:
-        return objects
+    if not keep_no_docstrings:
+        objects = [obj for obj in objects if obj.has_docstrings or (inherited_members_specified and obj.inherited)]
+
+    # Prevent infinite recursion.
+    if objects:
+        objects = list(_remove_cycles(objects))
 
-    return [obj for obj in objects if obj.has_docstrings or (inherited_members_specified and obj.inherited)]
+    return objects
 
 
 @lru_cache(maxsize=1)

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

@@ -49,7 +49,7 @@ Context:
             {% endif %}
             {% with heading_level = heading_level + extra_level %}
               {% for attribute in attributes|order_members(config.members_order, members_list) %}
-                {% if members_list is not none or (not attribute.is_imported or attribute.is_public) %}
+                {% if config.filters == "public" or members_list is not none or (not attribute.is_imported or attribute.is_public) %}
                   {% include attribute|get_template with context %}
                 {% endif %}
               {% endfor %}
@@ -69,7 +69,7 @@ Context:
             {% endif %}
             {% with heading_level = heading_level + extra_level %}
               {% for class in classes|order_members(config.members_order, members_list) %}
-                {% if members_list is not none or (not class.is_imported or class.is_public) %}
+                {% if config.filters == "public" or members_list is not none or (not class.is_imported or class.is_public) %}
                   {% include class|get_template with context %}
                 {% endif %}
               {% endfor %}
@@ -90,7 +90,7 @@ Context:
             {% with heading_level = heading_level + extra_level %}
               {% 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 members_list is not none or (not function.is_imported or function.is_public) %}
+                  {% if config.filters == "public" or members_list is not none or (not function.is_imported or function.is_public) %}
                     {% include function|get_template with context %}
                   {% endif %}
                 {% endif %}
@@ -112,7 +112,7 @@ Context:
               {% endif %}
               {% with heading_level = heading_level + extra_level %}
                 {% for module in modules|order_members("alphabetical", members_list) %}
-                  {% if members_list is not none or (not module.is_alias or module.is_public) %}
+                  {% if config.filters == "public" or members_list is not none or (not module.is_alias or module.is_public) %}
                     {% include module|get_template with context %}
                   {% endif %}
                 {% endfor %}
@@ -137,7 +137,7 @@ Context:
 
         {% if not (obj.is_class and child.name == "__init__" and config.merge_init_into_class) %}
 
-          {% if members_list is not none or child.is_public %}
+          {% if config.filters == "public" or members_list is not none or child.is_public %}
             {% if child.is_attribute %}
               {% with attribute = child %}
                 {% include attribute|get_template with context %}

{mkdocstrings_python-1.16.6.dist-info → mkdocstrings_python-1.16.8.dist-info}/METADATA

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

{mkdocstrings_python-1.16.6.dist-info → mkdocstrings_python-1.16.8.dist-info}/RECORD

@@ -1,9 +1,9 @@
 mkdocstrings_handlers/python/__init__.py,sha256=lg-XSQYS-o5J9_jBU35SA7rCW54CK0JsNcrSgsCfW2k,1614
 mkdocstrings_handlers/python/_internal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mkdocstrings_handlers/python/_internal/config.py,sha256=l0Rm5hH5kr39ihXcNNTCcetgSZpLfa6-rcQimpigIPo,32341
+mkdocstrings_handlers/python/_internal/config.py,sha256=JR6GVLLdVpCyCzjpJpFIY_bsQwQmo76PSlZCx28bUbQ,33469
 mkdocstrings_handlers/python/_internal/debug.py,sha256=KnkMM_XSjcE0-9U86AZPucS2hsCD6Rfn_BgMs7_xc3U,2845
 mkdocstrings_handlers/python/_internal/handler.py,sha256=FqIQzxz8k1COAlCzNlKlTzDlbEctXq77kaCxfl2-ILI,15976
-mkdocstrings_handlers/python/_internal/rendering.py,sha256=ufs6hCv12rjwRjLg6D86Dj0FE-wFA4Y7a5LBBlGMW-s,24717
+mkdocstrings_handlers/python/_internal/rendering.py,sha256=HeRIgG8g7eeqfZLx9bOavLmKgDtlMW_FuzWvP_k2epU,26493
 mkdocstrings_handlers/python/config.py,sha256=gDuOF8vYwo00opwtObQ55WQq2ECynirwcaGnd0VCHg4,477
 mkdocstrings_handlers/python/handler.py,sha256=xZnhzVC_y6ni3eX_RRO8132ED7DqXqU7IjA6sm8lCk8,480
 mkdocstrings_handlers/python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -12,7 +12,7 @@ mkdocstrings_handlers/python/templates/material/_base/attribute.html,sha256=M_eH
 mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja,sha256=1XPaM8_PgtyP_3dB66N3-ujTkaBfqoQ_tD4k9cIy2mQ,4754
 mkdocstrings_handlers/python/templates/material/_base/backlinks.html.jinja,sha256=FFrvIa-KH-DhT1cpc9HL0ecShR2gUVGs3VT9c1q88z8,467
 mkdocstrings_handlers/python/templates/material/_base/children.html,sha256=EQuTDoMRrICrieD62VZ9Ay-tw3sJQe4Jh7yDnFe1zFk,307
-mkdocstrings_handlers/python/templates/material/_base/children.html.jinja,sha256=Bu5dsIKcf5bX0_VzfSADmHvxXlY6K8wYBvXtuXtKVsU,6391
+mkdocstrings_handlers/python/templates/material/_base/children.html.jinja,sha256=JKQtXVemw8SJ1lPbCw_BNUKDnbtvnqzmC5cwhiYqxow,6541
 mkdocstrings_handlers/python/templates/material/_base/class.html,sha256=phAElLOLdaCRMW7uv1G5ePW3deavBpCp29OsK2Njn6E,298
 mkdocstrings_handlers/python/templates/material/_base/class.html.jinja,sha256=7dELSZWSA7cRMLxS_tkIQ_te76aWrfbqRaebsG2ozU0,9633
 mkdocstrings_handlers/python/templates/material/_base/docstring.html,sha256=x2JcxMNtM0xc1qZv1cKJQv4svNXyFThtKLJ66YqFHAQ,310
@@ -184,8 +184,8 @@ mkdocstrings_handlers/python/templates/readthedocs/languages/ja.html.jinja,sha25
 mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html,sha256=OIRkMlzFJ_wlXFzB96874tz6zn8UVFpEQX2hQJru2ug,79
 mkdocstrings_handlers/python/templates/readthedocs/languages/zh.html.jinja,sha256=OuvrkorxuL0gKZNYneann1bwd1Z2i5bBY7SbC496HDw,46
 mkdocstrings_handlers/python/templates/readthedocs/style.css,sha256=Ds8vF1rSxc2B0c4P10osx4cqXHWMntcSCxmRfX-nfzw,971
-mkdocstrings_python-1.16.6.dist-info/METADATA,sha256=Z3VnNpCHQb3t3d6oGeOeZUxPzb9mkDmhw4DAZs8KTYI,5605
-mkdocstrings_python-1.16.6.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
-mkdocstrings_python-1.16.6.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
-mkdocstrings_python-1.16.6.dist-info/licenses/LICENSE,sha256=JGb4pdPEM8TTjjhr-uNCO7oXkiVrwG5Pz0JamcjNF_s,754
-mkdocstrings_python-1.16.6.dist-info/RECORD,,
+mkdocstrings_python-1.16.8.dist-info/METADATA,sha256=hHVMSm5LbNhVPfh3so46jjrVLkiqPHWxTn6oDSTVQMI,5606
+mkdocstrings_python-1.16.8.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
+mkdocstrings_python-1.16.8.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+mkdocstrings_python-1.16.8.dist-info/licenses/LICENSE,sha256=JGb4pdPEM8TTjjhr-uNCO7oXkiVrwG5Pz0JamcjNF_s,754
+mkdocstrings_python-1.16.8.dist-info/RECORD,,