diff options
Diffstat (limited to 'third_party/py/mock/html/_sources/mocksignature.txt')
| -rw-r--r-- | third_party/py/mock/html/_sources/mocksignature.txt | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/third_party/py/mock/html/_sources/mocksignature.txt b/third_party/py/mock/html/_sources/mocksignature.txt new file mode 100644 index 0000000000..dbb5019fbb --- /dev/null +++ b/third_party/py/mock/html/_sources/mocksignature.txt @@ -0,0 +1,262 @@ +mocksignature +============= + +.. currentmodule:: mock + +.. note:: + + :ref:`auto-speccing`, added in mock 0.8, is a more advanced version of + `mocksignature` and can be used for many of the same use cases. + +A problem with using mock objects to replace real objects in your tests is that +:class:`Mock` can be *too* flexible. Your code can treat the mock objects in +any way and you have to manually check that they were called correctly. If your +code calls functions or methods with the wrong number of arguments then mocks +don't complain. + +The solution to this is `mocksignature`, which creates functions with the +same signature as the original, but delegating to a mock. You can interrogate +the mock in the usual way to check it has been called with the *right* +arguments, but if it is called with the wrong number of arguments it will +raise a `TypeError` in the same way your production code would. + +Another advantage is that your mocked objects are real functions, which can +be useful when your code uses +`inspect <http://docs.python.org/library/inspect.html>`_ or depends on +functions being function objects. + +.. function:: mocksignature(func, mock=None, skipfirst=False) + + Create a new function with the same signature as `func` that delegates + to `mock`. If `skipfirst` is True the first argument is skipped, useful + for methods where `self` needs to be omitted from the new function. + + If you don't pass in a `mock` then one will be created for you. + + Functions returned by `mocksignature` have many of the same attributes + and assert methods as a mock object. + + The mock is set as the `mock` attribute of the returned function for easy + access. + + `mocksignature` can also be used with classes. It copies the signature of + the `__init__` method. + + When used with callable objects (instances) it copies the signature of the + `__call__` method. + +`mocksignature` will work out if it is mocking the signature of a method on +an instance or a method on a class and do the "right thing" with the `self` +argument in both cases. + +Because of a limitation in the way that arguments are collected by functions +created by `mocksignature` they are *always* passed as positional arguments +(including defaults) and not keyword arguments. + + +mocksignature api +----------------- + +Although the objects returned by `mocksignature` api are real function objects, +they have much of the same api as the :class:`Mock` class. This includes the +assert methods: + +.. doctest:: + + >>> def func(a, b, c): + ... pass + ... + >>> func2 = mocksignature(func) + >>> func2.called + False + >>> func2.return_value = 3 + >>> func2(1, 2, 3) + 3 + >>> func2.called + True + >>> func2.assert_called_once_with(1, 2, 3) + >>> func2.assert_called_with(1, 2, 4) + Traceback (most recent call last): + ... + AssertionError: Expected call: mock(1, 2, 4) + Actual call: mock(1, 2, 3) + >>> func2.call_count + 1 + >>> func2.side_effect = IndexError + >>> func2(4, 5, 6) + Traceback (most recent call last): + ... + IndexError + +The mock object that is being delegated to is available as the `mock` attribute +of the function created by `mocksignature`. + +.. doctest:: + + >>> func2.mock.mock_calls + [call(1, 2, 3), call(4, 5, 6)] + +The methods and attributes available on functions returned by `mocksignature` +are: + + :meth:`~Mock.assert_any_call`, :meth:`~Mock.assert_called_once_with`, + :meth:`~Mock.assert_called_with`, :meth:`~Mock.assert_has_calls`, + :attr:`~Mock.call_args`, :attr:`~Mock.call_args_list`, + :attr:`~Mock.call_count`, :attr:`~Mock.called`, + :attr:`~Mock.method_calls`, `mock`, :attr:`~Mock.mock_calls`, + :meth:`~Mock.reset_mock`, :attr:`~Mock.return_value`, and + :attr:`~Mock.side_effect`. + + +Example use +----------- + +Basic use +~~~~~~~~~ + +.. doctest:: + + >>> def function(a, b, c=None): + ... pass + ... + >>> mock = Mock() + >>> function = mocksignature(function, mock) + >>> function() + Traceback (most recent call last): + ... + TypeError: <lambda>() takes at least 2 arguments (0 given) + >>> function.return_value = 'some value' + >>> function(1, 2, 'foo') + 'some value' + >>> function.assert_called_with(1, 2, 'foo') + + +Keyword arguments +~~~~~~~~~~~~~~~~~ + +Note that arguments to functions created by `mocksignature` are always passed +in to the underlying mock by position even when called with keywords: + +.. doctest:: + + >>> def function(a, b, c=None): + ... pass + ... + >>> function = mocksignature(function) + >>> function.return_value = None + >>> function(1, 2) + >>> function.assert_called_with(1, 2, None) + + +Mocking methods and self +~~~~~~~~~~~~~~~~~~~~~~~~ + +When you use `mocksignature` to replace a method on a class then `self` +will be included in the method signature - and you will need to include +the instance when you do your asserts. + +As a curious factor of the way Python (2) wraps methods fetched from a class, +we can *get* the `return_value` from a function set on a class, but we can't +set it. We have to do this through the exposed `mock` attribute instead: + +.. doctest:: + + >>> class SomeClass(object): + ... def method(self, a, b, c=None): + ... pass + ... + >>> SomeClass.method = mocksignature(SomeClass.method) + >>> SomeClass.method.mock.return_value = None + >>> instance = SomeClass() + >>> instance.method() + Traceback (most recent call last): + ... + TypeError: <lambda>() takes at least 4 arguments (1 given) + >>> instance.method(1, 2, 3) + >>> instance.method.assert_called_with(instance, 1, 2, 3) + +When you use `mocksignature` on instance methods `self` isn't included (and we +can set the `return_value` etc directly): + +.. doctest:: + + >>> class SomeClass(object): + ... def method(self, a, b, c=None): + ... pass + ... + >>> instance = SomeClass() + >>> instance.method = mocksignature(instance.method) + >>> instance.method.return_value = None + >>> instance.method(1, 2, 3) + >>> instance.method.assert_called_with(1, 2, 3) + + +mocksignature with classes +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When used with a class `mocksignature` copies the signature of the `__init__` +method. + +.. doctest:: + + >>> class Something(object): + ... def __init__(self, foo, bar): + ... pass + ... + >>> MockSomething = mocksignature(Something) + >>> instance = MockSomething(10, 9) + >>> assert instance is MockSomething.return_value + >>> MockSomething.assert_called_with(10, 9) + >>> MockSomething() + Traceback (most recent call last): + ... + TypeError: <lambda>() takes at least 2 arguments (0 given) + +Because the object returned by `mocksignature` is a function rather than a +`Mock` you lose the other capabilities of `Mock`, like dynamic attribute +creation. + + +mocksignature with callable objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When used with a callable object `mocksignature` copies the signature of the +`__call__` method. + +.. doctest:: + + >>> class Something(object): + ... def __call__(self, spam, eggs): + ... pass + ... + >>> something = Something() + >>> mock_something = mocksignature(something) + >>> result = mock_something(10, 9) + >>> mock_something.assert_called_with(10, 9) + >>> mock_something() + Traceback (most recent call last): + ... + TypeError: <lambda>() takes at least 2 arguments (0 given) + + +mocksignature argument to patch +------------------------------- + +`mocksignature` is available as a keyword argument to :func:`patch` or +:func:`patch.object`. It can be used with functions / methods / classes and +callable objects. + +.. doctest:: + + >>> class SomeClass(object): + ... def method(self, a, b, c=None): + ... pass + ... + >>> @patch.object(SomeClass, 'method', mocksignature=True) + ... def test(mock_method): + ... instance = SomeClass() + ... mock_method.return_value = None + ... instance.method(1, 2) + ... mock_method.assert_called_with(instance, 1, 2, None) + ... + >>> test() |