Incorrect parsing of class init annotations

[alexfikl]

Describe the bug

Sphinx 9.0.4 seems to parse arguments with type annotations incorrectly. I have the following class

and get the error

<unknown>:1: WARNING: py:class reference target not found: list[tuple[float [ref.class]

This looks like it is getting confused by the comma in the tuple when parsing the arguments in there, but I have not looked into it very carefully. The same annotation for the class member seems to work just fine.

This seems to be related to the fact that there's a <factory> default in there.

How to Reproduce

An MRE can be found here: sphinx-bug-mre.zip. I am generating the documentation using

cd docs
python -m sphinx -M html . _build -W -n --keep-going

in a virtual environment created using mkvirtualenv sphinx-bug.

Environment Information

Platform:              linux; (Linux-6.17.9-arch1-1-x86_64-with-glibc2.42)
Python version:        3.13.7 (main, Aug 15 2025, 12:34:02) [GCC 15.2.1 20250813])
Python implementation: CPython
Sphinx version:        9.0.4
Docutils version:      0.22.3
Jinja2 version:        3.1.6
Pygments version:      2.19.2

Sphinx extensions

Extensions: ["autodoc", "intersphinx"]

Additional context

No response

[AA-Turner]

@alexfikl my first guess is that parsing fails due to <factory>. Can you try changing the default argument?

A

[alexfikl]

@alexfikl my first guess is that parsing fails due to <factory>. Can you try changing the default argument?

Yeah, just had the same idea and can confirm that setting it to something like

history: list[tuple[float, float]] = ()

no longer causes the problem. Duplicate of #10954?

[alexfikl]

For what it's worth, just noticed that this also doesn't render correctly in Sphinx 8.2.3, but it doesn't show the error 😁

[AA-Turner]

Duplicate of #10954?

Perhaps, though my guess is that here there's an attempt to fall back to the old (regex) parsing method which splits on whitespace, hence the error message you observe.

Are you using autodoc here or 'raw' reST directives? If the former, we could maybe look into improving parsing for types (the np.int32 case), and perhaps it might be possible to do the same for other types with unrepresentable reprs?

I've just spent several months rewriting the core of autodoc so it should be easier to debug & run independently of core Sphinx, if you have time to do so. Look at do_autodoc in the tests for a starting point.

A

[alexfikl]

Are you using autodoc here or 'raw' reST directives? If the former, we could maybe look into improving parsing for types (the np.int32 case), and perhaps it might be possible to do the same for other types with unrepresentable reprs?

I'm just using an automodule directive to include the whole thing (both in the MRE above and in my actual code).

Look at do_autodoc in the tests for a starting point.

I'll take a look!