Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add pathlib types to _INVALID_BUILTIN_CLASSES #13261

Merged
merged 4 commits into from
Jan 23, 2025
Merged

Add pathlib types to _INVALID_BUILTIN_CLASSES #13261

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1b1dcd7
Add ``pathlib`` types to ``_INVALID_BUILTIN_CLASSES``
AA-Turner Jan 23, 2025
3b04faa
Partially revert 3496de62b743942115acb486cf35dfcc102586c3
AA-Turner Jan 23, 2025
5a17fdc
test __module__
AA-Turner Jan 23, 2025
8db98c1
`pathlib._local` is new in 3.13
AA-Turner Jan 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGES.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,8 @@ Bugs fixed
methods and attributes.
Patch by Bénédikt Tran.
* #12975: Avoid rendering a trailing comma in C and C++ multi-line signatures.
* #13178: autodoc: Fix resolution for ``pathlib`` types.
Patch by Adam Turner.

Testing
-------
Expand Down
22 changes: 16 additions & 6 deletions sphinx/util/typing.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,14 @@

from __future__ import annotations

import contextvars
import dataclasses
import pathlib
import struct
import sys
import types
import typing
from collections.abc import Callable, Sequence
from contextvars import Context, ContextVar, Token
from struct import Struct
from typing import TYPE_CHECKING

from docutils import nodes
Expand Down Expand Up @@ -40,10 +41,19 @@

# classes that have an incorrect .__module__ attribute
_INVALID_BUILTIN_CLASSES: Final[Mapping[object, str]] = {
Context: 'contextvars.Context', # Context.__module__ == '_contextvars'
ContextVar: 'contextvars.ContextVar', # ContextVar.__module__ == '_contextvars'
Token: 'contextvars.Token', # Token.__module__ == '_contextvars'
Struct: 'struct.Struct', # Struct.__module__ == '_struct'
# types in 'contextvars' with <type>.__module__ == '_contextvars':
contextvars.Context: 'contextvars.Context',
contextvars.ContextVar: 'contextvars.ContextVar',
contextvars.Token: 'contextvars.Token',
# types in 'pathlib' with <type>.__module__ == 'pathlib._local':
pathlib.Path: 'pathlib.Path',
pathlib.PosixPath: 'pathlib.PosixPath',
pathlib.PurePath: 'pathlib.PurePath',
pathlib.PurePosixPath: 'pathlib.PurePosixPath',
pathlib.PureWindowsPath: 'pathlib.PureWindowsPath',
pathlib.WindowsPath: 'pathlib.WindowsPath',
# types in 'struct' with <type>.__module__ == '_struct':
struct.Struct: 'struct.Struct',
# types in 'types' with <type>.__module__ == 'builtins':
types.AsyncGeneratorType: 'types.AsyncGeneratorType',
types.BuiltinFunctionType: 'types.BuiltinFunctionType',
Expand Down
31 changes: 9 additions & 22 deletions tests/test_extensions/test_ext_autodoc_configs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -696,11 +696,6 @@ def test_mocked_module_imports(app):
confoverrides={'autodoc_typehints': 'signature'},
)
def test_autodoc_typehints_signature(app):
if sys.version_info[:2] >= (3, 13):
type_ppp = 'pathlib._local.PurePosixPath'
else:
type_ppp = 'pathlib.PurePosixPath'

