improved code docs

Author: nicoddemus

pytest_mock.py

@@ -1,49 +1,67 @@
 import pytest
+import mock as mock_module
 
 
 class MockFixture(object):
+    """
+    Fixture that provides the same interface to functions in the mock module,
+    ensuring that they are uninstalled at the end of each test.
+    """
+
     def __init__(self):
-        self._patches = []
+        self._patches = []  # list of mock._patch objects
         self.patch = self._Patcher(self._patches)
 
     def stopall(self):
+        """
+        Stop all patchers started by this fixture. Can be safely called multiple
+        times.
+        """
         for p in self._patches:
             p.stop()
         self._patches[:] = []
 
     class _Patcher(object):
+        """
+        Object to provide the same interface as mock.patch, mock.patch.object,
+        etc. We need this indirection to keep the same API of the mock package.
+        """
+
         def __init__(self, patches):
             self._patches = patches
 
-        def object(self, *args, **kwargs):
-            import mock
-
-            p = mock.patch.object(*args, **kwargs)
+        def _start_patch(self, mock_func, *args, **kwargs):
+            """Patches something by calling the given function from the mock
+            module, registering the patch to stop it later and returns the
+            mock object resulting from the mock call.
+            """
+            p = mock_func(*args, **kwargs)
             mocked = p.start()
             self._patches.append(p)
             return mocked
 
+        def object(self, *args, **kwargs):
+            """API to mock.patch.object"""
+            return self._start_patch(mock_module.patch.object, *args, **kwargs)
 
-        def multiple(self, *args, **kwargs):
-            import mock
 
-            p = mock.patch.multiple(*args, **kwargs)
-            mocked = p.start()
-            self._patches.append(p)
-            return mocked
+        def multiple(self, *args, **kwargs):
+            """API to mock.patch.multiple"""
+            return self._start_patch(mock_module.patch.multiple, *args,
+                                     **kwargs)
 
 
         def __call__(self, *args, **kwargs):
-            import mock
-
-            p = mock.patch(*args, **kwargs)
-            mocked = p.start()
-            self._patches.append(p)
-            return mocked
+            """API to mock.patch"""
+            return self._start_patch(mock_module.patch, *args, **kwargs)
 
 
 @pytest.yield_fixture
 def mock():
+    """
+    return an object that has the same interface to the `mock` module, but
+    takes care of automatically undoing all patches after each test method.
+    """
     result = MockFixture()
     yield result
     result.stopall()

test_pytest_mock.py

@@ -2,7 +2,13 @@
 
 import pytest
 
+
 class UnixFS(object):
+    """
+    Wrapper to os functions to simulate a Unix file system, used for testing
+    the mock fixture.
+    """
+
     @classmethod
     def rm(cls, filename):
         os.remove(filename)
@@ -14,6 +20,11 @@ def ls(cls, path):
 
 @pytest.fixture
 def check_unix_fs_mocked(tmpdir, mock):
+    """
+    performs a standard test in a UnixFS, assuming that both `os.remove` and
+    `os.listdir` have been mocked previously.
+    """
+
     def check(mocked_rm, mocked_ls):
         assert mocked_rm is os.remove
         assert mocked_ls is os.listdir
@@ -56,6 +67,11 @@ def mock_using_patch_multiple(mock):
 @pytest.mark.parametrize('mock_fs', [mock_using_patch_object, mock_using_patch,
                                      mock_using_patch_multiple],
 )
-def test_fixture(mock_fs, mock, check_unix_fs_mocked):
+def test_mock_fixture(mock_fs, mock, check_unix_fs_mocked):
+    """
+    Installs mocks into `os` functions and performs a standard testing of
+    mock functionality. We parametrize different mock methods to ensure
+    all (intended, at least) mock API is covered.
+    """
     mocked_rm, mocked_ls = mock_fs(mock)
     check_unix_fs_mocked(mocked_rm, mocked_ls)