[WIP] chore: add folder key helper

src/uipath/_services/_folder_helpers.py

@@ -0,0 +1,79 @@
+from typing import Optional
+
+from .folder_service import FolderService
+
+
+def resolve_folder_key(
+    folder_key: Optional[str],
+    folder_path: Optional[str],
+    folders_service: FolderService,
+    context_folder_key: Optional[str] = None,
+    context_folder_path: Optional[str] = None,
+) -> str:
+    """Resolve folder key from provided parameters or instance context.
+
+    Args:
+        folder_key: Optional folder key to use directly
+        folder_path: Optional folder path to resolve to a key
+        folders_service: FolderService instance to resolve folder paths
+        context_folder_key: Optional instance-level folder key fallback
+        context_folder_path: Optional instance-level folder path fallback
+
+    Returns:
+        The resolved folder key
+
+    Raises:
+        ValueError: If folder key cannot be resolved
+    """
+    if folder_key is not None:
+        return folder_key
+
+    if folder_path is not None:
+        return folders_service.retrieve_folder_key(folder_path=folder_path)
+
+    if context_folder_key is not None:
+        return context_folder_key
+
+    if context_folder_path is not None:
+        return folders_service.retrieve_folder_key(folder_path=context_folder_path)
+
+    raise ValueError("Failed to resolve folder key")
+
+
+async def resolve_folder_key_async(
+    folder_key: Optional[str],
+    folder_path: Optional[str],
+    folders_service: FolderService,
+    context_folder_key: Optional[str] = None,
+    context_folder_path: Optional[str] = None,
+) -> str:
+    """Asynchronously resolve folder key from provided parameters or instance context.
+
+    Args:
+        folder_key: Optional folder key to use directly
+        folder_path: Optional folder path to resolve to a key
+        folders_service: FolderService instance to resolve folder paths
+        context_folder_key: Optional instance-level folder key fallback
+        context_folder_path: Optional instance-level folder path fallback
+
+    Returns:
+        The resolved folder key
+
+    Raises:
+        ValueError: If folder key cannot be resolved
+    """
+    if folder_key is not None:
+        return folder_key
+
+    if folder_path is not None:
+        return await folders_service.retrieve_folder_key_async(folder_path=folder_path)
+
+    if context_folder_key is not None:
+        return context_folder_key
+
+    if context_folder_path is not None:
+        return await folders_service.retrieve_folder_key_async(
+            folder_path=context_folder_path
+        )
+
+    raise ValueError("Failed to resolve folder key")

src/uipath/_services/connections_service.py

@@ -7,17 +7,19 @@
 
 from .._config import Config
 from .._execution_context import ExecutionContext
+from .._folder_context import FolderContext
 from .._utils import Endpoint, RequestSpec, header_folder, resource_override
 from ..models import Connection, ConnectionMetadata, ConnectionToken, EventArguments
 from ..models.connections import ActivityMetadata, ConnectionTokenType
 from ..tracing import traced
 from ._base_service import BaseService
+from ._folder_helpers import resolve_folder_key, resolve_folder_key_async
 from .folder_service import FolderService
 
 logger: logging.Logger = logging.getLogger("uipath")
 
 
