4.1.2: autodoc for classes with _name property is broken

[mathiasertl]

Describe the bug

In #9490, or more precisely 68fb548, Sphinx started preferring cls._name over cls.__qualname__. This breaks autodoc for classes that define a _name property for other purposes. I don't know of any PEPs or similar (but I might be wrong?) that define _name as something special, so implementing classes can use it to be anything.

A concrete example is cryptography.x509.ObjectIdentifier, which defines a property called _name. At a minimal level, generating autodoc documentation for this class will trigger the error:

from cryptography import x509

class Demo(x509.ObjectIdentifier):
    """Docstring"""

(note: I use this workaround to work around non-canonical name issues, partly(?) fixed in #4826).

Generating autodoc documentation for this class will yield the following warning:

...:docstring of path.to.Demo:1:py:obj reference target not found: property object at 0x...

Reverting the switch in the aforementioned commit makes the warning go away. A possible refinement would be to check if _name is a string, e.g.:

diff --git a/sphinx/util/typing.py b/sphinx/util/typing.py
index fd5735c57..81f110bff 100644
--- a/sphinx/util/typing.py
+++ b/sphinx/util/typing.py
@@ -174,7 +174,7 @@ def _restify_py37(cls: Optional[Type]) -> str:
             text += r"\ [%s]" % ", ".join(restify(a) for a in cls.__args__)
 
         return text
-    elif hasattr(cls, '_name'):
+    elif hasattr(cls, '_name') and isinstance(cls._name, str):
         # SpecialForm
         if cls.__module__ == 'typing':
             return ':obj:`~%s.%s`' % (cls.__module__, cls._name)

How to Reproduce

My project defines a more complex class, but I have verified this with the simple class defined above as well (I assume you know how to use a virtualenv ;-)). In this example, I clone my repo, build with Sphinx==4.1.1 (which works) and then update to Sphinx==4.1.2, which no longer works:

$ git clone https://github.com/mathiasertl/django-ca.git
$ cd django-ca
$ git checkout e8e93c358304b5f9cfa235ff7743e824994c32aa
$ pip install -r requirements.txt -r requirements/requirements-docs.txt
$ make -C docs html
... ok
$ pip install Sphinx==4.1.2
$ make -C docs html
...
Warning, treated as error:
/home/mertl/git/mati/test/django-ca/ca/django_ca/extensions/extensions.py:docstring of django_ca.extensions.extensions.ExtendedKeyUsage:1:py:obj reference target not found: property object at 0x7ff7717a1db0

If you change ExtendedKeyUsage in ca/django_ca/extensions/extensions.py to use any other class instead of x509.ObjectIdentifier, it will also work with 4.1.2. If you instead invert the "elif" order back to the state before 68fb548, it will also start working again.

Expected behavior

Sphinx should still build the documentation, obviously. Either the order should be reversed again, or it should be checked if cls._name is a str.

If you agree to either of the proposed solutions, I would volunteer for a PR.

Your project

https://github.com/mathiasertl/django-ca/

Screenshots

No response

OS

Ubuntu

Python version

tested with 3.8, 3.9

Sphinx version

4.1.2

Sphinx extensions

sphinx.ext.autodoc, celery.contrib.sphinx, numpydoc (but likely not relevant)

Extra tools

No response

Additional context

No response

[tk0miya]

Thank you for reporting.

The same problem was reporeted as #9504, and fixed at #9515. The fixed version will be released soon.

[mathiasertl]

Ah. I must have overlooked the issue, thanks.