Re-order unittest.mock documentation to put magic method support before the helpers

1 files changed, 220 insertions, 219 deletions

diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index df6665b..153dcab 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -1444,6 +1444,226 @@ that proxy attribute access, like the `django setttings object
 <http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198>`_.
 
 
+MagicMock and magic method support
+==================================
+
+.. _magic-methods:
+
+Mocking Magic Methods
+---------------------
+
+:class:`Mock` supports mocking the Python protocol methods, also known as
+"magic methods". This allows mock objects to replace containers or other
+objects that implement Python protocols.
+
+Because magic methods are looked up differently from normal methods [#]_, this
+support has been specially implemented. This means that only specific magic
+methods are supported. The supported list includes *almost* all of them. If
+there are any missing that you need please let us know.
+
+You mock magic methods by setting the method you are interested in to a function
+or a mock instance. If you are using a function then it *must* take ``self`` as
+the first argument [#]_.
+
+   >>> def __str__(self):
+   ...     return 'fooble'
+   ...
+   >>> mock = Mock()
+   >>> mock.__str__ = __str__
+   >>> str(mock)
+   'fooble'
+
+   >>> mock = Mock()
+   >>> mock.__str__ = Mock()
+   >>> mock.__str__.return_value = 'fooble'
+   >>> str(mock)
+   'fooble'
+
+   >>> mock = Mock()
+   >>> mock.__iter__ = Mock(return_value=iter([]))
+   >>> list(mock)
+   []
+
+One use case for this is for mocking objects used as context managers in a
+`with` statement:
+
+   >>> mock = Mock()
+   >>> mock.__enter__ = Mock(return_value='foo')
+   >>> mock.__exit__ = Mock(return_value=False)
+   >>> with mock as m:
+   ...     assert m == 'foo'
+   ...
+   >>> mock.__enter__.assert_called_with()
+   >>> mock.__exit__.assert_called_with(None, None, None)
+
+Calls to magic methods do not appear in :attr:`~Mock.method_calls`, but they
+are recorded in :attr:`~Mock.mock_calls`.
+
+.. note::
+
+   If you use the `spec` keyword argument to create a mock then attempting to
+   set a magic method that isn't in the spec will raise an `AttributeError`.
+
+The full list of supported magic methods is:
+
+* ``__hash__``, ``__sizeof__``, ``__repr__`` and ``__str__``
+* ``__dir__``, ``__format__`` and ``__subclasses__``
+* ``__floor__``, ``__trunc__`` and ``__ceil__``
+* Comparisons: ``__cmp__``, ``__lt__``, ``__gt__``, ``__le__``, ``__ge__``,
+  ``__eq__`` and ``__ne__``
+* Container methods: ``__getitem__``, ``__setitem__``, ``__delitem__``,
+  ``__contains__``, ``__len__``, ``__iter__``, ``__getslice__``,
+  ``__setslice__``, ``__reversed__`` and ``__missing__``
+* Context manager: ``__enter__`` and ``__exit__``
+* Unary numeric methods: ``__neg__``, ``__pos__`` and ``__invert__``
+* The numeric methods (including right hand and in-place variants):
+  ``__add__``, ``__sub__``, ``__mul__``, ``__div__``,
+  ``__floordiv__``, ``__mod__``, ``__divmod__``, ``__lshift__``,
+  ``__rshift__``, ``__and__``, ``__xor__``, ``__or__``, and ``__pow__``
+* Numeric conversion methods: ``__complex__``, ``__int__``, ``__float__``,
+  ``__index__`` and ``__coerce__``
+* Descriptor methods: ``__get__``, ``__set__`` and ``__delete__``
+* Pickling: ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``,
+  ``__getnewargs__``, ``__getstate__`` and ``__setstate__``
+
+
+The following methods exist but are *not* supported as they are either in use
+by mock, can't be set dynamically, or can cause problems:
+
+* ``__getattr__``, ``__setattr__``, ``__init__`` and ``__new__``
+* ``__prepare__``, ``__instancecheck__``, ``__subclasscheck__``, ``__del__``
+
+
+
+Magic Mock
+----------
+
+There are two `MagicMock` variants: `MagicMock` and `NonCallableMagicMock`.
+
+
+.. class:: MagicMock(*args, **kw)
+
+   ``MagicMock`` is a subclass of :class:`Mock` with default implementations
+   of most of the magic methods. You can use ``MagicMock`` without having to
+   configure the magic methods yourself.
+
+   The constructor parameters have the same meaning as for :class:`Mock`.
+
+   If you use the `spec` or `spec_set` arguments then *only* magic methods
+   that exist in the spec will be created.
+
+
+.. class:: NonCallableMagicMock(*args, **kw)
+
+    A non-callable version of `MagicMock`.
+
+    The constructor parameters have the same meaning as for
+    :class:`MagicMock`, with the exception of `return_value` and
+    `side_effect` which have no meaning on a non-callable mock.
+
+The magic methods are setup with `MagicMock` objects, so you can configure them
+and use them in the usual way:
+
+   >>> mock = MagicMock()
+   >>> mock[3] = 'fish'
+   >>> mock.__setitem__.assert_called_with(3, 'fish')
+   >>> mock.__getitem__.return_value = 'result'
+   >>> mock[2]
+   'result'
+
+By default many of the protocol methods are required to return objects of a
+specific type. These methods are preconfigured with a default return value, so
+that they can be used without you having to do anything if you aren't interested
+in the return value. You can still *set* the return value manually if you want
+to change the default.
+
+Methods and their defaults:
+
+* ``__lt__``: NotImplemented
+* ``__gt__``: NotImplemented
+* ``__le__``: NotImplemented
+* ``__ge__``: NotImplemented
+* ``__int__`` : 1
+* ``__contains__`` : False
+* ``__len__`` : 1
+* ``__iter__`` : iter([])
+* ``__exit__`` : False
+* ``__complex__`` : 1j
+* ``__float__`` : 1.0
+* ``__bool__`` : True
+* ``__index__`` : 1
+* ``__hash__`` : default hash for the mock
+* ``__str__`` : default str for the mock
+* ``__sizeof__``: default sizeof for the mock
+
+For example:
+
+   >>> mock = MagicMock()
+   >>> int(mock)
+   1
+   >>> len(mock)
+   0
+   >>> list(mock)
+   []
+   >>> object() in mock
+   False
+
+The two equality method, `__eq__` and `__ne__`, are special.
+They do the default equality comparison on identity, using a side
+effect, unless you change their return value to return something else:
+
+   >>> MagicMock() == 3
+   False
+   >>> MagicMock() != 3
+   True
+   >>> mock = MagicMock()
+   >>> mock.__eq__.return_value = True
+   >>> mock == 3
+   True
+
+The return value of `MagicMock.__iter__` can be any iterable object and isn't
+required to be an iterator:
+
+   >>> mock = MagicMock()
+   >>> mock.__iter__.return_value = ['a', 'b', 'c']
+   >>> list(mock)
+   ['a', 'b', 'c']
+   >>> list(mock)
+   ['a', 'b', 'c']
+
+If the return value *is* an iterator, then iterating over it once will consume
+it and subsequent iterations will result in an empty list:
+
+   >>> mock.__iter__.return_value = iter(['a', 'b', 'c'])
+   >>> list(mock)
+   ['a', 'b', 'c']
+   >>> list(mock)
+   []
+
+``MagicMock`` has all of the supported magic methods configured except for some
+of the obscure and obsolete ones. You can still set these up if you want.
+
+Magic methods that are supported but not setup by default in ``MagicMock`` are:
+
+* ``__subclasses__``
+* ``__dir__``
+* ``__format__``
+* ``__get__``, ``__set__`` and ``__delete__``
+* ``__reversed__`` and ``__missing__``
+* ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``, ``__getnewargs__``,
+  ``__getstate__`` and ``__setstate__``
+* ``__getformat__`` and ``__setformat__``
+
+
+
+.. [#] Magic methods *should* be looked up on the class rather than the
+   instance. Different versions of Python are inconsistent about applying this
+   rule. The supported protocol methods should work with all supported versions
+   of Python.
+.. [#] The function is basically hooked up to the class, but each ``Mock``
+   instance is kept isolated from the others.
+
+
 Helpers
 =======
 
@@ -1974,222 +2194,3 @@ alternative object as the `autospec` argument:
    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.
 
-
-MagicMock and magic method support
-==================================
-
-.. _magic-methods:
-
-Mocking Magic Methods
----------------------
-
-:class:`Mock` supports mocking the Python protocol methods, also known as
-"magic methods". This allows mock objects to replace containers or other
-objects that implement Python protocols.
-
-Because magic methods are looked up differently from normal methods [#]_, this
-support has been specially implemented. This means that only specific magic
-methods are supported. The supported list includes *almost* all of them. If
-there are any missing that you need please let us know.
-
-You mock magic methods by setting the method you are interested in to a function
-or a mock instance. If you are using a function then it *must* take ``self`` as
-the first argument [#]_.
-
-   >>> def __str__(self):
-   ...     return 'fooble'
-   ...
-   >>> mock = Mock()
-   >>> mock.__str__ = __str__
-   >>> str(mock)
-   'fooble'
-
-   >>> mock = Mock()
-   >>> mock.__str__ = Mock()
-   >>> mock.__str__.return_value = 'fooble'
-   >>> str(mock)
-   'fooble'
-
-   >>> mock = Mock()
-   >>> mock.__iter__ = Mock(return_value=iter([]))
-   >>> list(mock)
-   []
-
-One use case for this is for mocking objects used as context managers in a
-`with` statement:
-
-   >>> mock = Mock()
-   >>> mock.__enter__ = Mock(return_value='foo')
-   >>> mock.__exit__ = Mock(return_value=False)
-   >>> with mock as m:
-   ...     assert m == 'foo'
-   ...
-   >>> mock.__enter__.assert_called_with()
-   >>> mock.__exit__.assert_called_with(None, None, None)
-
-Calls to magic methods do not appear in :attr:`~Mock.method_calls`, but they
-are recorded in :attr:`~Mock.mock_calls`.
-
-.. note::
-
-   If you use the `spec` keyword argument to create a mock then attempting to
-   set a magic method that isn't in the spec will raise an `AttributeError`.
-
-The full list of supported magic methods is:
-
-* ``__hash__``, ``__sizeof__``, ``__repr__`` and ``__str__``
-* ``__dir__``, ``__format__`` and ``__subclasses__``
-* ``__floor__``, ``__trunc__`` and ``__ceil__``
-* Comparisons: ``__cmp__``, ``__lt__``, ``__gt__``, ``__le__``, ``__ge__``,
-  ``__eq__`` and ``__ne__``
-* Container methods: ``__getitem__``, ``__setitem__``, ``__delitem__``,
-  ``__contains__``, ``__len__``, ``__iter__``, ``__getslice__``,
-  ``__setslice__``, ``__reversed__`` and ``__missing__``
-* Context manager: ``__enter__`` and ``__exit__``
-* Unary numeric methods: ``__neg__``, ``__pos__`` and ``__invert__``
-* The numeric methods (including right hand and in-place variants):
-  ``__add__``, ``__sub__``, ``__mul__``, ``__div__``,
-  ``__floordiv__``, ``__mod__``, ``__divmod__``, ``__lshift__``,
-  ``__rshift__``, ``__and__``, ``__xor__``, ``__or__``, and ``__pow__``
-* Numeric conversion methods: ``__complex__``, ``__int__``, ``__float__``,
-  ``__index__`` and ``__coerce__``
-* Descriptor methods: ``__get__``, ``__set__`` and ``__delete__``
-* Pickling: ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``,
-  ``__getnewargs__``, ``__getstate__`` and ``__setstate__``
-
-
-The following methods exist but are *not* supported as they are either in use
-by mock, can't be set dynamically, or can cause problems:
-
-* ``__getattr__``, ``__setattr__``, ``__init__`` and ``__new__``
-* ``__prepare__``, ``__instancecheck__``, ``__subclasscheck__``, ``__del__``
-
-
-
-Magic Mock
-----------
-
-There are two `MagicMock` variants: `MagicMock` and `NonCallableMagicMock`.
-
-
-.. class:: MagicMock(*args, **kw)
-
-   ``MagicMock`` is a subclass of :class:`Mock` with default implementations
-   of most of the magic methods. You can use ``MagicMock`` without having to
-   configure the magic methods yourself.
-
-   The constructor parameters have the same meaning as for :class:`Mock`.
-
-   If you use the `spec` or `spec_set` arguments then *only* magic methods
-   that exist in the spec will be created.
-
-
-.. class:: NonCallableMagicMock(*args, **kw)
-
-    A non-callable version of `MagicMock`.
-
-    The constructor parameters have the same meaning as for
-    :class:`MagicMock`, with the exception of `return_value` and
-    `side_effect` which have no meaning on a non-callable mock.
-
-The magic methods are setup with `MagicMock` objects, so you can configure them
-and use them in the usual way:
-
-   >>> mock = MagicMock()
-   >>> mock[3] = 'fish'
-   >>> mock.__setitem__.assert_called_with(3, 'fish')
-   >>> mock.__getitem__.return_value = 'result'
-   >>> mock[2]
-   'result'
-
-By default many of the protocol methods are required to return objects of a
-specific type. These methods are preconfigured with a default return value, so
-that they can be used without you having to do anything if you aren't interested
-in the return value. You can still *set* the return value manually if you want
-to change the default.
-
-Methods and their defaults:
-
-* ``__lt__``: NotImplemented
-* ``__gt__``: NotImplemented
-* ``__le__``: NotImplemented
-* ``__ge__``: NotImplemented
-* ``__int__`` : 1
-* ``__contains__`` : False
-* ``__len__`` : 1
-* ``__iter__`` : iter([])
-* ``__exit__`` : False
-* ``__complex__`` : 1j
-* ``__float__`` : 1.0
-* ``__bool__`` : True
-* ``__index__`` : 1
-* ``__hash__`` : default hash for the mock
-* ``__str__`` : default str for the mock
-* ``__sizeof__``: default sizeof for the mock
-
-For example:
-
-   >>> mock = MagicMock()
-   >>> int(mock)
-   1
-   >>> len(mock)
-   0
-   >>> list(mock)
-   []
-   >>> object() in mock
-   False
-
-The two equality method, `__eq__` and `__ne__`, are special.
-They do the default equality comparison on identity, using a side
-effect, unless you change their return value to return something else:
-
-   >>> MagicMock() == 3
-   False
-   >>> MagicMock() != 3
-   True
-   >>> mock = MagicMock()
-   >>> mock.__eq__.return_value = True
-   >>> mock == 3
-   True
-
-The return value of `MagicMock.__iter__` can be any iterable object and isn't
-required to be an iterator:
-
-   >>> mock = MagicMock()
-   >>> mock.__iter__.return_value = ['a', 'b', 'c']
-   >>> list(mock)
-   ['a', 'b', 'c']
-   >>> list(mock)
-   ['a', 'b', 'c']
-
-If the return value *is* an iterator, then iterating over it once will consume
-it and subsequent iterations will result in an empty list:
-
-   >>> mock.__iter__.return_value = iter(['a', 'b', 'c'])
-   >>> list(mock)
-   ['a', 'b', 'c']
-   >>> list(mock)
-   []
-
-``MagicMock`` has all of the supported magic methods configured except for some
-of the obscure and obsolete ones. You can still set these up if you want.
-
-Magic methods that are supported but not setup by default in ``MagicMock`` are:
-
-* ``__subclasses__``
-* ``__dir__``
-* ``__format__``
-* ``__get__``, ``__set__`` and ``__delete__``
-* ``__reversed__`` and ``__missing__``
-* ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``, ``__getnewargs__``,
-  ``__getstate__`` and ``__setstate__``
-* ``__getformat__`` and ``__setformat__``
-
-
-
-.. [#] Magic methods *should* be looked up on the class rather than the
-   instance. Different versions of Python are inconsistent about applying this
-   rule. The supported protocol methods should work with all supported versions
-   of Python.
-.. [#] The function is basically hooked up to the class, but each ``Mock``
-   instance is kept isolated from the others.