{"id":9568,"library":"callee","title":"Callee: Argument Matchers for unittest.mock","description":"Callee provides a set of powerful argument matchers designed to extend the capabilities of Python's `unittest.mock` library. It allows developers to write more expressive and robust assertions for mocked calls, enabling checks for patterns, types, ranges, and more, beyond simple value equality. The current version is 0.3.1, with a stable but infrequent release cadence.","status":"active","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/Xion/callee","tags":["testing","mocking","unittest","assertion"],"install":[{"cmd":"pip install callee","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"callee.Any allows for type-specific matching (e.g., Any(int)), while unittest.mock.ANY is a generic singleton for 'any value'.","wrong":"from unittest.mock import ANY","symbol":"Any","correct":"from callee import Any"},{"symbol":"Eq","correct":"from callee import Eq"},{"symbol":"Regex","correct":"from callee import Regex"},{"symbol":"InstanceOf","correct":"from callee import InstanceOf"},{"symbol":"Not","correct":"from callee import Not"}],"quickstart":{"code":"from unittest import mock\nfrom callee import Eq, Regex, Any\n\nclass MyService:\n    def process_data(self, data_id, name):\n        # Imagine this does something with data_id and name\n        return f\"Processed {name} with ID {data_id}\"\n\ndef external_function(service: MyService):\n    # This function calls methods on the provided service\n    service.process_data(123, \"test_name_abc\")\n    service.process_data(456, \"another_name_xyz\")\n\n# Create a mock for MyService\nmock_service = mock.Mock(spec=MyService)\n\n# Call the function that uses the service, injecting our mock\nexternal_function(mock_service)\n\n# Assert that process_data was called with specific matchers\n# This checks the first call\nmock_service.process_data.assert_has_calls([\n    mock.call(Eq(123), Regex(r'^test_name_.*$')),\n    mock.call(Any(int), Any(str)) # Any integer, any string for the second call\n])\n\nprint(\"Assertions successful!\")","lang":"python","description":"This quickstart demonstrates how to use `callee` matchers with `unittest.mock` to assert more complex argument patterns. It creates a mock object, calls a function that uses it, and then uses `Eq`, `Regex`, and `Any` matchers within `assert_has_calls` to verify the arguments passed to the mock."},"warnings":[{"fix":"Update your code to use `InstanceOf` instead of `class_of` and `call_args_are`/`call_kwargs_are` instead of their deprecated names.","message":"Version 0.3.0 introduced breaking changes: The `class_of` matcher was removed (use `InstanceOf` instead). The `call_has_args` and `call_has_kwargs` methods were renamed to `call_args_are` and `call_kwargs_are` respectively.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Ensure `callee` matchers are passed as arguments to `unittest.mock` assertion methods, or used when inspecting `mock.call_args` through `callee.matchers.Matching(...)` if custom logic is required outside standard assertions.","message":"`callee` matchers are primarily designed for use within `unittest.mock`'s assertion methods (e.g., `assert_called_with`, `assert_has_calls`, checking `call_args`). They are not general-purpose assertion objects and should not be used directly in standard Python `assert` statements (e.g., `assert 'foo' == Regex(r'foo')` will likely fail or behave unexpectedly) as they rely on `unittest.mock`'s internal comparison logic.","severity":"gotcha","affected_versions":"All"},{"fix":"Use `callee.Any` when you need to specify a type or apply additional conditions to 'any' argument. Use `unittest.mock.ANY` for a generic 'don't care' placeholder.","message":"Be mindful of the distinction between `callee.Any` and `unittest.mock.ANY`. While both signify 'any argument', `callee.Any` offers more advanced capabilities, such as specifying a type (e.g., `Any(int)`) or other conditions, making it more powerful for precise matching. `unittest.mock.ANY` is a simple singleton for any value.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure `callee` matchers are always passed as arguments to `unittest.mock` assertion methods, like `mock_obj.assert_called_with(Regex(r'some.*'))`.","cause":"Attempting to use a `callee` matcher directly in a comparison or context where `unittest.mock`'s evaluation logic is not present, such as `assert 'some_string' == Regex(r'some.*')`.","error":"TypeError: argument of type 'Regex' is not iterable"},{"fix":"Review the actual values being passed to the mock during the test run and compare them against the conditions defined by your `callee` matchers. Adjust either the test data or the matcher's expectation to align.","cause":"This `AssertionError` from `unittest.mock` indicates that an expected `callee` matcher (e.g., `Eq(5)`) did not match the actual argument passed to the mock (e.g., `6`). The error message shows the matcher object because it represents the expectation that failed.","error":"AssertionError: Expected call: call(<callee.matchers.Eq object at 0x...>) Actual call: call(6)"},{"fix":"Add the necessary import statement at the top of your file: `from callee import Any` (or other specific matchers).","cause":"The `Any` matcher (or any other `callee` matcher) was used without being correctly imported from the `callee` library.","error":"NameError: name 'Any' is not defined"}]}