1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/python/mock-1.0.0/html/_sources/magicmock.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,258 @@
1.4 +
1.5 +.. currentmodule:: mock
1.6 +
1.7 +
1.8 +.. _magic-methods:
1.9 +
1.10 +Mocking Magic Methods
1.11 +=====================
1.12 +
1.13 +.. currentmodule:: mock
1.14 +
1.15 +:class:`Mock` supports mocking `magic methods
1.16 +<http://www.ironpythoninaction.com/magic-methods.html>`_. This allows mock
1.17 +objects to replace containers or other objects that implement Python
1.18 +protocols.
1.19 +
1.20 +Because magic methods are looked up differently from normal methods [#]_, this
1.21 +support has been specially implemented. This means that only specific magic
1.22 +methods are supported. The supported list includes *almost* all of them. If
1.23 +there are any missing that you need please let us know!
1.24 +
1.25 +You mock magic methods by setting the method you are interested in to a function
1.26 +or a mock instance. If you are using a function then it *must* take ``self`` as
1.27 +the first argument [#]_.
1.28 +
1.29 +.. doctest::
1.30 +
1.31 + >>> def __str__(self):
1.32 + ... return 'fooble'
1.33 + ...
1.34 + >>> mock = Mock()
1.35 + >>> mock.__str__ = __str__
1.36 + >>> str(mock)
1.37 + 'fooble'
1.38 +
1.39 + >>> mock = Mock()
1.40 + >>> mock.__str__ = Mock()
1.41 + >>> mock.__str__.return_value = 'fooble'
1.42 + >>> str(mock)
1.43 + 'fooble'
1.44 +
1.45 + >>> mock = Mock()
1.46 + >>> mock.__iter__ = Mock(return_value=iter([]))
1.47 + >>> list(mock)
1.48 + []
1.49 +
1.50 +One use case for this is for mocking objects used as context managers in a
1.51 +`with` statement:
1.52 +
1.53 +.. doctest::
1.54 +
1.55 + >>> mock = Mock()
1.56 + >>> mock.__enter__ = Mock(return_value='foo')
1.57 + >>> mock.__exit__ = Mock(return_value=False)
1.58 + >>> with mock as m:
1.59 + ... assert m == 'foo'
1.60 + ...
1.61 + >>> mock.__enter__.assert_called_with()
1.62 + >>> mock.__exit__.assert_called_with(None, None, None)
1.63 +
1.64 +Calls to magic methods do not appear in :attr:`~Mock.method_calls`, but they
1.65 +are recorded in :attr:`~Mock.mock_calls`.
1.66 +
1.67 +.. note::
1.68 +
1.69 + If you use the `spec` keyword argument to create a mock then attempting to
1.70 + set a magic method that isn't in the spec will raise an `AttributeError`.
1.71 +
1.72 +The full list of supported magic methods is:
1.73 +
1.74 +* ``__hash__``, ``__sizeof__``, ``__repr__`` and ``__str__``
1.75 +* ``__dir__``, ``__format__`` and ``__subclasses__``
1.76 +* ``__floor__``, ``__trunc__`` and ``__ceil__``
1.77 +* Comparisons: ``__cmp__``, ``__lt__``, ``__gt__``, ``__le__``, ``__ge__``,
1.78 + ``__eq__`` and ``__ne__``
1.79 +* Container methods: ``__getitem__``, ``__setitem__``, ``__delitem__``,
1.80 + ``__contains__``, ``__len__``, ``__iter__``, ``__getslice__``,
1.81 + ``__setslice__``, ``__reversed__`` and ``__missing__``
1.82 +* Context manager: ``__enter__`` and ``__exit__``
1.83 +* Unary numeric methods: ``__neg__``, ``__pos__`` and ``__invert__``
1.84 +* The numeric methods (including right hand and in-place variants):
1.85 + ``__add__``, ``__sub__``, ``__mul__``, ``__div__``,
1.86 + ``__floordiv__``, ``__mod__``, ``__divmod__``, ``__lshift__``,
1.87 + ``__rshift__``, ``__and__``, ``__xor__``, ``__or__``, and ``__pow__``
1.88 +* Numeric conversion methods: ``__complex__``, ``__int__``, ``__float__``,
1.89 + ``__index__`` and ``__coerce__``
1.90 +* Descriptor methods: ``__get__``, ``__set__`` and ``__delete__``
1.91 +* Pickling: ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``,
1.92 + ``__getnewargs__``, ``__getstate__`` and ``__setstate__``
1.93 +
1.94 +
1.95 +The following methods are supported in Python 2 but don't exist in Python 3:
1.96 +
1.97 +* ``__unicode__``, ``__long__``, ``__oct__``, ``__hex__`` and ``__nonzero__``
1.98 +* ``__truediv__`` and ``__rtruediv__``
1.99 +
1.100 +The following methods are supported in Python 3 but don't exist in Python 2:
1.101 +
1.102 +* ``__bool__`` and ``__next__``
1.103 +
1.104 +The following methods exist but are *not* supported as they are either in use by
1.105 +mock, can't be set dynamically, or can cause problems:
1.106 +
1.107 +* ``__getattr__``, ``__setattr__``, ``__init__`` and ``__new__``
1.108 +* ``__prepare__``, ``__instancecheck__``, ``__subclasscheck__``, ``__del__``
1.109 +
1.110 +
1.111 +
1.112 +Magic Mock
1.113 +==========
1.114 +
1.115 +There are two `MagicMock` variants: `MagicMock` and `NonCallableMagicMock`.
1.116 +
1.117 +
1.118 +.. class:: MagicMock(*args, **kw)
1.119 +
1.120 + ``MagicMock`` is a subclass of :class:`Mock` with default implementations
1.121 + of most of the magic methods. You can use ``MagicMock`` without having to
1.122 + configure the magic methods yourself.
1.123 +
1.124 + The constructor parameters have the same meaning as for :class:`Mock`.
1.125 +
1.126 + If you use the `spec` or `spec_set` arguments then *only* magic methods
1.127 + that exist in the spec will be created.
1.128 +
1.129 +
1.130 +.. class:: NonCallableMagicMock(*args, **kw)
1.131 +
1.132 + A non-callable version of `MagicMock`.
1.133 +
1.134 + The constructor parameters have the same meaning as for
1.135 + :class:`MagicMock`, with the exception of `return_value` and
1.136 + `side_effect` which have no meaning on a non-callable mock.
1.137 +
1.138 +The magic methods are setup with `MagicMock` objects, so you can configure them
1.139 +and use them in the usual way:
1.140 +
1.141 +.. doctest::
1.142 +
1.143 + >>> mock = MagicMock()
1.144 + >>> mock[3] = 'fish'
1.145 + >>> mock.__setitem__.assert_called_with(3, 'fish')
1.146 + >>> mock.__getitem__.return_value = 'result'
1.147 + >>> mock[2]
1.148 + 'result'
1.149 +
1.150 +By default many of the protocol methods are required to return objects of a
1.151 +specific type. These methods are preconfigured with a default return value, so
1.152 +that they can be used without you having to do anything if you aren't interested
1.153 +in the return value. You can still *set* the return value manually if you want
1.154 +to change the default.
1.155 +
1.156 +Methods and their defaults:
1.157 +
1.158 +* ``__lt__``: NotImplemented
1.159 +* ``__gt__``: NotImplemented
1.160 +* ``__le__``: NotImplemented
1.161 +* ``__ge__``: NotImplemented
1.162 +* ``__int__`` : 1
1.163 +* ``__contains__`` : False
1.164 +* ``__len__`` : 1
1.165 +* ``__iter__`` : iter([])
1.166 +* ``__exit__`` : False
1.167 +* ``__complex__`` : 1j
1.168 +* ``__float__`` : 1.0
1.169 +* ``__bool__`` : True
1.170 +* ``__nonzero__`` : True
1.171 +* ``__oct__`` : '1'
1.172 +* ``__hex__`` : '0x1'
1.173 +* ``__long__`` : long(1)
1.174 +* ``__index__`` : 1
1.175 +* ``__hash__`` : default hash for the mock
1.176 +* ``__str__`` : default str for the mock
1.177 +* ``__unicode__`` : default unicode for the mock
1.178 +* ``__sizeof__``: default sizeof for the mock
1.179 +
1.180 +For example:
1.181 +
1.182 +.. doctest::
1.183 +
1.184 + >>> mock = MagicMock()
1.185 + >>> int(mock)
1.186 + 1
1.187 + >>> len(mock)
1.188 + 0
1.189 + >>> hex(mock)
1.190 + '0x1'
1.191 + >>> list(mock)
1.192 + []
1.193 + >>> object() in mock
1.194 + False
1.195 +
1.196 +The two equality method, `__eq__` and `__ne__`, are special (changed in
1.197 +0.7.2). They do the default equality comparison on identity, using a side
1.198 +effect, unless you change their return value to return something else:
1.199 +
1.200 +.. doctest::
1.201 +
1.202 + >>> MagicMock() == 3
1.203 + False
1.204 + >>> MagicMock() != 3
1.205 + True
1.206 + >>> mock = MagicMock()
1.207 + >>> mock.__eq__.return_value = True
1.208 + >>> mock == 3
1.209 + True
1.210 +
1.211 +In `0.8` the `__iter__` also gained special handling implemented with a
1.212 +side effect. The return value of `MagicMock.__iter__` can be any iterable
1.213 +object and isn't required to be an iterator:
1.214 +
1.215 +.. doctest::
1.216 +
1.217 + >>> mock = MagicMock()
1.218 + >>> mock.__iter__.return_value = ['a', 'b', 'c']
1.219 + >>> list(mock)
1.220 + ['a', 'b', 'c']
1.221 + >>> list(mock)
1.222 + ['a', 'b', 'c']
1.223 +
1.224 +If the return value *is* an iterator, then iterating over it once will consume
1.225 +it and subsequent iterations will result in an empty list:
1.226 +
1.227 +.. doctest::
1.228 +
1.229 + >>> mock.__iter__.return_value = iter(['a', 'b', 'c'])
1.230 + >>> list(mock)
1.231 + ['a', 'b', 'c']
1.232 + >>> list(mock)
1.233 + []
1.234 +
1.235 +``MagicMock`` has all of the supported magic methods configured except for some
1.236 +of the obscure and obsolete ones. You can still set these up if you want.
1.237 +
1.238 +Magic methods that are supported but not setup by default in ``MagicMock`` are:
1.239 +
1.240 +* ``__cmp__``
1.241 +* ``__getslice__`` and ``__setslice__``
1.242 +* ``__coerce__``
1.243 +* ``__subclasses__``
1.244 +* ``__dir__``
1.245 +* ``__format__``
1.246 +* ``__get__``, ``__set__`` and ``__delete__``
1.247 +* ``__reversed__`` and ``__missing__``
1.248 +* ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``, ``__getnewargs__``,
1.249 + ``__getstate__`` and ``__setstate__``
1.250 +* ``__getformat__`` and ``__setformat__``
1.251 +
1.252 +
1.253 +
1.254 +------------
1.255 +
1.256 +.. [#] Magic methods *should* be looked up on the class rather than the
1.257 + instance. Different versions of Python are inconsistent about applying this
1.258 + rule. The supported protocol methods should work with all supported versions
1.259 + of Python.
1.260 +.. [#] The function is basically hooked up to the class, but each ``Mock``
1.261 + instance is kept isolated from the others.
