{"id":1759,"library":"types-mock","title":"Typing Stubs for the Mock Library","description":"This package provides high-quality type stubs for the `mock` library (and by extension, `unittest.mock` from the standard library), enabling static type checkers like `mypy` to understand and validate usage of mock objects. Part of the `typeshed` project, it is actively maintained with a continuous release cadence reflecting updates to the stubs. The current version is 5.2.0.20260408.","status":"active","version":"5.2.0.20260408","language":"python","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["types","type-hints","mypy","testing","mocking","static-analysis"],"install":[{"cmd":"pip install types-mock","lang":"bash","label":"Install `types-mock`"}],"dependencies":[{"reason":"This package provides type stubs for the 'mock' library (which is a backport of 'unittest.mock' for older Python versions). While 'types-mock' itself has no runtime dependencies, users typically install it to type-check their code that uses the 'mock' library or 'unittest.mock'.","package":"mock","optional":true}],"imports":[{"note":"`types-mock` provides stubs for runtime libraries like `unittest.mock` (or the `mock` backport). You should import the runtime symbols directly from `unittest.mock` (or `mock`), not from `types_mock`.","wrong":"from types_mock import Mock","symbol":"Mock","correct":"from unittest.mock import Mock"},{"note":"`types-mock` provides stubs for runtime libraries like `unittest.mock` (or the `mock` backport). You should import the runtime symbols directly from `unittest.mock` (or `mock`), not from `types_mock`.","wrong":"from types_mock import patch","symbol":"patch","correct":"from unittest.mock import patch"}],"quickstart":{"code":"import sys\nfrom unittest.mock import Mock, MagicMock\n\n# Define a simple service with type hints\nclass MyService:\n    def fetch_data(self, url: str) -> dict:\n        return {\"status\": \"ok\", \"url\": url, \"data\": \"real content\"}\n\ndef process_data(service: MyService, target_url: str) -> str:\n    data = service.fetch_data(target_url)\n    if data and data.get(\"status\") == \"ok\":\n        return f\"Successfully processed data from {data.get('url')}\"\n    return \"Failed to process data\"\n\n# --- Usage with types-mock (implicitly through mypy) ---\n\n# 1. Mocking a method explicitly typed\nmock_service_typed: MyService = Mock(spec=MyService) # Use spec for stricter type checking\nmock_service_typed.fetch_data.return_value = {\"status\": \"ok\", \"url\": \"mocked.com\", \"data\": \"mocked content\"}\n\nprint(f\"Typed Mock Result: {process_data(mock_service_typed, 'http://example.com')}\")\n\n# mypy would catch this if uncommented because 123 is not a string for url:\n# print(process_data(mock_service_typed, 123))\n\n# 2. MagicMock is also typed\nmagic_mock_example: MagicMock = MagicMock()\nmagic_mock_example.__len__.return_value = 5\nprint(f\"MagicMock length: {len(magic_mock_example)}\")\n\n# To see types-mock in action, save this as `app.py`, then run:\n# pip install mypy\n# mypy app.py","lang":"python","description":"This example demonstrates how `types-mock`, when used with `mypy`, provides type-checking for `unittest.mock.Mock` and `MagicMock` objects. By using `spec=MyService`, `mypy` ensures that the mock adheres to the `MyService` interface, catching potential type errors that might otherwise go unnoticed during testing setup."},"warnings":[{"fix":"Always import runtime mock objects from `from unittest.mock import ...` or `from mock import ...`.","message":"Do not import symbols directly from `types_mock`. This package provides type stubs for static analysis (e.g., by `mypy`), not runtime code. You should import `Mock`, `patch`, etc., from `unittest.mock` (or the `mock` backport library).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Understand that `types-mock` enhances developer productivity through static analysis, but doesn't alter how your code runs. Ensure `mypy` or another type checker is configured to use the installed stubs.","message":"`types-mock` is solely for static type checking; installing it has no effect on your program's runtime behavior. It's a development dependency, typically used with tools like `mypy`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For Python 3.3 and newer, prefer `unittest.mock`. For older Python versions, install `pip install mock` and use `import mock`. Ensure your type checker configuration points to the correct stubs if there's any ambiguity (though typeshed usually handles this automatically).","message":"There are two main 'mock' libraries: the built-in `unittest.mock` (Python 3.3+) and the standalone `mock` backport for older Python versions. `types-mock` provides stubs for both, but ensure you are consistent in which library you are using in your project's runtime code.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Don't try to map `types-mock` versions directly to `mock` or `unittest.mock` versions. Refer to the typeshed changelog or `mock` library documentation for specific API changes.","message":"The version number of `types-mock` (e.g., `5.2.0.20260408`) does not correspond to a specific version of the `mock` runtime library. Instead, it reflects the version of the stubs within the `typeshed` project and the date they were published.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'5.2.0.20260408':64 'activ':48 'analysi':74 'cadenc':54 'checker':30 'continu':52 'current':61 'enabl':27 'extens':21 'high':11 'high-qual':10 'hint':68 'librari':6,18,26 'like':31 'maintain':49 'mock':5,17,39,71 'mypi':32,69 'object':40 'packag':8 'part':41 'project':45 'provid':9 'qualiti':12 'reflect':55 'releas':53 'standard':25 'static':28,73 'static-analysi':72 'stub':2,14,59 'test':70 'type':1,13,29,65,67 'type-hint':66 'typesh':44 'understand':34 'unittest.mock':22 'updat':56 'usag':37 'valid':36 'version':62","created_at":"2026-04-09T04:01:54.837627+00:00","updated_at":"2026-04-16T23:40:03.030338+00:00","problems":[{"fix":"Install the `types-mock` package (`pip install types-mock`) to provide `mypy` with the necessary type information for mock objects.","cause":"Mypy cannot infer the types of `unittest.mock.Mock` attributes like `call_args`, `assert_called_once_with`, or `return_value` without type stubs.","error":"error: \"Mock\" has no attribute \"call_args\""},{"fix":"Explicitly type the patched argument in the decorated function's signature (e.g., `def test_func(self, mock_obj: MagicMock)`).","cause":"Mypy struggles to infer the types of arguments injected by `unittest.mock.patch` decorators, leading to functions being marked as untyped.","error":"error: Untyped decorator makes function \"...\" untyped"},{"fix":"Ensure `types-mock` is installed (`pip install types-mock`) to provide correct callable types for `Mock` objects, or explicitly cast the mock to a callable type (e.g., `mock_func: Callable[..., Any] = Mock()`).","cause":"Mypy expects a callable object but encounters a `unittest.mock.Mock` instance that it cannot determine to be callable without proper type stubs.","error":"error: \"Mock\" not callable"},{"fix":"Install `types-mock` (`pip install types-mock`) to provide `mypy` with comprehensive type stubs for all `Mock` attributes, including those for async mocking.","cause":"Mypy cannot find type information for specific asynchronous attributes like `async_return_value` on `unittest.mock.Mock` objects without type stubs.","error":"error: \"Mock\" has no attribute \"async_return_value\""}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"5.2.0.20260518","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/typeshed-internal/stub_uploader","docs":null,"changelog":"https://github.com/typeshed-internal/stub_uploader/blob/main/data/changelogs/mock.md","pypi":"https://pypi.org/project/types-mock/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs","testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":null}}