References to `pathlib` objects are incorrectly picked up by autodoc

[cjw296]

Describe the bug

Type annotations using pathlib.Path of callable that are handed by autodoc generate the following warning on Python 3.13:

{filename}.py:docstring of {callable}:1: WARNING: py:class reference target not found: pathlib._local.Path [ref.class]

They do not on 3.12 and below.

How to Reproduce

Failing build on RTD: https://readthedocs.org/projects/sybil/builds/26566926/
Passing build on RTD: https://readthedocs.org/projects/sybil/builds/26567027/

Only difference is Python 3.12 versus 3.13.

Python source being auto-doc'ed:

https://github.com/simplistix/sybil/blob/8d58cfe196a9f8136f8eea453805e6e3c9e6b263/sybil/sybil.py#L159-L164

Sphinx .rst referencing this:

https://github.com/simplistix/sybil/blob/8d58cfe196a9f8136f8eea453805e6e3c9e6b263/docs/api.rst?plain=1#L14-L16

Sphinx config:

https://github.com/simplistix/sybil/blob/8d58cfe196a9f8136f8eea453805e6e3c9e6b263/docs/conf.py#L1-L45

Environment Information

$ python -m sphinx --bug-report
Please paste all output below into the bug report template


...gave:

```text
Platform:              darwin; (macOS-15.1.1-arm64-arm-64bit-Mach-O)
Python version:        3.13.0 (main, Oct  7 2024, 23:47:22) [Clang 18.1.8 ])
Python implementation: CPython
Sphinx version:        8.1.3
Docutils version:      0.21.2
Jinja2 version:        3.1.4
Pygments version:      2.18.0

Sphinx extensions

"sphinx.ext.autodoc" is the one here.

[picnixz]

This is a known issue (at least to me) and I should have probably already said it somewhere but the issue is because of the (C)Python intersphinx mappings. When pathlib.Path is resolved, we (Sphinx) resolve it to pathlib._local.Path and I don't think we can set it to pathlib.Path internally. Now, CPython's interphinx does not have pathlib._local.Path documented and only pathlib.Path, hence the issue :(

[drammock]

This is a known issue (at least to me) and I should have probably already said it somewhere but the issue is because of the (C)Python intersphinx mappings. When pathlib.Path is resolved, we (Sphinx) resolve it to pathlib._local.Path and I don't think we can set it to pathlib.Path internally. Now, CPython's interphinx does not have pathlib._local.Path documented and only pathlib.Path, hence the issue :(

Could you give a bit more detail here @picnixz? The intersphinx mappings for Python 3.12 and 3.13 appear to be identical w/r/t the entry for pathlib.Path and neither of them has an entry for pathlib._local.Path. So I'm not following why this warning emerges only when building using Python 3.13, and I'm also not clear why sphinx resolves it to pathlib._local.Path (and why that can't be changed).

grepping against current master for _local doesn't clarify things; most hits are _locale or thread_local (irrelevant); the only relevant ones are from 3496de6 and they're in an autodoc test file, and all they do is triage against Python version so that the test passes :(

[picnixz]

Internally, pathlib.Path is imported from pathlib._local.Path: https://github.com/python/cpython/blob/3.13/Lib/pathlib/__init__.py and https://github.com/python/cpython/blob/fe08cdf2657bfde80aeed436fe49fee233651837/Lib/pathlib/_local.py#L26. Because of this, Sphinx will resolve it (dynamically) as pathlib._local.Path because that's the real fully-qualified name of pathlib.Path.

Namely, when you have def foo(p: pathlib.Path): ..., from a Python perspective, it's def foo(p: pathlib._local.Path): .... So when you autodoc the function, at runtime, pathlib.Path points to pathlib._local.Path and not pathlib.Path (which is only an re-exported member!)

On CPython's side, we document pathlib.Path. So, if Sphinx encounters pathlib._local.Path, it cannot resolves it to pathlib.Path because no such entry exists actually! I'm still wondering how we can fix this but I don't have much bandwidth for Sphinx these past months (sorry for that).

I'll honestly try to come up with something by the end of the year for at least forcing any false positive to be manually resolved to something else =/

[drammock]

thanks for the explainer!

[AA-Turner]

Cross-posting from #13232 (comment), a workaround for this issue is below. This alters private attributes in Sphinx, though, so be careful if adopting it. I will open a PR to fix for 8.2 shortly.

import sys
import sphinx

if sys.version_info[:2] >= (3, 13) and sphinx.version_info[:2] < (8, 2):
    import pathlib

    from sphinx.util.typing import _INVALID_BUILTIN_CLASSES

    _INVALID_BUILTIN_CLASSES[pathlib.Path] = 'pathlib.Path'  # type: ignore

A