The Tor Browser: python/mock-1.0.0/docs/helpers.txt@925c144e1f1f (annotated)

python/mock-1.0.0/docs/helpers.txt@925c144e1f1f (annotated)

python/mock-1.0.0/docs/helpers.txt

Fri, 16 Jan 2015 18:13:44 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Fri, 16 Jan 2015 18:13:44 +0100
branch: TOR_BUG_9701
changeset 14: 925c144e1f1f
permissions: -rw-r--r--

Integrate suggestion from review to improve consistency with existing code.

 =========
  Helpers
 =========
 .. currentmodule:: mock
 .. testsetup::
     mock.FILTER_DIR = True
     from pprint import pprint as pp
     original_dir = dir
     def dir(obj):
         print pp(original_dir(obj))
     import urllib2
     __main__.urllib2 = urllib2
 .. testcleanup::
     dir = original_dir
     mock.FILTER_DIR = True
 call
 ====
 .. function:: call(*args, **kwargs)
     `call` is a helper object for making simpler assertions, for comparing
     with :attr:`~Mock.call_args`, :attr:`~Mock.call_args_list`,
     :attr:`~Mock.mock_calls` and :attr: `~Mock.method_calls`. `call` can also be
     used with :meth:`~Mock.assert_has_calls`.
     .. doctest::
         >>> m = MagicMock(return_value=None)
         >>> m(1, 2, a='foo', b='bar')
         >>> m()
         >>> m.call_args_list == [call(1, 2, a='foo', b='bar'), call()]
         True
 .. method:: call.call_list()
     For a call object that represents multiple calls, `call_list`
     returns a list of all the intermediate calls as well as the
     final call.
 `call_list` is particularly useful for making assertions on "chained calls". A
 chained call is multiple calls on a single line of code. This results in
 multiple entries in :attr:`~Mock.mock_calls` on a mock. Manually constructing
 the sequence of calls can be tedious.
 :meth:`~call.call_list` can construct the sequence of calls from the same
 chained call:
 .. doctest::
     >>> m = MagicMock()
     >>> m(1).method(arg='foo').other('bar')(2.0)
     <MagicMock name='mock().method().other()()' id='...'>
     >>> kall = call(1).method(arg='foo').other('bar')(2.0)
     >>> kall.call_list()
     [call(1),
      call().method(arg='foo'),
      call().method().other('bar'),
      call().method().other()(2.0)]
     >>> m.mock_calls == kall.call_list()
     True
 .. _calls-as-tuples:
 A `call` object is either a tuple of (positional args, keyword args) or
 (name, positional args, keyword args) depending on how it was constructed. When
 you construct them yourself this isn't particularly interesting, but the `call`
 objects that are in the :attr:`Mock.call_args`, :attr:`Mock.call_args_list` and
 :attr:`Mock.mock_calls` attributes can be introspected to get at the individual
 arguments they contain.
 The `call` objects in :attr:`Mock.call_args` and :attr:`Mock.call_args_list`
 are two-tuples of (positional args, keyword args) whereas the `call` objects
 in :attr:`Mock.mock_calls`, along with ones you construct yourself, are
 three-tuples of (name, positional args, keyword args).
 You can use their "tupleness" to pull out the individual arguments for more
 complex introspection and assertions. The positional arguments are a tuple
 (an empty tuple if there are no positional arguments) and the keyword
 arguments are a dictionary:
 .. doctest::
     >>> m = MagicMock(return_value=None)
     >>> m(1, 2, 3, arg='one', arg2='two')
     >>> kall = m.call_args
     >>> args, kwargs = kall
     >>> args
     (1, 2, 3)
     >>> kwargs
     {'arg2': 'two', 'arg': 'one'}
     >>> args is kall[0]
     True
     >>> kwargs is kall[1]
     True
     >>> m = MagicMock()
     >>> m.foo(4, 5, 6, arg='two', arg2='three')
     <MagicMock name='mock.foo()' id='...'>
     >>> kall = m.mock_calls[0]
     >>> name, args, kwargs = kall
     >>> name
     'foo'
     >>> args
     (4, 5, 6)
     >>> kwargs
     {'arg2': 'three', 'arg': 'two'}
     >>> name is m.mock_calls[0][0]
     True
 create_autospec
 ===============
 .. function:: create_autospec(spec, spec_set=False, instance=False, **kwargs)
     Create a mock object using another object as a spec. Attributes on the
     mock will use the corresponding attribute on the `spec` object as their
     spec.
     Functions or methods being mocked will have their arguments checked to
     ensure that they are called with the correct signature.
     If `spec_set` is `True` then attempting to set attributes that don't exist
     on the spec object will raise an `AttributeError`.
     If a class is used as a spec then the return value of the mock (the
     instance of the class) will have the same spec. You can use a class as the
     spec for an instance object by passing `instance=True`. The returned mock
     will only be callable if instances of the mock are callable.
     `create_autospec` also takes arbitrary keyword arguments that are passed to
     the constructor of the created mock.
 See :ref:`auto-speccing` for examples of how to use auto-speccing with
 `create_autospec` and the `autospec` argument to :func:`patch`.
 ANY
 ===
 .. data:: ANY
 Sometimes you may need to make assertions about *some* of the arguments in a
 call to mock, but either not care about some of the arguments or want to pull
 them individually out of :attr:`~Mock.call_args` and make more complex
 assertions on them.
 To ignore certain arguments you can pass in objects that compare equal to
 *everything*. Calls to :meth:`~Mock.assert_called_with` and
 :meth:`~Mock.assert_called_once_with` will then succeed no matter what was
 passed in.
 .. doctest::
     >>> mock = Mock(return_value=None)
     >>> mock('foo', bar=object())
     >>> mock.assert_called_once_with('foo', bar=ANY)
 `ANY` can also be used in comparisons with call lists like
 :attr:`~Mock.mock_calls`:
 .. doctest::
     >>> m = MagicMock(return_value=None)
     >>> m(1)
     >>> m(1, 2)
     >>> m(object())
     >>> m.mock_calls == [call(1), call(1, 2), ANY]
     True
 FILTER_DIR
 ==========
 .. data:: FILTER_DIR
 `FILTER_DIR` is a module level variable that controls the way mock objects
 respond to `dir` (only for Python 2.6 or more recent). The default is `True`,
 which uses the filtering described below, to only show useful members. If you
 dislike this filtering, or need to switch it off for diagnostic purposes, then
 set `mock.FILTER_DIR = False`.
 With filtering on, `dir(some_mock)` shows only useful attributes and will
 include any dynamically created attributes that wouldn't normally be shown.
 If the mock was created with a `spec` (or `autospec` of course) then all the
 attributes from the original are shown, even if they haven't been accessed
 yet:
 .. doctest::
     >>> dir(Mock())
     ['assert_any_call',
      'assert_called_once_with',
      'assert_called_with',
      'assert_has_calls',
      'attach_mock',
      ...
     >>> import urllib2
     >>> dir(Mock(spec=urllib2))
     ['AbstractBasicAuthHandler',
      'AbstractDigestAuthHandler',
      'AbstractHTTPHandler',
      'BaseHandler',
      ...
 Many of the not-very-useful (private to `Mock` rather than the thing being
 mocked) underscore and double underscore prefixed attributes have been
 filtered from the result of calling `dir` on a `Mock`. If you dislike this
 behaviour you can switch it off by setting the module level switch
 `FILTER_DIR`:
 .. doctest::
     >>> import mock
     >>> mock.FILTER_DIR = False
     >>> dir(mock.Mock())
     ['_NonCallableMock__get_return_value',
      '_NonCallableMock__get_side_effect',
      '_NonCallableMock__return_value_doc',
      '_NonCallableMock__set_return_value',
      '_NonCallableMock__set_side_effect',
      '__call__',
      '__class__',
      ...
 Alternatively you can just use `vars(my_mock)` (instance members) and
 `dir(type(my_mock))` (type members) to bypass the filtering irrespective of
 `mock.FILTER_DIR`.
 mock_open
 =========
 .. function:: mock_open(mock=None, read_data=None)
     A helper function to create a mock to replace the use of `open`. It works
     for `open` called directly or used as a context manager.
     The `mock` argument is the mock object to configure. If `None` (the
     default) then a `MagicMock` will be created for you, with the API limited
     to methods or attributes available on standard file handles.
     `read_data` is a string for the `read` method of the file handle to return.
     This is an empty string by default.
 Using `open` as a context manager is a great way to ensure your file handles
 are closed properly and is becoming common::
     with open('/some/path', 'w') as f:
         f.write('something')
 The issue is that even if you mock out the call to `open` it is the
 *returned object* that is used as a context manager (and has `__enter__` and
 `__exit__` called).
 Mocking context managers with a :class:`MagicMock` is common enough and fiddly
 enough that a helper function is useful.
 .. doctest::
     >>> from mock import mock_open
     >>> m = mock_open()
     >>> with patch('__main__.open', m, create=True):
     ...     with open('foo', 'w') as h:
     ...         h.write('some stuff')
     ...
     >>> m.mock_calls
     [call('foo', 'w'),
      call().__enter__(),
      call().write('some stuff'),
      call().__exit__(None, None, None)]
     >>> m.assert_called_once_with('foo', 'w')
     >>> handle = m()
     >>> handle.write.assert_called_once_with('some stuff')
 And for reading files:
 .. doctest::
     >>> with patch('__main__.open', mock_open(read_data='bibble'), create=True) as m:
     ...     with open('foo') as h:
     ...         result = h.read()
     ...
     >>> m.assert_called_once_with('foo')
     >>> assert result == 'bibble'
 .. _auto-speccing:
 Autospeccing
 ============
 Autospeccing is based on the existing `spec` feature of mock. It limits the
 api of mocks to the api of an original object (the spec), but it is recursive
 (implemented lazily) so that attributes of mocks only have the same api as
 the attributes of the spec. In addition mocked functions / methods have the
 same call signature as the original so they raise a `TypeError` if they are
 called incorrectly.
 Before I explain how auto-speccing works, here's why it is needed.
 `Mock` is a very powerful and flexible object, but it suffers from two flaws
 when used to mock out objects from a system under test. One of these flaws is
 specific to the `Mock` api and the other is a more general problem with using
 mock objects.
 First the problem specific to `Mock`. `Mock` has two assert methods that are
 extremely handy: :meth:`~Mock.assert_called_with` and
 :meth:`~Mock.assert_called_once_with`.
 .. doctest::
     >>> mock = Mock(name='Thing', return_value=None)
     >>> mock(1, 2, 3)
     >>> mock.assert_called_once_with(1, 2, 3)
     >>> mock(1, 2, 3)
     >>> mock.assert_called_once_with(1, 2, 3)
     Traceback (most recent call last):
      ...
     AssertionError: Expected to be called once. Called 2 times.
 Because mocks auto-create attributes on demand, and allow you to call them
 with arbitrary arguments, if you misspell one of these assert methods then
 your assertion is gone:
 .. code-block:: pycon
     >>> mock = Mock(name='Thing', return_value=None)
     >>> mock(1, 2, 3)
     >>> mock.assret_called_once_with(4, 5, 6)
 Your tests can pass silently and incorrectly because of the typo.
 The second issue is more general to mocking. If you refactor some of your
 code, rename members and so on, any tests for code that is still using the
 *old api* but uses mocks instead of the real objects will still pass. This
 means your tests can all pass even though your code is broken.
 Note that this is another reason why you need integration tests as well as
 unit tests. Testing everything in isolation is all fine and dandy, but if you
 don't test how your units are "wired together" there is still lots of room
 for bugs that tests might have caught.
 `mock` already provides a feature to help with this, called speccing. If you
 use a class or instance as the `spec` for a mock then you can only access
 attributes on the mock that exist on the real class:
 .. doctest::
     >>> import urllib2
     >>> mock = Mock(spec=urllib2.Request)
     >>> mock.assret_called_with
     Traceback (most recent call last):
      ...
     AttributeError: Mock object has no attribute 'assret_called_with'
 The spec only applies to the mock itself, so we still have the same issue
 with any methods on the mock:
 .. code-block:: pycon
     >>> mock.has_data()
     <mock.Mock object at 0x...>
     >>> mock.has_data.assret_called_with()
 Auto-speccing solves this problem. You can either pass `autospec=True` to
 `patch` / `patch.object` or use the `create_autospec` function to create a
 mock with a spec. If you use the `autospec=True` argument to `patch` then the
 object that is being replaced will be used as the spec object. Because the
 speccing is done "lazily" (the spec is created as attributes on the mock are
 accessed) you can use it with very complex or deeply nested objects (like
 modules that import modules that import modules) without a big performance
 hit.
 Here's an example of it in use:
 .. doctest::
     >>> import urllib2
     >>> patcher = patch('__main__.urllib2', autospec=True)
     >>> mock_urllib2 = patcher.start()
     >>> urllib2 is mock_urllib2
     True
     >>> urllib2.Request
     <MagicMock name='urllib2.Request' spec='Request' id='...'>
 You can see that `urllib2.Request` has a spec. `urllib2.Request` takes two
 arguments in the constructor (one of which is `self`). Here's what happens if
 we try to call it incorrectly:
 .. doctest::
     >>> req = urllib2.Request()
     Traceback (most recent call last):
      ...
     TypeError: <lambda>() takes at least 2 arguments (1 given)
 The spec also applies to instantiated classes (i.e. the return value of
 specced mocks):
 .. doctest::
     >>> req = urllib2.Request('foo')
     >>> req
     <NonCallableMagicMock name='urllib2.Request()' spec='Request' id='...'>
 `Request` objects are not callable, so the return value of instantiating our
 mocked out `urllib2.Request` is a non-callable mock. With the spec in place
 any typos in our asserts will raise the correct error:
 .. doctest::
     >>> req.add_header('spam', 'eggs')
     <MagicMock name='urllib2.Request().add_header()' id='...'>
     >>> req.add_header.assret_called_with
     Traceback (most recent call last):
      ...
     AttributeError: Mock object has no attribute 'assret_called_with'
     >>> req.add_header.assert_called_with('spam', 'eggs')
 In many cases you will just be able to add `autospec=True` to your existing
 `patch` calls and then be protected against bugs due to typos and api
 changes.
 As well as using `autospec` through `patch` there is a
 :func:`create_autospec` for creating autospecced mocks directly:
 .. doctest::
     >>> import urllib2
     >>> mock_urllib2 = create_autospec(urllib2)
     >>> mock_urllib2.Request('foo', 'bar')
     <NonCallableMagicMock name='mock.Request()' spec='Request' id='...'>
 This isn't without caveats and limitations however, which is why it is not
 the default behaviour. In order to know what attributes are available on the
 spec object, autospec has to introspect (access attributes) the spec. As you
 traverse attributes on the mock a corresponding traversal of the original
 object is happening under the hood. If any of your specced objects have
 properties or descriptors that can trigger code execution then you may not be
 able to use autospec. On the other hand it is much better to design your
 objects so that introspection is safe [#]_.
 A more serious problem is that it is common for instance attributes to be
 created in the `__init__` method and not to exist on the class at all.
 `autospec` can't know about any dynamically created attributes and restricts
 the api to visible attributes.
 .. doctest::
     >>> class Something(object):
     ...   def __init__(self):
     ...     self.a = 33
     ...
     >>> with patch('__main__.Something', autospec=True):
     ...   thing = Something()
     ...   thing.a
     ...
     Traceback (most recent call last):
       ...
     AttributeError: Mock object has no attribute 'a'
 There are a few different ways of resolving this problem. The easiest, but
 not necessarily the least annoying, way is to simply set the required
 attributes on the mock after creation. Just because `autospec` doesn't allow
 you to fetch attributes that don't exist on the spec it doesn't prevent you
 setting them:
 .. doctest::
     >>> with patch('__main__.Something', autospec=True):
     ...   thing = Something()
     ...   thing.a = 33
     ...
 There is a more aggressive version of both `spec` and `autospec` that *does*
 prevent you setting non-existent attributes. This is useful if you want to
 ensure your code only *sets* valid attributes too, but obviously it prevents
 this particular scenario:
 .. doctest::
     >>> with patch('__main__.Something', autospec=True, spec_set=True):
     ...   thing = Something()
     ...   thing.a = 33
     ...
     Traceback (most recent call last):
      ...
     AttributeError: Mock object has no attribute 'a'
 Probably the best way of solving the problem is to add class attributes as
 default values for instance members initialised in `__init__`. Note that if
 you are only setting default attributes in `__init__` then providing them via
 class attributes (shared between instances of course) is faster too. e.g.
 .. code-block:: python
     class Something(object):
         a = 33
 This brings up another issue. It is relatively common to provide a default
 value of `None` for members that will later be an object of a different type.
 `None` would be useless as a spec because it wouldn't let you access *any*
 attributes or methods on it. As `None` is *never* going to be useful as a
 spec, and probably indicates a member that will normally of some other type,
 `autospec` doesn't use a spec for members that are set to `None`. These will
 just be ordinary mocks (well - `MagicMocks`):
 .. doctest::
     >>> class Something(object):
     ...     member = None
     ...
     >>> mock = create_autospec(Something)
     >>> mock.member.foo.bar.baz()
     <MagicMock name='mock.member.foo.bar.baz()' id='...'>
 If modifying your production classes to add defaults isn't to your liking
 then there are more options. One of these is simply to use an instance as the
 spec rather than the class. The other is to create a subclass of the
 production class and add the defaults to the subclass without affecting the
 production class. Both of these require you to use an alternative object as
 the spec. Thankfully `patch` supports this - you can simply pass the
 alternative object as the `autospec` argument:
 .. doctest::
     >>> class Something(object):
     ...   def __init__(self):
     ...     self.a = 33
     ...
     >>> class SomethingForTest(Something):
     ...   a = 33
     ...
     >>> p = patch('__main__.Something', autospec=SomethingForTest)
     >>> mock = p.start()
     >>> mock.a
     <NonCallableMagicMock name='Something.a' spec='int' id='...'>
 .. note::
     An additional limitation (currently) with `autospec` is that unbound
     methods on mocked classes *don't* take an "explicit self" as the first
     argument - so this usage will fail with `autospec`.
     .. doctest::
         >>> class Foo(object):
         ...   def foo(self):
         ...     pass
         ...
         >>> Foo.foo(Foo())
         >>> MockFoo = create_autospec(Foo)
         >>> MockFoo.foo(MockFoo())
         Traceback (most recent call last):
           ...
         TypeError: <lambda>() takes exactly 1 argument (2 given)
     The reason is that its very hard to tell the difference between functions,
     unbound methods and staticmethods across Python 2 & 3 and the alternative
     implementations. This restriction may be fixed in future versions.
 ------
 .. [#] This only applies to classes or already instantiated objects. Calling
    a mocked class to create a mock instance *does not* create a real instance.
    It is only attribute lookups - along with calls to `dir` - that are done. A
    way round this problem would have been to use `getattr_static
    <http://docs.python.org/dev/library/inspect.html#inspect.getattr_static>`_,
    which can fetch attributes without triggering code execution. Descriptors
    like `classmethod` and `staticmethod` *need* to be fetched correctly though,
    so that their signatures can be mocked correctly.

The Tor Browser / annotate

python/mock-1.0.0/docs/helpers.txt@925c144e1f1f (annotated)

python/mock-1.0.0/docs/helpers.txt