Merge pull request #16 from tigarmo/tigarmo-contextmanager-docs

Update README.rst with contextmanager warning

Author: nicoddemus

README.rst

@@ -60,6 +60,24 @@ The supported methods are:
 * ``mocker.patch.dict``: see http://www.voidspace.org.uk/python/mock/patch.html#patch-dict.
 * ``mocker.stopall()``: stops all active patches at this point.
 
+Note that, although mocker's API is intentionally the same as ``mock.patch``'s, its uses as context managers and function decorators are **not** supported. The purpose of this plugin is to make the use of context managers and function decorators for mocking unnecessary. Indeed, trying to use the functionality in ``mocker`` in this manner can lead to non-intuitive errors:
+
+.. code-block:: python
+
+    def test_context_manager(mocker):
+        a = A()
+        with mocker.patch.object(a, 'doIt', return_value=True, autospec=True):
+            assert a.doIt() == True
+
+.. code-block:: console
+
+    ================================== FAILURES ===================================
+    ____________________________ test_context_manager _____________________________
+    in test_context_manager
+        with mocker.patch.object(a, 'doIt', return_value=True, autospec=True):
+    E   AttributeError: __exit__
+
+
 You can also access ``Mock`` and ``MagicMock`` directly using from ``mocker``
 fixture: