Bug 859422 - Document why mozfile.remove works better than shutil.rmtree. r=wlach

testing/mozbase/mozfile/mozfile/mozfile.py

@@ -133,10 +133,19 @@ def rmtree(dir):
 
 
 def remove(path):
-    """Removes the specified file, link, or directory tree
+    """Removes the specified file, link, or directory tree.
 
     This is a replacement for shutil.rmtree that works better under
-    windows.
+    windows. It does the following things:
+
+     - check path access for the current user before trying to remove
+     - retry operations on some known errors due to various things keeping
+       a handle on file paths - like explorer, virus scanners, etc. The
+       known errors are errno.EACCES and errno.ENOTEMPTY, and it will
+       retry up to 5 five times with a delay of 0.5 seconds between each
+       attempt.
+
+    Note that no error will be raised if the given path does not exists.
 
     :param path: path to be removed
     """

testing/mozbase/mozfile/tests/test_remove.py

@@ -6,6 +6,7 @@ import shutil
 import threading
 import time
 import unittest
+import errno
 
 import mozfile
 import mozinfo
@@ -181,3 +182,15 @@ class MozfileRemoveTestCase(unittest.TestCase):
         # original linked file
         mozfile.remove(symlink_path)
         self.assertFalse(os.path.exists(symlink_path))
+
+    def test_remove_path_that_does_not_exists(self):
+        not_existing_path = os.path.join(self.tempdir, 'I_do_not_not_exists')
+        try:
+            mozfile.remove(not_existing_path)
+        except OSError, exc:
+            if exc.errno == errno.ENOENT:
+                self.fail("removing non existing path must not raise error")
+            raise
+
+if __name__ == '__main__':
+    unittest.main()