Standardize behaviour of removetree("/") and add test case to FSTestCase

Author: althonos

fs/base.py

@@ -273,7 +273,7 @@ def removedir(self, path):
         Raises:
             fs.errors.DirectoryNotEmpty: If the directory is not empty (
                 see `~fs.base.FS.removetree` for a way to remove the
-                directory contents.).
+                directory contents).
             fs.errors.DirectoryExpected: If the path does not refer to
                 a directory.
             fs.errors.ResourceNotFound: If no resource exists at the
@@ -1215,14 +1215,38 @@ def opendir(
 
     def removetree(self, dir_path):
         # type: (Text) -> None
-        """Recursively remove the contents of a directory.
+        """Recursively remove a directory and all its contents.
 
-        This method is similar to `~fs.base.removedir`, but will
+        This method is similar to `~fs.base.FS.removedir`, but will
         remove the contents of the directory if it is not empty.
 
         Arguments:
             dir_path (str): Path to a directory on the filesystem.
 
+        Caution:
+            A filesystem should never delete its root folder, so
+            ``FS.removetree("/")`` has different semantics: the
+            contents of the root folder will be deleted, but the
+            root will be untouched::
+
+                >>> home_fs = fs.open_fs("~")
+                >>> home_fs.removetree("/")
+                >>> home_fs.exists("/")
+                True
+                >>> home_fs.isempty("/")
+                True
+
+            Combined with `~fs.base.FS.opendir`, this can be used
+            to clear a directory without removing the directory
+            itself::
+
+                >>> home_fs = fs.open_fs("~")
+                >>> home_fs.opendir("/Videos").removetree("/")
+                >>> home_fs.exists("/Videos")
+                True
+                >>> home_fs.isempty("/Videos")
+                True
+
         """
         _dir_path = abspath(normpath(dir_path))
         with self._lock:

fs/test.py

@@ -292,6 +292,15 @@ def assert_not_exists(self, path):
         """
         self.assertFalse(self.fs.exists(path))
 
+    def assert_isempty(self, path):
+        """Assert a path is an empty directory.
+
+        Arguments:
+            path (str): A path on the filesystem.
+
+        """
+        self.assertTrue(self.fs.isempty(path))
+
     def assert_isfile(self, path):
         """Assert a path is a file.
 
@@ -1101,6 +1110,7 @@ def test_removedir(self):
             self.fs.removedir("foo/bar")
 
     def test_removetree(self):
+        self.fs.makedirs("spam")
         self.fs.makedirs("foo/bar/baz")
         self.fs.makedirs("foo/egg")
         self.fs.makedirs("foo/a/b/c/d/e")
@@ -1116,6 +1126,7 @@ def test_removetree(self):
 
         self.fs.removetree("foo")
         self.assert_not_exists("foo")
+        self.assert_exists("spam")
 
         # Errors on files
         self.fs.create("bar")
@@ -1126,6 +1137,34 @@ def test_removetree(self):
         with self.assertRaises(errors.ResourceNotFound):
             self.fs.removetree("foofoo")
 
+    def test_removetree_root(self):
+        self.fs.makedirs("foo/bar/baz")
+        self.fs.makedirs("foo/egg")
+        self.fs.makedirs("foo/a/b/c/d/e")
+        self.fs.create("foo/egg.txt")
+        self.fs.create("foo/bar/egg.bin")
+        self.fs.create("foo/a/b/c/1.txt")
+        self.fs.create("foo/a/b/c/2.txt")
+        self.fs.create("foo/a/b/c/3.txt")
+
+        self.assert_exists("foo/egg.txt")
+        self.assert_exists("foo/bar/egg.bin")
+
+        # removetree("/") removes the contents,
+        # but not the root folder itself
+        self.fs.removetree("/")
+        self.assert_exists("/")
+        self.assert_isempty("/")
+
+        # we check we can create a file after
+        # to catch potential issues with the
+        # root folder being deleted on faulty
+        # implementations
+        self.fs.create("egg")
+        self.fs.makedir("yolk")
+        self.assert_exists("egg")
+        self.assert_exists("yolk")
+
     def test_setinfo(self):
         self.fs.create("birthday.txt")
         now = math.floor(time.time())