added folders.create_path

* Add recursive folder creation and example

* Corrections based on deepsource

* New corrections based on deepsource second run

* Correct typo in upload_file.py

* Update Folders documentation missing parameters

* Change method name to create_path
Update code to be recursive

* Updates based on comments

* Remove HTTPError import from folders.py

* Corrections based on comments

* Update folders service based on latest comments

---------

Co-authored-by: Xavier BIZOUX <xavier.bizouxësas.com>

Author: xavierBizoux

.gitignore

@@ -67,3 +67,6 @@ doc/build
 doc/source/generated
 doc/_build
 doc/.doctrees
+
+## VS CODE settings
+.vscode/settings.json

examples/upload_file.py

@@ -0,0 +1,61 @@
+import getpass
+import os
+
+from sasctl import Session
+from sasctl.services import files, folders
+
+server_name = "myServer.sas.com"
+user = "sasdemo"
+password = getpass.getpass()
+os_path = "/test/Downloads/pdfs"
+sas_path = "/Public/PDFs"
+
+
+def build_storage_lists(source_path, target_path):
+    """
+    Function to create a list of files and directories
+    from a source folder at OS level
+    and mapped to target folder in SAS Content Server.
+
+    Parameters
+    ----------
+    source_path : str
+        Path to the folder which should be imported.
+    target_path : str
+        Path to the folder which will contain the files and folders in SAS Content Server.
+
+    Returns
+    -------
+    f_list
+        A list of file information which can be used to map local and SAS files.
+    d_list
+        A list of directory information which can be user to map local and SAS folder structure.
+    """
+    files_list = []
+    folders_list = []
+
+    for root, _, src_files in os.walk(source_path):
+        for src_file in src_files:
+            if src_file.endswith(".pdf"):
+                if root not in folders_list:
+                    folder_info = root.replace(source_path, target_path)
+                    if folder_info not in folders_list:
+                        folders_list.append(folder_info)
+                file_info = {}
+                file_info["source_file"] = os.path.join(root, src_file)
+                file_info["target_folder"] = root.replace(
+                    source_path, target_path)
+                files_list.append(file_info)
+    return folders_list, files_list
+
+
+with Session(server_name, user, password):
+    folders_list, files_list = build_storage_lists(os_path, sas_path)
+    for folder in folders_list:
+        folders.create_path(folder)
+    for file in files_list:
+        files.create_file(
+            file["source_file"],
+            file["target_folder"],
+            os.path.basename(file["source_file"])
+        )

src/sasctl/_services/folders.py

@@ -49,7 +49,8 @@ def create_folder(cls, name, parent=None, description=None):
 
             parent_uri = cls.get_link(parent_obj, "self")
             if parent_uri is None:
-                raise ValueError("`parent` folder '%s' does not exist." % parent)
+                raise ValueError(
+                    f"`parent` folder {parent} does not exist.")
             parent_uri = parent_uri["uri"]
         else:
             parent_uri = None
@@ -135,3 +136,35 @@ def get_folder(cls, folder, refresh=False):
             return cls.get(f"/folders/{folder}")
 
         return cls._get_folder(folder, refresh=refresh)
+
+    @classmethod
+    def create_path(cls, folder, description=None):
+        """Create a new folder recursively.
+
+        Parameters
+        ----------
+        folder : str
+            The folder to be created including the path.
+        description: str, optional
+             A description of the folder
+
+        Returns
+        -------
+        RestObj
+            Details of newly-created folder
+
+        """
+        folder = str(folder)
+        # Path must include a leading "/"
+        if not folder.startswith("/"):
+            folder = f"/{folder}"
+        path = folder.split("/")
+        for level in range(2, len(path)+1):
+
+            current_path = path[0:level]
+            name = current_path[-1]
+            parent = "/".join(current_path[0:-1]) or None
+            new_folder = cls.get_folder("/".join(current_path))
+            if not new_folder:
+                new_folder = cls.create_folder(name, parent=parent, description=description)
+        return new_folder