options = {
'members': None,
'undoc-members': None,
Expand All @@ -726,7 +721,7 @@ def test_autodoc_typehints_signature(app):
'',
'.. py:data:: CONST3',
' :module: target.typehints',
f' :type: ~{type_ppp}',
' :type: ~pathlib.PurePosixPath',
" :value: PurePosixPath('/a/b/c')",
'',
' docstring',
Expand All @@ -749,7 +744,7 @@ def test_autodoc_typehints_signature(app):
'',
' .. py:attribute:: Math.CONST3',
' :module: target.typehints',
f' :type: ~{type_ppp}',
' :type: ~pathlib.PurePosixPath',
" :value: PurePosixPath('/a/b/c')",
'',
'',
Expand All @@ -771,7 +766,7 @@ def test_autodoc_typehints_signature(app):
'',
' .. py:property:: Math.path',
' :module: target.typehints',
f' :type: ~{type_ppp}',
' :type: ~pathlib.PurePosixPath',
'',
'',
' .. py:property:: Math.prop',
Expand All @@ -796,7 +791,7 @@ def test_autodoc_typehints_signature(app):
'',
' docstring',
'',
f" alias of TypeVar('T', bound=\\ :py:class:`~{type_ppp}`)",
" alias of TypeVar('T', bound=\\ :py:class:`~pathlib.PurePosixPath`)",
'',
'',
'.. py:function:: complex_func(arg1: str, arg2: List[int], arg3: Tuple[int, '
Expand Down Expand Up @@ -828,10 +823,6 @@ def test_autodoc_typehints_signature(app):
confoverrides={'autodoc_typehints': 'none'},
)
def test_autodoc_typehints_none(app):
if sys.version_info[:2] >= (3, 13):
type_ppp = 'pathlib._local.PurePosixPath'
else:
type_ppp = 'pathlib.PurePosixPath'
options = {
'members': None,
'undoc-members': None,
Expand Down Expand Up @@ -919,7 +910,7 @@ def test_autodoc_typehints_none(app):
'',
' docstring',
'',
f" alias of TypeVar('T', bound=\\ :py:class:`~{type_ppp}`)",
" alias of TypeVar('T', bound=\\ :py:class:`~pathlib.PurePosixPath`)",
'',
'',
'.. py:function:: complex_func(arg1, arg2, arg3=None, *args, **kwargs)',
Expand Down Expand Up @@ -1511,10 +1502,6 @@ def test_autodoc_typehints_description_and_type_aliases(app):
confoverrides={'autodoc_typehints_format': 'fully-qualified'},
)
def test_autodoc_typehints_format_fully_qualified(app):
if sys.version_info[:2] >= (3, 13):
type_ppp = 'pathlib._local.PurePosixPath'
else:
type_ppp = 'pathlib.PurePosixPath'
options = {
'members': None,
'undoc-members': None,
Expand All @@ -1540,7 +1527,7 @@ def test_autodoc_typehints_format_fully_qualified(app):
'',
'.. py:data:: CONST3',
' :module: target.typehints',
f' :type: {type_ppp}',
' :type: pathlib.PurePosixPath',
" :value: PurePosixPath('/a/b/c')",
'',
' docstring',
Expand All @@ -1563,7 +1550,7 @@ def test_autodoc_typehints_format_fully_qualified(app):
'',
' .. py:attribute:: Math.CONST3',
' :module: target.typehints',
f' :type: {type_ppp}',
' :type: pathlib.PurePosixPath',
" :value: PurePosixPath('/a/b/c')",
'',
'',
Expand All @@ -1585,7 +1572,7 @@ def test_autodoc_typehints_format_fully_qualified(app):
'',
' .. py:property:: Math.path',
' :module: target.typehints',
f' :type: {type_ppp}',
' :type: pathlib.PurePosixPath',
'',
'',
' .. py:property:: Math.prop',
Expand All @@ -1610,7 +1597,7 @@ def test_autodoc_typehints_format_fully_qualified(app):
'',
' docstring',
'',
f" alias of TypeVar('T', bound=\\ :py:class:`{type_ppp}`)",
" alias of TypeVar('T', bound=\\ :py:class:`pathlib.PurePosixPath`)",
'',
'',
'.. py:function:: complex_func(arg1: str, arg2: List[int], arg3: Tuple[int, '
Expand Down
39 changes: 39 additions & 0 deletions tests/test_util/test_util_typing.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,14 @@
from contextvars import Context, ContextVar, Token
from enum import Enum
from numbers import Integral
from pathlib import (
Path,
PosixPath,
PurePath,
PurePosixPath,
PureWindowsPath,
WindowsPath,
)
from struct import Struct
from types import (
AsyncGeneratorType,
Expand Down Expand Up @@ -99,6 +107,9 @@ def test_restify():
assert restify(TracebackType) == ':py:class:`types.TracebackType`'
assert restify(TracebackType, 'smart') == ':py:class:`~types.TracebackType`'

assert restify(Path) == ':py:class:`pathlib.Path`'
assert restify(Path, 'smart') == ':py:class:`~pathlib.Path`'

assert restify(Any) == ':py:obj:`~typing.Any`'
assert restify(Any, 'smart') == ':py:obj:`~typing.Any`'

Expand All @@ -111,10 +122,20 @@ def test_is_invalid_builtin_class():
# of one of these classes has changed, and _INVALID_BUILTIN_CLASSES
# in sphinx.util.typing needs to be updated.
assert _INVALID_BUILTIN_CLASSES.keys() == {
# contextvars
Context,
ContextVar,
Token,
# pathlib
Path,
PosixPath,
PurePath,
PurePosixPath,
PureWindowsPath,
WindowsPath,
# struct
Struct,
# types
AsyncGeneratorType,
BuiltinFunctionType,
BuiltinMethodType,
Expand All @@ -136,7 +157,21 @@ def test_is_invalid_builtin_class():
TracebackType,
WrapperDescriptorType,
}
# contextvars
assert Context.__module__ == '_contextvars'
assert ContextVar.__module__ == '_contextvars'
assert Token.__module__ == '_contextvars'
if sys.version_info[:2] >= (3, 13):
# pathlib
assert Path.__module__ == 'pathlib._local'
assert PosixPath.__module__ == 'pathlib._local'
assert PurePath.__module__ == 'pathlib._local'
assert PurePosixPath.__module__ == 'pathlib._local'
assert PureWindowsPath.__module__ == 'pathlib._local'
assert WindowsPath.__module__ == 'pathlib._local'
# struct
assert Struct.__module__ == '_struct'
# types
assert AsyncGeneratorType.__module__ == 'builtins'
assert BuiltinFunctionType.__module__ == 'builtins'
assert BuiltinMethodType.__module__ == 'builtins'
Expand Down Expand Up @@ -487,6 +522,10 @@ def test_stringify_annotation():
assert ann_str == 'types.TracebackType'
assert stringify_annotation(TracebackType, 'smart') == '~types.TracebackType'

ann_str = stringify_annotation(Path, 'fully-qualified-except-typing')
assert ann_str == 'pathlib.Path'
assert stringify_annotation(Path, 'smart') == '~pathlib.Path'

assert stringify_annotation(Any, 'fully-qualified-except-typing') == 'Any'
assert stringify_annotation(Any, 'fully-qualified') == 'typing.Any'
assert stringify_annotation(Any, 'smart') == '~typing.Any'
Expand Down
Loading