3.12.3 --> 3.12.4 regression? [deep rabbit hole warning]

Python Help
, ,
12

Before the backport, Sphinx/autodoc parses the regular methods correctly:

.. py:method:: Container.make_dir(path: str | ~pathlib.PurePath, *, make_parents: bool = False, permissions: ...

And type overloads for methods correctly:

.. py:method:: Container.pull(path: str | ~pathlib.PurePath, *, encoding: None) -> ~typing.BinaryIO
               Container.pull(path: str | ~pathlib.PurePath, *, encoding: str = 'utf-8') -> ~typing.TextIO

After the backport, regular methods are still parsed correctly:

.. py:method:: Container.make_dir(path: str | ~pathlib.PurePath, *, make_parents: bool = False, permissions: ...

But type overloads for methods are not:

.. py:method:: Container.pull(path: Union[str, PurePath], *, encoding: None) -> BinaryIO
               Container.pull(path: Union[str, PurePath], *, encoding: str = 'utf-8') -> TextIO

Here Sphinx seems to keep the signature verbatim as it’s stated in the source code.

Note that the code in question has to work under py3.8~3.13, so we use older-style annotations, like Union[str, PurePath. These seems to be decoded by Sphinx running under Python 3.12.3 into str | ~pathlib.PurePath.

The regression is that, somehow, the type annotation is not decoded specifically in overloads.

It’s also possible that Sphinx tries to decode this, hits an exception, and keeps the literal type hint / signature as a fallback.

2 Likes