Add function generating an unused directory given a path

The create_unused_dir function distinguishes between the parent
directory and the name of the target subdirectory in 2 separate
arguments. This interface requires additional parameter management when
combined with newer path management interfaces such as pathlib. Add a
function create_unused_path accepting the target path as a single
argument.

Author: gkaf89

easybuild/tools/filetools.py

@@ -2980,3 +2980,43 @@ def create_unused_dir(parent_folder, name):
     set_gid_sticky_bits(path, recursive=True)
 
     return path
+
+
+def get_first_nonexisting_parent(path):
+    path = os.path.abspath(path)
+
+    first_nonexisting_parent = None
+    while not os.path.exists(path):
+        first_nonexisting_parent = path
+        path = os.path.dirname(path)
+
+    return first_nonexisting_parent
+
+
+def create_unused_path(path):
+    """
+    Create a new directory with a given path, including the parent directories
+    When a directory in the same path already exists, then '_0' is appended which is retried for increasing numbers
+    until an unused name was found.
+    """
+    path = os.path.abspath(path)
+
+    for number in range(-1, 10000):  # Start with no suffix and limit the number of attempts
+        if number < 0:
+            final_path = path
+            first_nonexisting_parent = get_first_nonexisting_parent(path)
+        else:
+            final_path = path + '_' + str(number)
+            first_nonexisting_parent = final_path
+        try:
+            os.makedirs(final_path)
+            break
+        except OSError as err:
+            # Distinguish between error due to existing folder and anything else
+            if not os.path.exists(final_path):
+                raise EasyBuildError("Failed to create directory %s: %s", final_path, err)
+
+    # set group ID and sticky bits, if desired
+    set_gid_sticky_bits(first_nonexisting_parent, recursive=True)
+
+    return final_path

test/framework/filetools.py

@@ -3522,6 +3522,31 @@ def test_compat_makedirs(self):
         py2vs3.makedirs(name, exist_ok=True)  # No error
         self.assertExists(name)
 
+    def test_get_first_nonexisting_parent(self):
+        """Test get_first_nonexisting_parent function."""
+        test_root = os.path.join(self.test_prefix, 'a')
+
+        base_path = os.path.join(self.test_prefix, 'a')
+        target_path = os.path.join(self.test_prefix, 'a', 'b', 'c')
+        os.makedirs(base_path)
+        first_nonexisting_parent = ft.get_first_nonexisting_parent(target_path)
+        self.assertEqual(first_nonexisting_parent, os.path.join(self.test_prefix, 'a', 'b'))
+        shutil.rmtree(test_root)
+
+        base_path = os.path.join(self.test_prefix, 'a', 'b')
+        target_path = os.path.join(self.test_prefix, 'a', 'b', 'c')
+        os.makedirs(base_path)
+        first_nonexisting_parent = ft.get_first_nonexisting_parent(target_path)
+        self.assertEqual(first_nonexisting_parent, os.path.join(self.test_prefix, 'a', 'b', 'c'))
+        shutil.rmtree(test_root)
+
+        base_path = os.path.join(self.test_prefix, 'a', 'b', 'c')
+        target_path = os.path.join(self.test_prefix, 'a', 'b', 'c')
+        os.makedirs(base_path)
+        first_nonexisting_parent = ft.get_first_nonexisting_parent(target_path)
+        self.assertEqual(first_nonexisting_parent, None)
+        shutil.rmtree(test_root)
+
     def test_create_unused_dir(self):
         """Test create_unused_dir function."""
         path = ft.create_unused_dir(self.test_prefix, 'folder')
@@ -3560,6 +3585,55 @@ def test_create_unused_dir(self):
         self.assertEqual(path, os.path.join(self.test_prefix, 'file_0'))
         self.assertExists(path)
 
+    def test_create_unused_path(self):
+        """Test create_unused_path function."""
+        requested_path = os.path.join(self.test_prefix, 'folder')
+        path = ft.create_unused_dir(requested_path)
+        self.assertEqual(path, requested_path)
+        self.assertExists(path)
+
+        # Repeat with existing folder(s) should create new ones
+        for i in range(10):
+            requested_path = os.path.join(self.test_prefix, 'folder')
+            path = ft.create_unused_dir(requested_path)
+            self.assertEqual(path, requested_path + '_%s' % i)
+            self.assertExists(path)
+
+        # Support creation of parent directories
+        requested_path = os.path.join(self.test_prefix, 'parent_folder', 'folder')
+        path = ft.create_unused_dir(requested_path)
+        self.assertEqual(path, requested_path)
+        self.assertExists(path)
+
+        # Not influenced by similar folder
+        requested_path = os.path.join(self.test_prefix, 'folder2')
+        path = ft.create_unused_dir(requested_path)
+        self.assertEqual(path, requested_path)
+        self.assertExists(path)
+        for i in range(10):
+            path = ft.create_unused_dir(requested_path)
+            self.assertEqual(path, requested_path + '_%s' % i)
+            self.assertExists(path)
+
+        # Fail cleanly if passed a readonly folder
+        readonly_dir = os.path.join(self.test_prefix, 'ro_folder')
+        ft.mkdir(readonly_dir)
+        old_perms = os.lstat(readonly_dir)[stat.ST_MODE]
+        ft.adjust_permissions(readonly_dir, stat.S_IREAD | stat.S_IEXEC, relative=False)
+        requested_path = os.path.join(readonly_dir, 'new_folder')
+        try:
+            self.assertErrorRegex(EasyBuildError, 'Failed to create directory',
+                                  ft.create_unused_dir, requested_path)
+        finally:
+            ft.adjust_permissions(readonly_dir, old_perms, relative=False)
+
+        # Ignore files same as folders. So first just create a file with no contents
+        requested_path = os.path.join(self.test_prefix, 'file')
+        ft.write_file(requested_path, '')
+        path = ft.create_unused_dir(requested_path)
+        self.assertEqual(path, requested_path + '_0')
+        self.assertExists(path)
+
 
 def suite():
     """ returns all the testcases in this module """