0
# Types Mock
1

2
Types Mock provides comprehensive type stubs for Python's mock testing framework, enabling full static type checking support for all mock testing utilities. It includes type annotations for Mock and MagicMock classes, the patch decorator system, AsyncMock for testing asynchronous code, and various testing utilities with complete IDE integration and type safety.
3

4
## Package Information
5

6
- **Package Name**: types-mock
7
- **Language**: Python
8
- **Installation**: `pip install types-mock`
9
- **Upstream**: [mock library](https://github.com/testing-cabal/mock)
10

11
## Core Imports
12

13
```python
14
import mock
15
```
16

17
Common for specific utilities:
18

19
```python
20
from mock import Mock, MagicMock, patch, AsyncMock
21
from mock import create_autospec, mock_open, PropertyMock
22
from mock import sentinel, DEFAULT, ANY, call
23
```
24

25
## Basic Usage
26

27
```python
28
from mock import Mock, MagicMock, patch, AsyncMock
29

30
# Basic Mock usage
31
mock_obj = Mock()
32
mock_obj.method.return_value = "test"
33
result = mock_obj.method()
34
mock_obj.method.assert_called_once()
35

36
# MagicMock with magic methods
37
magic_mock = MagicMock()
38
magic_mock.__len__.return_value = 5
39
assert len(magic_mock) == 5
40

41
# Patching for dependency injection
42
@patch('module.function')
43
def test_function(mock_func):
44
    mock_func.return_value = "mocked"
45
    # Test code here
46

47
# Async mocking for testing coroutines
48
async_mock = AsyncMock()
49
async_mock.return_value = "async result"
50
result = await async_mock()
51
async_mock.assert_awaited_once()
52
```
53

54
## Architecture
55

56
The mock framework provides a hierarchical structure of mock objects:
57

58
- **NonCallableMock**: Base mock class for non-callable objects with assertion methods
59
- **Mock**: Callable mock combining NonCallableMock with CallableMixin
60
- **MagicMock**: Mock with automatic magic method support for special operations
61
- **AsyncMock**: Specialized mock for testing asynchronous code with await assertions
62
- **Patching System**: Decorators and context managers for temporary object replacement
63
- **Call Tracking**: Comprehensive call recording and assertion capabilities
64

65
## Capabilities
66

67
### Core Mocking
68

69
Essential mock classes for creating test doubles, including basic Mock objects, MagicMock with automatic magic method support, and NonCallableMock for non-callable objects. These provide comprehensive assertion methods and call tracking.
70

71
```python { .api }
72
class Mock:
73
    def __init__(self, spec=None, side_effect=None, return_value=..., wraps=None, name=None, spec_set=None, **kwargs) -> None: ...
74
    def assert_called_with(self, *args, **kwargs) -> None: ...
75
    def assert_called_once_with(self, *args, **kwargs) -> None: ...
76
    def assert_not_called(self) -> None: ...
77

78
class MagicMock(Mock):
79
    def mock_add_spec(self, spec, spec_set: bool = False) -> None: ...
80

81
class NonCallableMock:
82
    def __init__(self, spec=None, wraps=None, name=None, spec_set=None, **kwargs) -> None: ...
83
    def reset_mock(self, visited=None, *, return_value: bool = False, side_effect: bool = False) -> None: ...
84
```
85

86
[Core Mocking](./core-mocking.md)
87

88
### Async Mocking
89

90
Specialized mock class for testing asynchronous code with await-specific assertions and async-aware call tracking. Provides comprehensive support for testing coroutines, async context managers, and async iterators.
91

92
```python { .api }
93
class AsyncMock(Mock):
94
    def assert_awaited(self) -> None: ...
95
    def assert_awaited_once(self) -> None: ...
96
    def assert_awaited_with(self, *args, **kwargs) -> None: ...
97
    def assert_awaited_once_with(self, *args, **kwargs) -> None: ...
98
    def assert_not_awaited(self) -> None: ...
99
    await_count: int
100
    await_args: call | None
101
```
102

103
[Async Mocking](./async-mocking.md)
104

105
### Patching System
106

107
Comprehensive patching decorators and context managers for temporarily replacing objects during testing. Supports object attribute patching, multiple patching, and dictionary patching with automatic cleanup.
108

109
```python { .api }
110
def patch(target, new=..., spec=None, create: bool = False, spec_set=None, autospec=None, new_callable=None, **kwargs): ...
111
def patch.object(target, attribute: str, new=..., spec=None, create: bool = False, **kwargs): ...
112
def patch.multiple(target, spec=None, create: bool = False, **kwargs): ...
113
patch.stopall() -> None
114
```
115

116
[Patching System](./patching.md)
117

118
### Utilities
119

120
Helper functions and specialized mock classes for common testing scenarios, including automatic spec creation, file mocking, property mocking, and mock sealing to prevent accidental attribute access.
121

122
```python { .api }
123
def create_autospec(spec, spec_set: bool = False, instance: bool = False, **kwargs): ...
124
def mock_open(mock=None, read_data: str = "") -> Mock: ...
125
def seal(mock) -> None: ...
126

127
class PropertyMock(Mock):
128
    def __get__(self, obj, obj_type=None): ...
129
    def __set__(self, obj, value) -> None: ...
130
```
131

132
[Utilities](./utilities.md)
133

134
## Constants and Sentinels
135

136
```python { .api }
137
# Version information
138
__version__: str  # Package version string
139
version_info: tuple[int, int, int]  # Version tuple
140

141
# Special matching objects
142
ANY: object  # Matches any value in assertions
143
DEFAULT: object  # Default return value marker
144
sentinel: object  # Factory for creating unique sentinel objects
145

146
# Call tracking
147
call: object  # Factory for creating call objects for assertions
148

149
# Configuration
150
FILTER_DIR: bool  # Controls directory filtering behavior
151
```
152

153
## Type Definitions
154

155
```python { .api }
156
# Call tracking types
157
class call:
158
    args: tuple[Any, ...]
159
    kwargs: dict[str, Any]
160
    def call_list(self) -> list[call]: ...
161

162
# Exception types  
163
class InvalidSpecError(Exception): ...
164
```