The Tor Browser: python/mock-1.0.0/html/_sources/mocksignature.txt@141e0f1194b1 (annotated)

python/mock-1.0.0/html/_sources/mocksignature.txt@141e0f1194b1 (annotated)

python/mock-1.0.0/html/_sources/mocksignature.txt

Wed, 31 Dec 2014 07:16:47 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 07:16:47 +0100
branch: TOR_BUG_9701
changeset 3: 141e0f1194b1
permissions: -rw-r--r--

Revert simplistic fix pending revisit of Mozilla integration attempt.

 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)
 
     >>> 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
 
     >>> 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()

The Tor Browser / annotate

python/mock-1.0.0/html/_sources/mocksignature.txt@141e0f1194b1 (annotated)

python/mock-1.0.0/html/_sources/mocksignature.txt