allow folder lookup by path or delegate string.

Author: jlwalke2

CHANGELOG.md

@@ -1,7 +1,7 @@
 Unreleased
 ----------
 **Improvements**
- - `folders.get_folder()` can now handle folder names that include a leading or trailing "/" character.
+ - `folders.get_folder()` can now handle folder paths and delegates (e.g. @public).
 
 v1.8.1 (2023-01-19)
 ----------

src/sasctl/_services/folders.py

@@ -69,7 +69,12 @@ def get_folder(cls, folder, refresh=False):
         Parameters
         ----------
         folder : str or dict
-            Name, ID, or dictionary representation of the folder.
+            May be one of:
+             - folder name
+             - folder ID
+             - folder path
+             - folder delegate string
+             - dictionary representation of the folder
         refresh : bool, optional
             Obtain an updated copy of the folder.
 
@@ -84,10 +89,48 @@ def get_folder(cls, folder, refresh=False):
         returned unless `refresh` is set.  This prevents unnecessary REST
         calls when data is already available on the client.
 
+        Examples
+        --------
+        The following four examples are all functionally equivalent.
+
+        >>> get_folder("Public")
+        {"name": "Public", "id": "4a737209-5662"}
+
+        >>> get_folder("/Public")
+        {"name": "Public", "id": "4a737209-5662"}
+
+        >>> get_folder("@public")
+        {"name": "Public", "id": "4a737209-5662"}
+
+        >>> get_folder("@public")
+        {"name": "Public", "id": "4a737209-5662"}
+
+        >>> get_folder("4a737209-5662")
+        {"name": "Public", "id": "4a737209-5662"}
+
+        The full folder path can also be specified.
+
+        >>> get_folder("/Public/Demo")
+        {"name": "Demo", "id": "148081bf-1c86"}
+
+        Special folders can be identified using a delegate string.  Currently supported
+        are: @myFolder, @appDataFolder, @myHistory, @myFavorites, and @public.
+
+        >>> get_folder("@myFolder")
+        {"name": "My Folder", "id": "71687cd2-db4b"}
+
         """
-        # If users pass in a folder name like "/Public" instead of "Public"
-        # then just cleanup the folder name so that it matches what's returned by Viya.
-        if isinstance(folder, str):
-            folder = folder.strip("/")
+        # If a folder path is specified, lookup folder using the full path instead of the name.
+        if isinstance(folder, str) and "/" in folder:
+            # Path must include a leading "/"
+            if not folder.startswith("/"):
+                folder = f"/{folder}"
+
+            return cls.get("/folders/@item", params={"path": folder})
+
+        # Its possible to lookup special folders by using a handle (called a delegate string in docs)
+        # Current values (2022.09) are @myFolder, @appDataFolder, @myHistory, @myFavorites, @public.
+        if isinstance(folder, str) and folder.startswith("@"):
+            return cls.get(f"/folders/{folder}")
 
         return cls._get_folder(folder, refresh=refresh)

tests/unit/test_folders.py

@@ -78,12 +78,12 @@ def test_create_folder_with_parent():
 
 
 @mock.patch("sasctl.core.Session.request")
-def test_get_folder_with_path(request):
-    """Verify that simple folder paths instead of names are handled."""
+def test_get_folder_by_name(request):
+    """Verify that looking up a folder by name works."""
     request.return_value.status_code = 200
     request.return_value.json.return_value = {"name": "Spam"}
 
-    folder = folders.get_folder("/Spam")
+    folder = folders.get_folder("Spam")
     assert folder is not None
     assert folder.name == "Spam"
 
@@ -95,4 +95,63 @@ def test_get_folder_with_path(request):
 
     # / should have been stripped out of folder name
     assert '"Spam"' in search_filter
-    assert '"/Spam"' not in search_filter
+
+
+@mock.patch("sasctl.core.Session.request")
+def test_get_folder_by_path(request):
+    """Verify that simple folder paths instead of names are handled."""
+    request.return_value.status_code = 200
+    request.return_value.json.return_value = {"name": "Spam"}
+
+    folder = folders.get_folder("/Spam")
+    assert folder is not None
+    assert folder.name == "Spam"
+
+    # Should not have called list_folders to search.  Should have been a direct call to lookup by path.
+    assert request.call_count == 1
+
+    url, params = request.call_args_list[0]
+    query_string = params["params"]
+
+    assert url[1] == "/folders/folders/@item"
+    assert query_string["path"] == "/Spam"
+
+
+@mock.patch("sasctl.core.Session.request")
+def test_get_folder_by_path(request):
+    """Verify that complex folder paths are handled."""
+    request.return_value.status_code = 200
+    request.return_value.json.return_value = {"name": "Spam"}
+
+    folder = folders.get_folder("Spam/Eggs/Spam")
+    assert folder is not None
+    assert folder.name == "Spam"
+
+    # Should not have called list_folders to search.  Should have been a direct call to lookup by path.
+    assert request.call_count == 1
+
+    url, params = request.call_args_list[0]
+    query_string = params["params"]
+
+    assert url[1] == "/folders/folders/@item"
+
+    # Leading "/" should have been added
+    assert query_string["path"] == "/Spam/Eggs/Spam"
+
+
+@mock.patch("sasctl.core.Session.request")
+def test_get_folder_by_delegate(request):
+    """Verify that folder can be found by using delegate strings (e.g. @public)."""
+    request.return_value.status_code = 200
+    request.return_value.json.return_value = {"name": "Spam"}
+
+    folder = folders.get_folder("@spam")
+    assert folder is not None
+    assert folder.name == "Spam"
+
+    # Should not have called list_folders to search.  Should have been a direct call to GET by id.
+    assert request.call_count == 1
+
+    url, params = request.call_args_list[0]
+    assert url[1] == "/folders/folders/@spam"
+    assert params == {}