According to the documentation .return_value should be identical to the object returned when calling the mock ("assert m() is m.return_value")

This is the case except on objects returned by __iter__ on MagicMocks. The following script demonstrates the problem:
----
from unittest.mock import MagicMock
m = MagicMock()
assert x.__iter__() is x.__iter__.return_value    # <- fails
----

In fact __iter__() returns the object "iter([])" (which matches the documentation) while __iter__.return_value return a MagicMock object (which does not match the documentation).

When replacing "__iter__" with any other special function MagicMock works as expected.

Can you please link to the relevant documentation that is misleading? As I can see from the source code return value is a Mock object [1] which I believe the docs state as below : 

https://docs.python.org/3/library/unittest.mock.html#calling

> Mock objects are callable. The call will return the value set as the return_value attribute. The default return value is a new Mock object; it is created the first time the return value is accessed (either explicitly or by calling the Mock) - but it is stored and the same one returned each time.

from unittest.mock import MagicMock
x = MagicMock()

print(x.__iter__())
print(x.__iter__.return_value)
print(x.return_value)


➜  cpython git:(master) ./python.exe bpo33236.py
<list_iterator object at 0x10d0797f0>
<MagicMock name='mock.__iter__()' id='4513568752'>
<MagicMock name='mock()' id='4513642816'>


[1] : https://github.com/python/cpython/blob/b10a64d117de6121ea3e79c467c4107f8f399f3d/Lib/unittest/mock.py#L463


Thanks

According to this chapter ( https://docs.python.org/3/library/unittest.mock.html#unittest.mock.MagicMock ) the specialmethods in MagicMock are different:

.return_value is preinitialized with defaultvalues, which depends on the operator. In the case of .__iter__ this is "iter([])".
This is the case when running __iter__(), but not when running __iter__.result_value

iter is initialized by using side_effects, not return_value.

The statement "According to the documentation .return_value should be identical to the object returned when calling the mock" works only when it return_value has been used to define the behaviour of the mock.

Example:

```
>>> m = MagicMock(side_effect=lambda: 1)
>>> m()
1
>>> m.return_value
<MagicMock name='mock()' id='140107830678472'>
>>> m() is m.return_value
False
```

This isn't a bug. This is the intended behaviour, otherwise MagicMock objects would error out on iteration.