feat: Prefer stub over target object if not the same kind

[kattni]

For reviewers

• I did not use AI
• I used AI and thorougly reviewed every code/docs change

Description of the change

This update changes the behavior of handling stub packages when encountering a target object and stub that are of a different kind. griffe no longer skips the stub in this case, and instead prefers the stub over the target.

Successfully tested on my current documentation project wherein griffe was seeing a class object as a module-attribute, and with the change, is successfully rendering it as a class with the expected docstring from a .pyi file.

Both make check and make test are not working for me. If desired, I can provide the failure details. I'm including this to note that neither were run before submitting this PR.

Relevant resources

• mkdocstrings discussion 803: Stubs package configuration for `mkdocstrings` mkdocstrings#803

[pawamoy]

One possible issue I see is that any modification done by on_x_instance events on the base object would be lost once we overwrite the base object with the stub one 🤔 In this case the users can always use on_x events instead, which would happen after the base object was overwritten by the stub one. This will need a note in the docs, probably. And keeping a DEBUG log message would probably be useful too. Other than that, I think we can go ahead and do the change 🙂

I can deal with the docs update. Could you add back a DEBUG log message informing users that the object is overwritten by its stub equivalent?

[kattni]

Is this acceptable? The previous version had obj_member.kind.value and I'm unclear on whether the .value is necessary here on the .name calls.

                if obj_member.kind is not stub_member.kind:
                    # If the stub and the target are not of the same kind, prefer the
                    # stub over the target.
                    logger.debug(
                        "In %s, %s source object type != %s stub object type; "
                        "source object will be overwritten by stub object.",
                        obj_member.path,
                        obj_member.name,
                        stub_member.name,
                    )
                    obj.set_member(stub_member.name, stub_member)