refactor: Prepare public filtering method feature

Issue-78: #78

Author: pawamoy

docs/insiders/changelog.md

@@ -2,6 +2,10 @@
 
 ## mkdocstrings-python Insiders
 
+### 1.11.0 <small>March 20, 2025</small> { id="1.11.0" }
+
+- [Filtering method: `public`][option-filters-public]
+
 ### 1.10.0 <small>March 10, 2025</small> { id="1.10.0" }
 
 - [Backlinks][backlinks]

docs/insiders/goals.yml

@@ -45,3 +45,6 @@ goals:
     - name: Backlinks
       ref: /usage/configuration/general/#backlinks
       since: 2025/03/10
+    - name: "Filtering method: `public`"
+      ref: /usage/configuration/members/#option-filters-public
+      since: 2025/03/20

docs/usage/configuration/members.md

@@ -335,10 +335,21 @@ def function_c():
 [](){#option-filters}
 ## `filters`
 
-- **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] | None</code>  :material-equal: `["!^_[^_]"]`{ title="default value" }**
+- **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] | <autoref identifier="typing.Literal" optional>Literal</autoref>["public"] | None</code>  :material-equal: `["!^_[^_]"]`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
-A list of filters applied to filter objects based on their name.
+A list of filters, or `"public"`.
+
+**Filtering methods**
+
+[](){#option-filters-public}
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } &mdash;
+[:octicons-tag-24: Insiders 1.11.0](../../insiders/changelog.md#1.11.0)
+
+The `public` filtering method will include only public objects: those added to the `__all__` attribute of modules, or not starting with a single underscore. Special methods and attributes ("dunder" methods/attributes, starting and ending with two underscores), like `__init__`, `__call__`, `__mult__`, etc., are always considered public.
+
+**List of filters**
 
 Filters are regular expressions. These regular expressions are evaluated by Python
 and so must match the syntax supported by the [`re`][] module.
@@ -379,13 +390,13 @@ plugins:
       python:
         options:
           filters:
-          - "!^_"
+          - "!^_[^_]"
 ```
 
 ```md title="or in docs/some_page.md (local configuration)"
 ::: package.module
     options:
-      filters: []
+      filters: public
 ```
 
 ```python title="package/module.py"

mkdocs.yml

@@ -160,7 +160,7 @@ plugins:
             ignore_init_summary: true
           docstring_section_style: list
           extensions: [scripts/griffe_extensions.py]
-          filters: ["!^_"]
+          filters: public
           heading_level: 1
           inherited_members: true
           line_length: 88

src/mkdocstrings_handlers/python/_internal/config.py

@@ -432,14 +432,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())
@@ -916,12 +926,12 @@ def from_data(cls, **data: Any) -> Self:
 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 +940,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 ()
             ]

src/mkdocstrings_handlers/python/_internal/rendering.py

@@ -399,7 +399,7 @@ def _keep_object(name: str, filters: Sequence[tuple[Pattern, bool]]) -> bool:
 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 +408,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,7 +449,9 @@ 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)
         ]

src/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 %}

tests/snapshots/__init__.py

@@ -353,5 +353,35 @@
             ("inherited_members", ()),
             ("members", ()),
         ): external("a185e216dc7b*.html"),
+        (("filters", "public"), ("inherited_members", ("method1",)), ("members", None)): external("6af55596d9c4*.html"),
+        (("filters", "public"), ("inherited_members", ("method1",)), ("members", False)): external(
+            "6abf5ddd819b*.html",
+        ),
+        (("filters", "public"), ("inherited_members", ()), ("members", None)): external("6d72c524b827*.html"),
+        (("filters", "public"), ("inherited_members", False), ("members", False)): external("9dab67183389*.html"),
+        (("filters", "public"), ("inherited_members", ("method1",)), ("members", True)): external("6c0b7207df03*.html"),
+        (("filters", "public"), ("inherited_members", True), ("members", ())): external("f48d651b3f1a*.html"),
+        (("filters", "public"), ("inherited_members", ("method1",)), ("members", ("module_attribute",))): external(
+            "408244423577*.html",
+        ),
+        (("filters", "public"), ("inherited_members", True), ("members", None)): external("16295fa51a2c*.html"),
+        (("filters", "public"), ("inherited_members", True), ("members", True)): external("37232379c426*.html"),
+        (("filters", "public"), ("inherited_members", ()), ("members", ())): external("2e866eca9a45*.html"),
+        (("filters", "public"), ("inherited_members", True), ("members", False)): external("ed5d07bcdbaa*.html"),
+        (("filters", "public"), ("inherited_members", False), ("members", ())): external("135f57223e00*.html"),
+        (("filters", "public"), ("inherited_members", False), ("members", None)): external("b4e20d5cd52e*.html"),
+        (("filters", "public"), ("inherited_members", ()), ("members", False)): external("46daa7e60b98*.html"),
+        (("filters", "public"), ("inherited_members", False), ("members", True)): external("a255ee80bf7a*.html"),
+        (("filters", "public"), ("inherited_members", ()), ("members", True)): external("74e2496015e1*.html"),
+        (("filters", "public"), ("inherited_members", True), ("members", ("module_attribute",))): external(
+            "e254ae60f9af*.html",
+        ),
+        (("filters", "public"), ("inherited_members", ("method1",)), ("members", ())): external("51d73351dc55*.html"),
+        (("filters", "public"), ("inherited_members", ()), ("members", ("module_attribute",))): external(
+            "d56d3aeae22b*.html",
+        ),
+        (("filters", "public"), ("inherited_members", False), ("members", ("module_attribute",))): external(
+            "80399c502938*.html",
+        ),
     },
 )

tests/snapshots/external/135f57223e006849dcdd1463367127e4c5ee4aba5f12bde17ab3e494dbeed490.html

@@ -0,0 +1,22 @@
+<!--
+{
+  "filters": "public",
+  "inherited_members": false,
+  "members": []
+}
+-->
+
+<div class="doc doc-object doc-module">
+ <h1 class="doc doc-heading" id="members_package">
+  <code>
+   members_package
+  </code>
+ </h1>
+ <div class="doc doc-contents first">
+  <p>
+   Docstring for the package.
+  </p>
+  <div class="doc doc-children">
+  </div>
+ </div>
+</div>