Skip to content

Commit beae7fd

Browse files
committed
doc: workaround for ugly API docs for overloaded functions with new Sphinx
New Sphinx added support for overloads and always displays them all with full type annotations etc. This regresses the API reference for overloaded functions like `fixture()`, `warns()`, `raises()` and friends to become impossible to read. I tried various workarounds but none worked except this one.
1 parent 7431750 commit beae7fd

File tree

5 files changed

+26
-15
lines changed

5 files changed

+26
-15
lines changed

src/_pytest/compat.py

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,16 @@
2020
import attr
2121
import py
2222

23+
# fmt: off
24+
# Workaround for https://github.com/sphinx-doc/sphinx/issues/10351.
25+
# If `overload` is imported from `compat` instead of from `typing`,
26+
# Sphinx doesn't recognize it as `overload` and the API docs for
27+
# overloaded functions look good again. But type checkers handle
28+
# it fine.
29+
# fmt: on
30+
if True:
31+
from typing import overload as overload
32+
2333
if TYPE_CHECKING:
2434
from typing_extensions import Final
2535

@@ -345,7 +355,6 @@ def final(f):
345355
if sys.version_info >= (3, 8):
346356
from functools import cached_property as cached_property
347357
else:
348-
from typing import overload
349358
from typing import Type
350359

351360
class cached_property(Generic[_S, _T]):

src/_pytest/fixtures.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@
2020
from typing import MutableMapping
2121
from typing import NoReturn
2222
from typing import Optional
23-
from typing import overload
2423
from typing import Sequence
2524
from typing import Set
2625
from typing import Tuple
@@ -48,6 +47,7 @@
4847
from _pytest.compat import getlocation
4948
from _pytest.compat import is_generator
5049
from _pytest.compat import NOTSET
50+
from _pytest.compat import overload
5151
from _pytest.compat import safe_getattr
5252
from _pytest.config import _PluggyPlugin
5353
from _pytest.config import Config
@@ -1231,7 +1231,7 @@ def fixture(
12311231

12321232

12331233
@overload
1234-
def fixture(
1234+
def fixture( # noqa: F811
12351235
fixture_function: None = ...,
12361236
*,
12371237
scope: "Union[_ScopeName, Callable[[str, Config], _ScopeName]]" = ...,
@@ -1245,7 +1245,7 @@ def fixture(
12451245
...
12461246

12471247

1248-
def fixture(
1248+
def fixture( # noqa: F811
12491249
fixture_function: Optional[FixtureFunction] = None,
12501250
*,
12511251
scope: "Union[_ScopeName, Callable[[str, Config], _ScopeName]]" = "function",

src/_pytest/main.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@
1212
from typing import Iterator
1313
from typing import List
1414
from typing import Optional
15-
from typing import overload
1615
from typing import Sequence
1716
from typing import Set
1817
from typing import Tuple
@@ -25,6 +24,7 @@
2524
import _pytest._code
2625
from _pytest import nodes
2726
from _pytest.compat import final
27+
from _pytest.compat import overload
2828
from _pytest.config import Config
2929
from _pytest.config import directory_arg
3030
from _pytest.config import ExitCode
@@ -597,12 +597,12 @@ def perform_collect(
597597
...
598598

599599
@overload
600-
def perform_collect(
600+
def perform_collect( # noqa: F811
601601
self, args: Optional[Sequence[str]] = ..., genitems: bool = ...
602602
) -> Sequence[Union[nodes.Item, nodes.Collector]]:
603603
...
604604

605-
def perform_collect(
605+
def perform_collect( # noqa: F811
606606
self, args: Optional[Sequence[str]] = None, genitems: bool = True
607607
) -> Sequence[Union[nodes.Item, nodes.Collector]]:
608608
"""Perform the collection phase for this session.

src/_pytest/python_api.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@
1212
from typing import List
1313
from typing import Mapping
1414
from typing import Optional
15-
from typing import overload
1615
from typing import Pattern
1716
from typing import Sequence
1817
from typing import Tuple
@@ -28,6 +27,7 @@
2827
import _pytest._code
2928
from _pytest.compat import final
3029
from _pytest.compat import STRING_TYPES
30+
from _pytest.compat import overload
3131
from _pytest.outcomes import fail
3232

3333

@@ -786,7 +786,7 @@ def raises(
786786

787787

788788
@overload
789-
def raises(
789+
def raises( # noqa: F811
790790
expected_exception: Union[Type[E], Tuple[Type[E], ...]],
791791
func: Callable[..., Any],
792792
*args: Any,
@@ -795,7 +795,7 @@ def raises(
795795
...
796796

797797

798-
def raises(
798+
def raises( # noqa: F811
799799
expected_exception: Union[Type[E], Tuple[Type[E], ...]], *args: Any, **kwargs: Any
800800
) -> Union["RaisesContext[E]", _pytest._code.ExceptionInfo[E]]:
801801
r"""Assert that a code block/function call raises an exception.

src/_pytest/recwarn.py

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,14 @@
99
from typing import Iterator
1010
from typing import List
1111
from typing import Optional
12-
from typing import overload
1312
from typing import Pattern
1413
from typing import Tuple
1514
from typing import Type
1615
from typing import TypeVar
1716
from typing import Union
1817

1918
from _pytest.compat import final
19+
from _pytest.compat import overload
2020
from _pytest.deprecated import check_ispytest
2121
from _pytest.deprecated import WARNS_NONE_ARG
2222
from _pytest.fixtures import fixture
@@ -47,11 +47,13 @@ def deprecated_call(
4747

4848

4949
@overload
50-
def deprecated_call(func: Callable[..., T], *args: Any, **kwargs: Any) -> T:
50+
def deprecated_call( # noqa: F811
51+
func: Callable[..., T], *args: Any, **kwargs: Any
52+
) -> T:
5153
...
5254

5355

54-
def deprecated_call(
56+
def deprecated_call( # noqa: F811
5557
func: Optional[Callable[..., Any]] = None, *args: Any, **kwargs: Any
5658
) -> Union["WarningsRecorder", Any]:
5759
"""Assert that code produces a ``DeprecationWarning`` or ``PendingDeprecationWarning``.
@@ -93,7 +95,7 @@ def warns(
9395

9496

9597
@overload
96-
def warns(
98+
def warns( # noqa: F811
9799
expected_warning: Union[Type[Warning], Tuple[Type[Warning], ...]],
98100
func: Callable[..., T],
99101
*args: Any,
@@ -102,7 +104,7 @@ def warns(
102104
...
103105

104106

105-
def warns(
107+
def warns( # noqa: F811
106108
expected_warning: Union[Type[Warning], Tuple[Type[Warning], ...]] = Warning,
107109
*args: Any,
108110
match: Optional[Union[str, Pattern[str]]] = None,

0 commit comments

Comments
 (0)