Skip to content

Improve unittest.mock stubs #14421

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

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Improve unittest.mock stubs #14421

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1c5807d
Improve unittest.mock stubs
srittau Jul 16, 2025
e5f0836
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Jul 16, 2025
f5a1a75
Ignore a mypy build error
srittau Jul 16, 2025
454dfa7
Fix
srittau Jul 16, 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
126 changes: 88 additions & 38 deletions stdlib/unittest/mock.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ from _typeshed import MaybeNone
from collections.abc import Awaitable, Callable, Coroutine, Iterable, Mapping, Sequence
from contextlib import _GeneratorContextManager
from types import TracebackType
from typing import Any, ClassVar, Final, Generic, Literal, TypeVar, overload
from typing import Any, ClassVar, Final, Generic, Literal, TypeVar, overload, type_check_only
from typing_extensions import ParamSpec, Self, TypeAlias

_T = TypeVar("_T")
Expand Down Expand Up @@ -262,6 +262,7 @@ class _patch(Generic[_T]):
# This class does not exist at runtime, it's a hack to make this work:
# @patch("foo")
# def bar(..., mock: MagicMock) -> None: ...
@type_check_only
class _patch_pass_arg(_patch[_T]):
@overload
def __call__(self, func: _TT) -> _TT: ...
Expand All @@ -288,72 +289,88 @@ class _patch_dict:

# This class does not exist at runtime, it's a hack to add methods to the
# patch() function.
@type_check_only
class _patcher:
TEST_PREFIX: str
dict: type[_patch_dict]
# This overload also covers the case, where new==DEFAULT. In this case, the return type is _patch[Any].
# Ideally we'd be able to add an overload for it so that the return type is _patch[MagicMock],
# but that's impossible with the current type system.
@overload
def __call__(
def __call__( # type: ignore[overload-overlap]
self,
target: str,
new: _T,
spec: Any | None = ...,
create: bool = ...,
spec_set: Any | None = ...,
autospec: Any | None = ...,
new_callable: Callable[..., Any] | None = ...,
**kwargs: Any,
spec: Literal[False] | None = None,
create: bool = False,
spec_set: Literal[False] | None = None,
autospec: Literal[False] | None = None,
new_callable: None = None,
*,
unsafe: bool = False,
) -> _patch[_T]: ...
@overload
def __call__(
self,
target: str,
*,
spec: Any | None = ...,
create: bool = ...,
spec_set: Any | None = ...,
autospec: Any | None = ...,
# If not False or None, this is passed to new_callable
spec: Any | Literal[False] | None = None,
create: bool = False,
# If not False or None, this is passed to new_callable
spec_set: Any | Literal[False] | None = None,
autospec: Literal[False] | None = None,
new_callable: Callable[..., _T],
unsafe: bool = False,
# kwargs are passed to new_callable
**kwargs: Any,
) -> _patch_pass_arg[_T]: ...
@overload
def __call__(
self,
target: str,
*,
spec: Any | None = ...,
create: bool = ...,
spec_set: Any | None = ...,
autospec: Any | None = ...,
new_callable: None = ...,
spec: Any | bool | None = None,
create: bool = False,
spec_set: Any | bool | None = None,
autospec: Any | bool | None = None,
new_callable: None = None,
unsafe: bool = False,
# kwargs are passed to the MagicMock/AsyncMock constructor
**kwargs: Any,
) -> _patch_pass_arg[MagicMock | AsyncMock]: ...
# This overload also covers the case, where new==DEFAULT. In this case, the return type is _patch[Any].
# Ideally we'd be able to add an overload for it so that the return type is _patch[MagicMock],
# but that's impossible with the current type system.
@overload
@staticmethod
def object(
target: Any,
attribute: str,
new: _T,
spec: Any | None = ...,
create: bool = ...,
spec_set: Any | None = ...,
autospec: Any | None = ...,
new_callable: Callable[..., Any] | None = ...,
**kwargs: Any,
spec: Literal[False] | None = None,
create: bool = False,
spec_set: Literal[False] | None = None,
autospec: Literal[False] | None = None,
new_callable: None = None,
*,
unsafe: bool = False,
) -> _patch[_T]: ...
@overload
@staticmethod
def object(
target: Any,
attribute: str,
*,
spec: Any | None = ...,
create: bool = ...,
spec_set: Any | None = ...,
autospec: Any | None = ...,
# If not False or None, this is passed to new_callable
spec: Any | Literal[False] | None = None,
create: bool = False,
# If not False or None, this is passed to new_callable
spec_set: Any | Literal[False] | None = None,
autospec: Literal[False] | None = None,
new_callable: Callable[..., _T],
unsafe: bool = False,
# kwargs are passed to new_callable
**kwargs: Any,
) -> _patch_pass_arg[_T]: ...
@overload
Expand All @@ -362,21 +379,54 @@ class _patcher:
target: Any,
attribute: str,
*,
spec: Any | None = ...,
create: bool = ...,
spec_set: Any | None = ...,
autospec: Any | None = ...,
new_callable: None = ...,
spec: Any | bool | None = None,
create: bool = False,
spec_set: Any | bool | None = None,
autospec: Any | bool | None = None,
new_callable: None = None,
unsafe: bool = False,
# kwargs are passed to the MagicMock/AsyncMock constructor
**kwargs: Any,
) -> _patch_pass_arg[MagicMock | AsyncMock]: ...
@overload
@staticmethod
def multiple(
target: Any,
spec: Any | None = ...,
create: bool = ...,
spec_set: Any | None = ...,
autospec: Any | None = ...,
new_callable: Any | None = ...,
target: Any | str,
# If not False or None, this is passed to new_callable
spec: Any | Literal[False] | None = None,
create: bool = False,
# If not False or None, this is passed to new_callable
spec_set: Any | Literal[False] | None = None,
autospec: Literal[False] | None = None,
*,
new_callable: Callable[..., _T],
# The kwargs must be DEFAULT
**kwargs: Any,
) -> _patch_pass_arg[_T]: ...
@overload
@staticmethod
def multiple(
target: Any | str,
# If not False or None, this is passed to new_callable
spec: Any | Literal[False] | None,
create: bool,
# If not False or None, this is passed to new_callable
spec_set: Any | Literal[False] | None,
autospec: Literal[False] | None,
new_callable: Callable[..., _T],
# The kwargs must be DEFAULT
**kwargs: Any,
) -> _patch_pass_arg[_T]: ...
@overload
@staticmethod
def multiple(
target: Any | str,
spec: Any | bool | None = None,
create: bool = False,
spec_set: Any | bool | None = None,
autospec: Any | bool | None = None,
new_callable: None = None,
# The kwargs are the mock objects or DEFAULT
**kwargs: Any,
) -> _patch[Any]: ...
@staticmethod
Expand Down
Loading