bug: mkdocstrings filters option doesn't work anymore after upgrade to griffe 0.46.0

[kkpattern]

Description of the bug

I don't know it's a griffe bug or the mkdocstrings's bug. After upgrade to griffe 0.46.0, the filters option doesn't work anymore. We have the filters option set to a empty list. After upgrade to griffe 0.46.0, the protected methods are no longer collected. Revert back to 0.45.3 fixed the issue.

To Reproduce

With the following setting:

plugins:
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: sphinx
            show_source: false
            filters: []

Protected methods are no longer collected.

Expected behavior

Projected methods can be collected.

Environment information

griffe --debug-info  # | xclip -selection clipboard

- __System__: Linux-4.19.0-10-amd64-x86_64-with-glibc2.31
- __Python__: cpython 3.11.3 (/tmp/.venv/bin/python3)
- __Environment variables__:
- __Installed packages__:
  - `griffe` v0.46.0

Additional context

[pawamoy]

Thanks for the fast report. Looking into it right now.

[pawamoy]

OK, found the issue.

In the Python handler templates, we first filter objects according to the members, inherited_members, filters and show_if_no_docstring options. Then, we do a second filtering pass, checking if each object is either explicitly passed in members, or is public. This is because when you don't pass an explicit members list, and let filters do their stuff, you still don't want to end up with non-public objects rendered in your page (such as imported objects).

The issue is that previously, we would tweak the is_public check so as to ignore the object's name, but now it always checks the name, so objects whose name starts with _ are not considered public and are therefore filtered out. That means dunder attributes and methods are filtered out.

I think the easiest and most correct way to fix this is to update Griffe's "public" logic to consider dunder attributes and methods to be public, because even if we don't access them directly, we still use them publicly through different syntax or means.

I'll do just that!

[pawamoy]

OK, v0.46.1 is on PyPI, let me know if you still encounter issues!

[llucax]

WORKSFORME ❤️

[vulli321]

does not work for me, 0.46.1 only fixed #295
protected methods as noted in this issue are still missing

[pawamoy]

Ah, right, I read it as "special" instead of protected, my bad. Essentially I think the Python handler should stop doing this second filtering pass. But that would be a breaking change, so I'll simply change it to filter out imported objects, not private/protected ones.

[pawamoy]

@vulli321 could you try latest mkdocstrings-python (1.10.4) and tell me if this issue is fixed?

[kkpattern]

Upgrade to mkdocstrings-python (1.10.4) fixed our issue. Thanks!

[vulli321]

can confirm, fixed now 👍

[pawamoy]

Thanks @kkpattern, @vulli321! Closing :)

[llucax]

Whoops, it seems like this issue doesn't want to go away. The new release broke my use case again 😬

[llucax]

@pawamoy Not sure what the problem is now, but with griffe 0.47 I'm getting these errors:

WARNING -  mkdocs_autorefs: reference/frequenz/sdk/actor/index.md: Could not find cross-reference target '[frequenz.sdk.actor.Actor]'
WARNING -  mkdocs_autorefs: reference/frequenz/sdk/actor/index.md: Could not find cross-reference target '[frequenz.sdk.actor.Actor]'
WARNING -  mkdocs_autorefs: reference/frequenz/sdk/actor/index.md: Could not find cross-reference target '[frequenz.sdk.actor.Actor]'
WARNING -  mkdocs_autorefs: reference/frequenz/sdk/actor/index.md: Could not find cross-reference target '[frequenz.sdk.actor.run]'
WARNING -  mkdocs_autorefs: reference/frequenz/sdk/actor/index.md: Could not find cross-reference target '[frequenz.sdk.actor.run]'

While 0.45.3 and 0.46.1 work fine. Instructions to reproduce are the same as in #295.

[pawamoy]

Sorry for the trouble, let me look into it 👍

[pawamoy]

@llucax what version of mkdocstrings-python do you have?

[pawamoy]

OK, keeping only public objects was wrong, filtering out imported objects is wrong, the solution is to filter out imported objects unless they are public 🥵 Sorry for the confusion, the template logic is sometimes hard to get right. I'll prioritize the end-to-end tests PR next: mkdocstrings/python#157.

[pawamoy]

Released v1.8.5, it should behave correctly now.

[llucax]

Yup, it is working again now. Thanks a lot for the super fast responses and fixes! 🎉

[pawamoy]

Thanks for testing new releases super early and sending bug reports 😄