-class ConnectionsService(BaseService):
+class ConnectionsService(FolderContext, BaseService):
     """Service for managing UiPath external service connections.
 
     This service provides methods to retrieve direct connection information retrieval
@@ -177,7 +179,13 @@ def list(
         """
         spec = self._list_spec(
             name=name,
-            folder_key=self._folders_service.retrieve_folder_key(folder_path),
+            folder_key=resolve_folder_key(
+                folder_key,
+                folder_path,
+                self._folders_service,
+                self._folder_key,
+                self._folder_path,
+            ),
             connector_key=connector_key,
             skip=skip,
             top=top,
@@ -231,8 +239,12 @@ async def list_async(
         """
         spec = self._list_spec(
             name=name,
-            folder_key=await self._folders_service.retrieve_folder_key_async(
-                folder_path
+            folder_key=await resolve_folder_key_async(
+                folder_key,
+                folder_path,
+                self._folders_service,
+                self._folder_key,
+                self._folder_path,
             ),
             connector_key=connector_key,
             skip=skip,

src/uipath/_services/context_grounding_service.py

@@ -7,7 +7,12 @@
 from .._config import Config
 from .._execution_context import ExecutionContext
 from .._folder_context import FolderContext
-from .._utils import Endpoint, RequestSpec, header_folder, resource_override
+from .._utils import (
+    Endpoint,
+    RequestSpec,
+    header_folder,
+    resource_override,
+)
 from .._utils.constants import (
     LLMV4_REQUEST,
     ORCHESTRATOR_STORAGE_BUCKET_DATA_SOURCE,
@@ -33,6 +38,7 @@
 from ..models.exceptions import UnsupportedDataSourceException
 from ..tracing import traced
 from ._base_service import BaseService
+from ._folder_helpers import resolve_folder_key
 from .buckets_service import BucketsService
 from .folder_service import FolderService
 
@@ -672,7 +678,13 @@ def _ingest_spec(
         folder_key: Optional[str] = None,
         folder_path: Optional[str] = None,
     ) -> RequestSpec:
-        folder_key = self._resolve_folder_key(folder_key, folder_path)
+        folder_key = resolve_folder_key(
+            folder_key,
+            folder_path,
+            self._folders_service,
+            self._folder_key,
+            self._folder_path,
+        )
 
         return RequestSpec(
             method="POST",
@@ -688,7 +700,13 @@ def _retrieve_spec(
         folder_key: Optional[str] = None,
         folder_path: Optional[str] = None,
     ) -> RequestSpec:
-        folder_key = self._resolve_folder_key(folder_key, folder_path)
+        folder_key = resolve_folder_key(
+            folder_key,
+            folder_path,
+            self._folders_service,
+            self._folder_key,
+            self._folder_path,
+        )
 
         return RequestSpec(
             method="GET",
@@ -726,7 +744,13 @@ def _create_spec(
         Returns:
             RequestSpec for the create index request
         """
-        folder_key = self._resolve_folder_key(folder_key, folder_path)
+        folder_key = resolve_folder_key(
+            folder_key,
+            folder_path,
+            self._folders_service,
+            self._folder_key,
+            self._folder_path,
+        )
 
         data_source_dict = self._build_data_source(source)
 
@@ -828,7 +852,13 @@ def _retrieve_by_id_spec(
         folder_key: Optional[str] = None,
         folder_path: Optional[str] = None,
     ) -> RequestSpec:
-        folder_key = self._resolve_folder_key(folder_key, folder_path)
+        folder_key = resolve_folder_key(
+            folder_key,
+            folder_path,
+            self._folders_service,
+            self._folder_key,
+            self._folder_path,
+        )
 
         return RequestSpec(
             method="GET",
@@ -844,7 +874,13 @@ def _delete_by_id_spec(
         folder_key: Optional[str] = None,
         folder_path: Optional[str] = None,
     ) -> RequestSpec:
-        folder_key = self._resolve_folder_key(folder_key, folder_path)
+        folder_key = resolve_folder_key(
+            folder_key,
+            folder_path,
+            self._folders_service,
+            self._folder_key,
+            self._folder_path,
+        )
 
         return RequestSpec(
             method="DELETE",
@@ -862,7 +898,13 @@ def _search_spec(
         folder_key: Optional[str] = None,
         folder_path: Optional[str] = None,
     ) -> RequestSpec:
-        folder_key = self._resolve_folder_key(folder_key, folder_path)
+        folder_key = resolve_folder_key(
+            folder_key,
+            folder_path,
+            self._folders_service,
+            self._folder_key,
+            self._folder_path,
+        )
 
         return RequestSpec(
             method="POST",
@@ -876,22 +918,6 @@ def _search_spec(
             },
         )
 
-    def _resolve_folder_key(self, folder_key, folder_path):
-        if folder_key is None and folder_path is not None:
-            folder_key = self._folders_service.retrieve_key(folder_path=folder_path)
-
-        if folder_key is None and folder_path is None:
-            folder_key = self._folder_key or (
-                self._folders_service.retrieve_key(folder_path=self._folder_path)
-                if self._folder_path
-                else None
-            )
-
-        if folder_key is None:
-            raise ValueError("ContextGrounding: Failed to resolve folder key")
-
-        return folder_key
-
     def _extract_bucket_info(self, index: ContextGroundingIndex) -> Tuple[str, str]:
         """Extract bucket information from the index, validating it's a storage bucket data source.
 

src/uipath/_services/folder_service.py

@@ -21,7 +21,7 @@ class FolderService(BaseService):
     def __init__(self, config: Config, execution_context: ExecutionContext) -> None:
         super().__init__(config=config, execution_context=execution_context)
 
-    def retrieve_folder_key(self, folder_path: str | None) -> str | None:
+    def retrieve_folder_key(self, folder_path: str | None) -> str:
         """Resolve a folder path to its corresponding folder key.
 
         Args:
@@ -41,7 +41,7 @@ def retrieve_folder_key(self, folder_path: str | None) -> str | None:
             raise ValueError(f"Folder with path '{folder_path}' not found")
         return resolved_folder_key
 
-    async def retrieve_folder_key_async(self, folder_path: str | None) -> str | None:
+    async def retrieve_folder_key_async(self, folder_path: str | None) -> str:
         """Asynchronously resolve a folder path to its corresponding folder key.
 
         Args:

src/uipath/_services/resource_catalog_service.py

@@ -5,6 +5,10 @@
 from uipath._folder_context import FolderContext
 from uipath._services import FolderService
 from uipath._services._base_service import BaseService
+from uipath._services._folder_helpers import (
+    resolve_folder_key,
+    resolve_folder_key_async,
+)
 from uipath._utils import Endpoint, RequestSpec, header_folder
 from uipath.models.resource_catalog import Resource, ResourceType
 from uipath.tracing import traced
@@ -217,7 +221,13 @@ def list(
         if take <= 0:
             raise ValueError(f"page_size must be greater than 0. Got {page_size}")
 
-        resolved_folder_key = self.folder_service.retrieve_folder_key(folder_path)
+        resolved_folder_key = resolve_folder_key(
+            folder_key,
+            folder_path,
+            self.folder_service,
+            self._folder_key,
+            self._folder_path,
+        )
 
         while True:
             spec = self._list_spec(
@@ -299,8 +309,12 @@ async def list_async(
         if take <= 0:
             raise ValueError(f"page_size must be greater than 0. Got {page_size}")
 
-        resolved_folder_key = await self.folder_service.retrieve_folder_key_async(
-            folder_path
+        resolved_folder_key = await resolve_folder_key_async(
+            folder_key,
+            folder_path,
+            self.folder_service,
+            self._folder_key,
+            self._folder_path,
         )
         while True:
             spec = self._list_spec(
@@ -385,7 +399,13 @@ def list_by_type(
         if take <= 0:
             raise ValueError(f"page_size must be greater than 0. Got {page_size}")
 
-        resolved_folder_key = self.folder_service.retrieve_folder_key(folder_path)
+        resolved_folder_key = resolve_folder_key(
+            folder_key,
+            folder_path,
+            self.folder_service,
+            self._folder_key,
+            self._folder_path,
+        )
 
         while True:
             spec = self._list_by_type_spec(
@@ -471,8 +491,12 @@ async def list_by_type_async(
         if take <= 0:
             raise ValueError(f"page_size must be greater than 0. Got {page_size}")
 
-        resolved_folder_key = await self.folder_service.retrieve_folder_key_async(
-            folder_path
+        resolved_folder_key = await resolve_folder_key_async(
+            folder_key,
+            folder_path,
+            self.folder_service,
+            self._folder_key,
+            self._folder_path,
         )
 
         while True: