uipath 2.1.122__py3-none-any.whl → 2.1.123__py3-none-any.whl

uipath/_cli/_runtime/_contracts.py

@@ -96,6 +96,7 @@ class UiPathErrorCategory(str, Enum):
 class UiPathErrorCode(str, Enum):
     """Standard error codes for UiPath runtime errors."""
 
+    AUTHENTICATION_REQUIRED = "AUTHENTICATION_REQUIRED"
     # Entrypoint related errors
     ENTRYPOINT_MISSING = "ENTRYPOINT_MISSING"
     ENTRYPOINT_NOT_FOUND = "ENTRYPOINT_NOT_FOUND"

uipath/_services/buckets_service.py

@@ -1,5 +1,8 @@
+import asyncio
 import mimetypes
-from typing import Dict, Optional, Union
+import uuid
+from pathlib import Path
+from typing import Any, AsyncIterator, Dict, Iterator, Optional, Union
 
 import httpx
 
@@ -8,7 +11,7 @@ from .._execution_context import ExecutionContext
 from .._folder_context import FolderContext
 from .._utils import Endpoint, RequestSpec, header_folder, infer_bindings
 from .._utils._ssl_context import get_httpx_client_kwargs
-from ..models import Bucket
+from ..models import Bucket, BucketFile
 from ..tracing._traced import traced
 from ._base_service import BaseService
 
@@ -20,11 +23,241 @@ class BucketsService(FolderContext, BaseService):
     used by automation processes.
     """
 
+    _GET_FILES_PAGE_SIZE = 500  # OData GetFiles pagination page size
+
     def __init__(self, config: Config, execution_context: ExecutionContext) -> None:
         super().__init__(config=config, execution_context=execution_context)
         self.custom_client = httpx.Client(**get_httpx_client_kwargs())
         self.custom_client_async = httpx.AsyncClient(**get_httpx_client_kwargs())
 
+    @traced(name="buckets_list", run_type="uipath")
+    def list(
+        self,
+        *,
+        folder_path: Optional[str] = None,
+        folder_key: Optional[str] = None,
+        name: Optional[str] = None,
+    ) -> Iterator[Bucket]:
+        """List buckets with auto-pagination.
+
+        Args:
+            folder_path: Folder path to filter buckets
+            folder_key: Folder key (mutually exclusive with folder_path)
+            name: Filter by bucket name (contains match)
+
+        Yields:
+            Bucket: Bucket resource instances
+
+        Examples:
+            >>> # List all buckets
+            >>> for bucket in sdk.buckets.list():
+            ...     print(bucket.name)
+            >>>
+            >>> # Filter by folder
+            >>> for bucket in sdk.buckets.list(folder_path="Production"):
+            ...     print(bucket.name)
+            >>>
+            >>> # Filter by name
+            >>> for bucket in sdk.buckets.list(name="invoice"):
+            ...     print(bucket.name)
+        """
+        skip = 0
+        top = 100
+
+        while True:
+            spec = self._list_spec(
+                folder_path=folder_path,
+                folder_key=folder_key,
+                name=name,
+                skip=skip,
+                top=top,
+            )
+            response = self.request(
+                spec.method,
+                url=spec.endpoint,
+                params=spec.params,
+                headers=spec.headers,
+            ).json()
+
+            items = response.get("value", [])
+            if not items:
+                break
+
+            for item in items:
+                bucket = Bucket.model_validate(item)
+                yield bucket
+
+            if len(items) < top:
+                break
+
+            skip += top
+
+    @traced(name="buckets_list", run_type="uipath")
+    async def list_async(
+        self,
+        *,
+        folder_path: Optional[str] = None,
+        folder_key: Optional[str] = None,
+        name: Optional[str] = None,
+    ) -> AsyncIterator[Bucket]:
+        """Async version of list() with auto-pagination."""
+        skip = 0
+        top = 50
+
+        while True:
+            spec = self._list_spec(
+                folder_path=folder_path,
+                folder_key=folder_key,
+                name=name,
+                skip=skip,
+                top=top,
+            )
+            response = (
+                await self.request_async(
+                    spec.method,
+                    url=spec.endpoint,
+                    params=spec.params,
+                    headers=spec.headers,
+                )
+            ).json()
+
+            items = response.get("value", [])
+            if not items:
+                break
+
+            for item in items:
+                bucket = Bucket.model_validate(item)
+                yield bucket
+
+            if len(items) < top:
+                break
+
+            skip += top
+
+    @traced(name="buckets_exists", run_type="uipath")
+    def exists(
+        self,
+        name: str,
+        *,
+        folder_key: Optional[str] = None,
+        folder_path: Optional[str] = None,
+    ) -> bool:
+        """Check if bucket exists.
+
+        Args:
+            name: Bucket name
+            folder_key: Folder key
+            folder_path: Folder path
+
+        Returns:
+            bool: True if bucket exists
+
+        Examples:
+            >>> if sdk.buckets.exists("my-storage"):
+            ...     print("Bucket found")
+        """
+        try:
+            self.retrieve(name=name, folder_key=folder_key, folder_path=folder_path)
+            return True
+        except LookupError:
+            return False
+
+    @traced(name="buckets_exists", run_type="uipath")
+    async def exists_async(
+        self,
+        name: str,
+        *,
+        folder_key: Optional[str] = None,
+        folder_path: Optional[str] = None,
+    ) -> bool:
+        """Async version of exists()."""
+        try:
+            await self.retrieve_async(
+                name=name, folder_key=folder_key, folder_path=folder_path
+            )
+            return True
+        except LookupError:
+            return False
+
+    @traced(name="buckets_create", run_type="uipath")
+    def create(
+        self,
+        name: str,
+        *,
+        description: Optional[str] = None,
+        identifier: Optional[str] = None,
+        folder_path: Optional[str] = None,
+        folder_key: Optional[str] = None,
+    ) -> Bucket:
+        """Create a new bucket.
+
+        Args:
+            name: Bucket name (must be unique within folder)
+            description: Optional description
+            identifier: UUID identifier (auto-generated if not provided)
+            folder_path: Folder to create bucket in
+            folder_key: Folder key
+
+        Returns:
+            Bucket: Newly created bucket resource
+
+        Raises:
+            Exception: If bucket creation fails
+
+        Examples:
+            >>> bucket = sdk.buckets.create("my-storage")
+            >>> bucket = sdk.buckets.create(
+            ...     "data-storage",
+            ...     description="Production data"
+            ... )
+        """
+        spec = self._create_spec(
+            name=name,
+            description=description,
+            identifier=identifier or str(uuid.uuid4()),
+            folder_path=folder_path,
+            folder_key=folder_key,
+        )
+        response = self.request(
+            spec.method,
+            url=spec.endpoint,
+            json=spec.json,
+            headers=spec.headers,
+        ).json()
+
+        bucket = Bucket.model_validate(response)
+        return bucket
+
+    @traced(name="buckets_create", run_type="uipath")
+    async def create_async(
+        self,
+        name: str,
+        *,
+        description: Optional[str] = None,
+        identifier: Optional[str] = None,
+        folder_path: Optional[str] = None,
+        folder_key: Optional[str] = None,
+    ) -> Bucket:
+        """Async version of create()."""
+        spec = self._create_spec(
+            name=name,
+            description=description,
+            identifier=identifier or str(uuid.uuid4()),
+            folder_path=folder_path,
+            folder_key=folder_key,
+        )
+        response = (
+            await self.request_async(
+                spec.method,
+                url=spec.endpoint,
+                json=spec.json,
+                headers=spec.headers,
+            )
+        ).json()
+
+        bucket = Bucket.model_validate(response)
+        return bucket
+
     @traced(name="buckets_download", run_type="uipath")
     @infer_bindings(resource_type="bucket")
     def download(
@@ -74,7 +307,6 @@ class BucketsService(FolderContext, BaseService):
         }
 
         with open(destination_path, "wb") as file:
-            # the self.request adds auth bearer token
             if result["RequiresAuth"]:
                 file_content = self.request("GET", read_uri, headers=headers).content
             else:
@@ -131,17 +363,16 @@ class BucketsService(FolderContext, BaseService):
             )
         }
 
-        with open(destination_path, "wb") as file:
-            # the self.request adds auth bearer token
-            if result["RequiresAuth"]:
-                file_content = (
-                    await self.request_async("GET", read_uri, headers=headers)
-                ).content
-            else:
-                file_content = (
-                    await self.custom_client_async.get(read_uri, headers=headers)
-                ).content
-            file.write(file_content)
+        if result["RequiresAuth"]:
+            file_content = (
+                await self.request_async("GET", read_uri, headers=headers)
+            ).content
+        else:
+            file_content = (
+                await self.custom_client_async.get(read_uri, headers=headers)
+            ).content
+
+        await asyncio.to_thread(Path(destination_path).write_bytes, file_content)
 
     @traced(name="buckets_upload", run_type="uipath")
     @infer_bindings(resource_type="bucket")
@@ -182,8 +413,6 @@ class BucketsService(FolderContext, BaseService):
             name=name, key=key, folder_key=folder_key, folder_path=folder_path
         )
 
-        # if source_path, dynamically detect the mime type
-        # default to application/octet-stream
         if source_path:
             _content_type, _ = mimetypes.guess_type(source_path)
         else:
@@ -258,7 +487,7 @@ class BucketsService(FolderContext, BaseService):
             name (Optional[str]): The name of the bucket.
             blob_file_path (str): The path where the file will be stored in the bucket.
             content_type (Optional[str]): The MIME type of the file. For file inputs this is computed dynamically. Default is "application/octet-stream".
-            source_path (str): The local path of the file to upload.
+            source_path (Optional[str]): The local path of the file to upload.
             content (Optional[Union[str, bytes]]): The content to upload (string or bytes).
             folder_key (Optional[str]): The key of the folder where the bucket resides.
             folder_path (Optional[str]): The path of the folder where the bucket resides.
@@ -276,8 +505,6 @@ class BucketsService(FolderContext, BaseService):
             name=name, key=key, folder_key=folder_key, folder_path=folder_path
         )
 
-        # if source_path, dynamically detect the mime type
-        # default to application/octet-stream
         if source_path:
             _content_type, _ = mimetypes.guess_type(source_path)
         else:
@@ -326,16 +553,15 @@ class BucketsService(FolderContext, BaseService):
                 )
 
         if source_path is not None:
-            with open(source_path, "rb") as file:
-                file_content = file.read()
-                if result["RequiresAuth"]:
-                    await self.request_async(
-                        "PUT", write_uri, headers=headers, content=file_content
-                    )
-                else:
-                    await self.custom_client_async.put(
-                        write_uri, headers=headers, content=file_content
-                    )
+            file_content = await asyncio.to_thread(Path(source_path).read_bytes)
+            if result["RequiresAuth"]:
+                await self.request_async(
+                    "PUT", write_uri, headers=headers, content=file_content
+                )
+            else:
+                await self.custom_client_async.put(
+                    write_uri, headers=headers, content=file_content
+                )
 
     @traced(name="buckets_retrieve", run_type="uipath")
     @infer_bindings(resource_type="bucket")
@@ -356,34 +582,61 @@ class BucketsService(FolderContext, BaseService):
             folder_path (Optional[str]): The path of the folder where the bucket resides.
 
         Returns:
-            Response: The bucket details.
+            Bucket: The bucket resource instance.
 
         Raises:
             ValueError: If neither bucket key nor bucket name is provided.
             Exception: If the bucket with the specified name is not found.
+
+        Examples:
+            >>> bucket = sdk.buckets.retrieve(name="my-storage")
+            >>> print(bucket.name, bucket.identifier)
         """
         if not (key or name):
             raise ValueError("Must specify a bucket name or bucket key")
+
         if key:
             spec = self._retrieve_by_key_spec(
                 key, folder_key=folder_key, folder_path=folder_path
             )
+            try:
+                response = self.request(
+                    spec.method,
+                    url=spec.endpoint,
+                    params=spec.params,
+                    headers=spec.headers,
+                ).json()
+                if "value" in response:
+                    items = response.get("value", [])
+                    if not items:
+                        raise LookupError(f"Bucket with key '{key}' not found")
+                    bucket_data = items[0]
+                else:
+                    bucket_data = response
+            except (KeyError, IndexError) as e:
+                raise LookupError(f"Bucket with key '{key}' not found") from e
         else:
             spec = self._retrieve_spec(
                 name,  # type: ignore
                 folder_key=folder_key,
                 folder_path=folder_path,
             )
-        try:
-            response = self.request(
-                spec.method,
-                url=spec.endpoint,
-                params=spec.params,
-                headers=spec.headers,
-            ).json()["value"][0]
-        except (KeyError, IndexError) as e:
-            raise Exception(f"Bucket with name '{name}' not found") from e
-        return Bucket.model_validate(response)
+            try:
+                response = self.request(
+                    spec.method,
+                    url=spec.endpoint,
+                    params=spec.params,
+                    headers=spec.headers,
+                ).json()
+                items = response.get("value", [])
+                if not items:
+                    raise LookupError(f"Bucket with name '{name}' not found")
+                bucket_data = items[0]
+            except (KeyError, IndexError) as e:
+                raise LookupError(f"Bucket with name '{name}' not found") from e
+
+        bucket = Bucket.model_validate(bucket_data)
+        return bucket
 
     @traced(name="buckets_retrieve", run_type="uipath")
     @infer_bindings(resource_type="bucket")
@@ -404,26 +657,177 @@ class BucketsService(FolderContext, BaseService):
             folder_path (Optional[str]): The path of the folder where the bucket resides.
 
         Returns:
-            Response: The bucket details.
+            Bucket: The bucket resource instance.
 
         Raises:
             ValueError: If neither bucket key nor bucket name is provided.
             Exception: If the bucket with the specified name is not found.
+
+        Examples:
+            >>> bucket = await sdk.buckets.retrieve_async(name="my-storage")
+            >>> print(bucket.name, bucket.identifier)
         """
         if not (key or name):
             raise ValueError("Must specify a bucket name or bucket key")
+
         if key:
             spec = self._retrieve_by_key_spec(
                 key, folder_key=folder_key, folder_path=folder_path
             )
+            try:
+                response = (
+                    await self.request_async(
+                        spec.method,
+                        url=spec.endpoint,
+                        params=spec.params,
+                        headers=spec.headers,
+                    )
+                ).json()
+                if "value" in response:
+                    items = response.get("value", [])
+                    if not items:
+                        raise LookupError(f"Bucket with key '{key}' not found")
+                    bucket_data = items[0]
+                else:
+                    bucket_data = response
+            except (KeyError, IndexError) as e:
+                raise LookupError(f"Bucket with key '{key}' not found") from e
         else:
             spec = self._retrieve_spec(
                 name,  # type: ignore
                 folder_key=folder_key,
                 folder_path=folder_path,
             )
+            try:
+                response = (
+                    await self.request_async(
+                        spec.method,
+                        url=spec.endpoint,
+                        params=spec.params,
+                        headers=spec.headers,
+                    )
+                ).json()
+                items = response.get("value", [])
+                if not items:
+                    raise LookupError(f"Bucket with name '{name}' not found")
+                bucket_data = items[0]
+            except (KeyError, IndexError) as e:
+                raise LookupError(f"Bucket with name '{name}' not found") from e
 
-        try:
+        bucket = Bucket.model_validate(bucket_data)
+        return bucket
+
+    @traced(name="buckets_list_files", run_type="uipath")
+    @infer_bindings(resource_type="bucket")
+    def list_files(
+        self,
+        *,
+        name: Optional[str] = None,
+        key: Optional[str] = None,
+        prefix: str = "",
+        folder_key: Optional[str] = None,
+        folder_path: Optional[str] = None,
+    ) -> Iterator[BucketFile]:
+        """List files in a bucket.
+
+        Args:
+            name: Bucket name
+            key: Bucket identifier
+            prefix: Filter files by prefix
+            folder_key: Folder key
+            folder_path: Folder path
+
+        Returns:
+            Iterator[BucketFile]: Iterator of files in the bucket
+
+        Note:
+            Returns an iterator for memory efficiency. Use list() to materialize all results:
+            files = list(sdk.buckets.list_files(name="my-storage"))
+
+            This method automatically handles pagination, fetching up to 500 files per request.
+
+        Examples:
+            >>> for file in sdk.buckets.list_files(name="my-storage"):
+            ...     print(file.path)
+            >>> files = list(sdk.buckets.list_files(name="my-storage", prefix="data/"))
+        """
+        bucket = self.retrieve(
+            name=name, key=key, folder_key=folder_key, folder_path=folder_path
+        )
+
+        continuation_token: Optional[str] = None
+
+        while True:
+            spec = self._list_files_spec(
+                bucket.id,
+                prefix,
+                continuation_token=continuation_token,
+                folder_key=folder_key,
+                folder_path=folder_path,
+            )
+            response = self.request(
+                spec.method,
+                url=spec.endpoint,
+                params=spec.params,
+                headers=spec.headers,
+            ).json()
+
+            items = response.get("items", [])
+            for item in items:
+                yield BucketFile.model_validate(item)
+
+            continuation_token = response.get("continuationToken")
+            if not continuation_token:
+                break
+
+    @traced(name="buckets_list_files", run_type="uipath")
+    @infer_bindings(resource_type="bucket")
+    async def list_files_async(
+        self,
+        *,
+        name: Optional[str] = None,
+        key: Optional[str] = None,
+        prefix: str = "",
+        folder_key: Optional[str] = None,
+        folder_path: Optional[str] = None,
+    ) -> AsyncIterator[BucketFile]:
+        """List files in a bucket asynchronously.
+
+        Args:
+            name: Bucket name
+            key: Bucket identifier
+            prefix: Filter files by prefix
+            folder_key: Folder key
+            folder_path: Folder path
+
+        Returns:
+            AsyncIterator[BucketFile]: Async iterator of files in the bucket
+
+        Note:
+            Returns an async iterator for memory efficiency. Use list comprehension to materialize:
+            files = [f async for f in sdk.buckets.list_files_async(name="my-storage")]
+
+            This method automatically handles pagination, fetching up to 500 files per request.
+
+        Examples:
+            >>> async for file in sdk.buckets.list_files_async(name="my-storage"):
+            ...     print(file.path)
+            >>> files = [f async for f in sdk.buckets.list_files_async(name="my-storage", prefix="data/")]
+        """
+        bucket = await self.retrieve_async(
+            name=name, key=key, folder_key=folder_key, folder_path=folder_path
+        )
+
+        continuation_token: Optional[str] = None
+
+        while True:
+            spec = self._list_files_spec(
+                bucket.id,
+                prefix,
+                continuation_token=continuation_token,
+                folder_key=folder_key,
+                folder_path=folder_path,
+            )
             response = (
                 await self.request_async(
                     spec.method,
@@ -431,25 +835,343 @@ class BucketsService(FolderContext, BaseService):
                     params=spec.params,
                     headers=spec.headers,
                 )
-            ).json()["value"][0]
-        except (KeyError, IndexError) as e:
-            raise Exception(f"Bucket with name '{name}' not found") from e
-        return Bucket.model_validate(response)
+            ).json()
+
+            items = response.get("items", [])
+            for item in items:
+                yield BucketFile.model_validate(item)
+
+            continuation_token = response.get("continuationToken")
+            if not continuation_token:
+                break
+
+    @traced(name="buckets_delete", run_type="uipath")
+    @infer_bindings(resource_type="bucket")
+    def delete(
+        self,
+        *,
+        name: Optional[str] = None,
+        key: Optional[str] = None,
+        blob_file_path: str,
+        folder_key: Optional[str] = None,
+        folder_path: Optional[str] = None,
+    ) -> None:
+        """Delete a file from a bucket.
+
+        Args:
+            name: Bucket name
+            key: Bucket identifier
+            blob_file_path: Path to the file in the bucket
+            folder_key: Folder key
+            folder_path: Folder path
+
+        Examples:
+            >>> sdk.buckets.delete(name="my-storage", blob_file_path="data/file.txt")
+        """
+        bucket = self.retrieve(
+            name=name, key=key, folder_key=folder_key, folder_path=folder_path
+        )
+        spec = self._delete_file_spec(
+            bucket.id, blob_file_path, folder_key=folder_key, folder_path=folder_path
+        )
+        self.request(
+            spec.method,
+            url=spec.endpoint,
+            params=spec.params,
+            headers=spec.headers,
+        )
+
+    @traced(name="buckets_delete", run_type="uipath")
+    @infer_bindings(resource_type="bucket")
+    async def delete_async(
+        self,
+        *,
+        name: Optional[str] = None,
+        key: Optional[str] = None,
+        blob_file_path: str,
+        folder_key: Optional[str] = None,
+        folder_path: Optional[str] = None,
+    ) -> None:
+        """Delete a file from a bucket asynchronously.
+
+        Args:
+            name: Bucket name
+            key: Bucket identifier
+            blob_file_path: Path to the file in the bucket
+            folder_key: Folder key
+            folder_path: Folder path
+
+        Examples:
+            >>> await sdk.buckets.delete_async(name="my-storage", blob_file_path="data/file.txt")
+        """
+        bucket = await self.retrieve_async(
+            name=name, key=key, folder_key=folder_key, folder_path=folder_path
+        )
+        spec = self._delete_file_spec(
+            bucket.id, blob_file_path, folder_key=folder_key, folder_path=folder_path
+        )
+        await self.request_async(
+            spec.method,
+            url=spec.endpoint,
+            params=spec.params,
+            headers=spec.headers,
+        )
+
+    @traced(name="buckets_get_files", run_type="uipath")
+    @infer_bindings(resource_type="bucket")
+    def get_files(
+        self,
+        *,
+        name: Optional[str] = None,
+        key: Optional[str] = None,
+        prefix: str = "",
+        recursive: bool = False,
+        file_name_glob: Optional[str] = None,
+        folder_key: Optional[str] = None,
+        folder_path: Optional[str] = None,
+    ) -> Iterator[BucketFile]:
+        """Get files using OData GetFiles API (Studio-compatible).
+
+        This method uses the GetFiles API which is used by UiPath Studio activities.
+        Use this when you need:
+        - Recursive directory traversal
+        - Glob pattern filtering (e.g., "*.pdf")
+        - Compatibility with Studio activity behavior
+
+        Args:
+            name: Bucket name
+            key: Bucket identifier
+            prefix: Directory path to filter files (default: root)
+            recursive: Recurse subdirectories for flat view (default: False)
+            file_name_glob: File filter pattern (e.g., "*.pdf", "data_*.csv")
+            folder_key: Folder key
+            folder_path: Folder path
+
+        Returns:
+            Iterator[BucketFile]: Iterator of files matching criteria
+
+        Raises:
+            ValueError: If neither name nor key is provided
+            LookupError: If bucket not found
+            Exception: For API errors or invalid responses
+
+        Note:
+            For large buckets with 10,000+ files, consider using list_files()
+            which uses more efficient cursor-based pagination.
+
+        Examples:
+            >>> # Get all PDF files recursively
+            >>> for file in sdk.buckets.get_files(
+            ...     name="my-storage",
+            ...     recursive=True,
+            ...     file_name_glob="*.pdf"
+            ... ):
+            ...     print(f"{file.path} - {file.size} bytes")
+            >>>
+            >>> # Get files in specific directory
+            >>> files = list(sdk.buckets.get_files(
+            ...     name="my-storage",
+            ...     prefix="reports/"
+            ... ))
+        """
+        if not (name or key):
+            raise ValueError("Must specify either bucket name or key")
+
+        if file_name_glob is not None and not file_name_glob.strip():
+            raise ValueError("file_name_glob cannot be empty")
+
+        bucket = self.retrieve(
+            name=name, key=key, folder_key=folder_key, folder_path=folder_path
+        )
+
+        skip = 0
+        top = self._GET_FILES_PAGE_SIZE
+
+        while True:
+            spec = self._get_files_spec(
+                bucket.id,
+                prefix=prefix,
+                recursive=recursive,
+                file_name_glob=file_name_glob,
+                skip=skip,
+                top=top,
+                folder_key=folder_key,
+                folder_path=folder_path,
+            )
+
+            response = self.request(
+                spec.method,
+                url=spec.endpoint,
+                params=spec.params,
+                headers=spec.headers,
+            ).json()
+
+            items = response.get("value", [])
+
+            if not items:
+                break
+
+            for item in items:
+                if not item.get("IsDirectory", False):
+                    try:
+                        yield BucketFile.model_validate(item)
+                    except Exception as e:
+                        raise ValueError(
+                            f"Failed to parse file entry: {e}. Item: {item}"
+                        ) from e
+
+            if len(items) < top:
+                break
+
+            skip += top
+
+    @traced(name="buckets_get_files", run_type="uipath")
+    @infer_bindings(resource_type="bucket")
+    async def get_files_async(
+        self,
+        *,
+        name: Optional[str] = None,
+        key: Optional[str] = None,
+        prefix: str = "",
+        recursive: bool = False,
+        file_name_glob: Optional[str] = None,
+        folder_key: Optional[str] = None,
+        folder_path: Optional[str] = None,
+    ) -> AsyncIterator[BucketFile]:
+        """Async version of get_files().
+
+        See get_files() for detailed documentation.
+
+        Examples:
+            >>> async for file in sdk.buckets.get_files_async(
+            ...     name="my-storage",
+            ...     recursive=True,
+            ...     file_name_glob="*.pdf"
+            ... ):
+            ...     print(file.path)
+        """
+        if not (name or key):
+            raise ValueError("Must specify either bucket name or key")
+
+        if file_name_glob is not None and not file_name_glob.strip():
+            raise ValueError("file_name_glob cannot be empty")
+
+        bucket = await self.retrieve_async(
+            name=name, key=key, folder_key=folder_key, folder_path=folder_path
+        )
+
+        skip = 0
+        top = self._GET_FILES_PAGE_SIZE
+
+        while True:
+            spec = self._get_files_spec(
+                bucket.id,
+                prefix=prefix,
+                recursive=recursive,
+                file_name_glob=file_name_glob,
+                skip=skip,
+                top=top,
+                folder_key=folder_key,
+                folder_path=folder_path,
+            )
+
+            response = (
+                await self.request_async(
+                    spec.method,
+                    url=spec.endpoint,
+                    params=spec.params,
+                    headers=spec.headers,
+                )
+            ).json()
+
+            items = response.get("value", [])
+
+            if not items:
+                break
+
+            for item in items:
+                if not item.get("IsDirectory", False):
+                    try:
+                        yield BucketFile.model_validate(item)
+                    except Exception as e:
+                        raise ValueError(
+                            f"Failed to parse file entry: {e}. Item: {item}"
+                        ) from e
+
+            if len(items) < top:
+                break
+
+            skip += top
 
     @property
     def custom_headers(self) -> Dict[str, str]:
         return self.folder_headers
 
+    def _list_spec(
+        self,
+        folder_path: Optional[str],
+        folder_key: Optional[str],
+        name: Optional[str],
+        skip: int,
+        top: int,
+    ) -> RequestSpec:
+        """Build OData request for listing buckets."""
+        filters = []
+        if name:
+            escaped_name = name.replace("'", "''")
+            filters.append(f"contains(tolower(Name), tolower('{escaped_name}'))")
+
+        filter_str = " and ".join(filters) if filters else None
+
+        params: Dict[str, Any] = {"$skip": skip, "$top": top}
+        if filter_str:
+            params["$filter"] = filter_str
+
+        return RequestSpec(
+            method="GET",
+            endpoint=Endpoint("/orchestrator_/odata/Buckets"),
+            params=params,
+            headers={
+                **header_folder(folder_key, folder_path),
+            },
+        )
+
+    def _create_spec(
+        self,
+        name: str,
+        description: Optional[str],
+        identifier: str,
+        folder_path: Optional[str],
+        folder_key: Optional[str],
+    ) -> RequestSpec:
+        """Build request for creating bucket."""
+        body = {
+            "Name": name,
+            "Identifier": identifier,
+        }
+        if description:
+            body["Description"] = description
+
+        return RequestSpec(
+            method="POST",
+            endpoint=Endpoint("/orchestrator_/odata/Buckets"),
+            json=body,
+            headers={
+                **header_folder(folder_key, folder_path),
+            },
+        )
+
     def _retrieve_spec(
         self,
         name: str,
         folder_key: Optional[str] = None,
         folder_path: Optional[str] = None,
     ) -> RequestSpec:
+        escaped_name = name.replace("'", "''")
         return RequestSpec(
             method="GET",
             endpoint=Endpoint("/orchestrator_/odata/Buckets"),
-            params={"$filter": f"Name eq '{name}'", "$top": 1},
+            params={"$filter": f"Name eq '{escaped_name}'", "$top": 1},
             headers={
                 **header_folder(folder_key, folder_path),
             },
@@ -498,11 +1220,120 @@ class BucketsService(FolderContext, BaseService):
         folder_key: Optional[str] = None,
         folder_path: Optional[str] = None,
     ) -> RequestSpec:
+        escaped_key = key.replace("'", "''")
+        return RequestSpec(
+            method="GET",
+            endpoint=Endpoint(
+                f"/orchestrator_/odata/Buckets/UiPath.Server.Configuration.OData.GetByKey(identifier='{escaped_key}')"
+            ),
+            headers={
+                **header_folder(folder_key, folder_path),
+            },
+        )
+
+    def _list_files_spec(
+        self,
+        bucket_id: int,
+        prefix: str,
+        continuation_token: Optional[str] = None,
+        take_hint: int = 500,
+        folder_key: Optional[str] = None,
+        folder_path: Optional[str] = None,
+    ) -> RequestSpec:
+        """Build REST API request for listing files in a bucket.
+
+        Uses the /api/Buckets/{id}/ListFiles endpoint which supports pagination.
+
+        Args:
+            bucket_id: The bucket ID
+            prefix: Path prefix for filtering
+            continuation_token: Token for pagination
+            take_hint: Minimum number of files to return (default 500, max 1000)
+            folder_key: Folder key
+            folder_path: Folder path
+        """
+        params: Dict[str, Any] = {}
+        if prefix:
+            params["prefix"] = prefix
+        if continuation_token:
+            params["continuationToken"] = continuation_token
+        if take_hint:
+            params["takeHint"] = take_hint
+
+        return RequestSpec(
+            method="GET",
+            endpoint=Endpoint(f"/api/Buckets/{bucket_id}/ListFiles"),
+            params=params,
+            headers={
+                **header_folder(folder_key, folder_path),
+            },
+        )
+
+    def _delete_file_spec(
+        self,
+        bucket_id: int,
+        blob_file_path: str,
+        folder_key: Optional[str] = None,
+        folder_path: Optional[str] = None,
+    ) -> RequestSpec:
+        """Build request for deleting a file from a bucket."""
+        return RequestSpec(
+            method="DELETE",
+            endpoint=Endpoint(
+                f"/orchestrator_/odata/Buckets({bucket_id})/UiPath.Server.Configuration.OData.DeleteFile"
+            ),
+            params={"path": blob_file_path},
+            headers={
+                **header_folder(folder_key, folder_path),
+            },
+        )
+
+    def _get_files_spec(
+        self,
+        bucket_id: int,
+        prefix: str = "",
+        recursive: bool = False,
+        file_name_glob: Optional[str] = None,
+        skip: int = 0,
+        top: int = 500,
+        folder_key: Optional[str] = None,
+        folder_path: Optional[str] = None,
+    ) -> RequestSpec:
+        """Build OData request for GetFiles endpoint.
+
+        Args:
+            bucket_id: Bucket ID
+            prefix: Directory path prefix
+            recursive: Recurse subdirectories
+            file_name_glob: File name filter pattern
+            skip: Number of items to skip (pagination)
+            top: Number of items to return (pagination)
+            folder_key: Folder key
+            folder_path: Folder path
+
+        Returns:
+            RequestSpec: OData request specification
+        """
+        params: Dict[str, Any] = {}
+
+        params["directory"] = "/" if not prefix else prefix
+
+        if recursive:
+            params["recursive"] = "true"
+
+        if file_name_glob:
+            params["fileNameGlob"] = file_name_glob
+
+        if skip > 0:
+            params["$skip"] = skip
+        params["$top"] = top
+
         return RequestSpec(
             method="GET",
             endpoint=Endpoint(
-                f"/orchestrator_/odata/Buckets/UiPath.Server.Configuration.OData.GetByKey(identifier={key})"
+                f"/orchestrator_/odata/Buckets({bucket_id})/UiPath.Server.Configuration.OData.GetFiles"
             ),
+            params=params,
             headers={
                 **header_folder(folder_key, folder_path),
             },

uipath/models/__init__.py

@@ -2,7 +2,7 @@ from .action_schema import ActionSchema
 from .actions import Action
 from .assets import Asset, UserAsset
 from .attachment import Attachment
-from .buckets import Bucket
+from .buckets import Bucket, BucketFile
 from .connections import Connection, ConnectionMetadata, ConnectionToken, EventArguments
 from .context_grounding import ContextGroundingQueryResponse
 from .context_grounding_index import ContextGroundingIndex
@@ -51,4 +51,5 @@ __all__ = [
     "BaseUrlMissingError",
     "SecretMissingError",
     "Bucket",
+    "BucketFile",
 ]

uipath/models/buckets.py

@@ -1,6 +1,55 @@
 from typing import List, Optional
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
+
+
+class BucketFile(BaseModel):
+    """Represents a file within a bucket.
+
+    Supports both ListFiles API (lowercase fields) and GetFiles API (PascalCase fields).
+    """
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_by_alias=True,
+        extra="allow",
+    )
+
+    full_path: str = Field(
+        validation_alias=AliasChoices("fullPath", "FullPath"),
+        description="Full path within bucket",
+    )
+    content_type: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("contentType", "ContentType"),
+        description="MIME type",
+    )
+    size: int = Field(
+        validation_alias=AliasChoices("size", "Size"),
+        description="File size in bytes",
+    )
+    last_modified: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("lastModified", "LastModified"),
+        description="Last modification timestamp (ISO format)",
+    )
+    is_directory: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("IsDirectory", "isDirectory"),
+        description="Whether this entry is a directory",
+    )
+
+    @property
+    def path(self) -> str:
+        """Alias for full_path for consistency."""
+        return self.full_path
+
+    @property
+    def name(self) -> str:
+        """Extract filename from full path."""
+        return (
+            self.full_path.split("/")[-1] if "/" in self.full_path else self.full_path
+        )
 
 
 class Bucket(BaseModel):

{uipath-2.1.122.dist-info → uipath-2.1.123.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uipath
-Version: 2.1.122
+Version: 2.1.123
 Summary: Python SDK and CLI for UiPath Platform, enabling programmatic interaction with automation services, process management, and deployment tools.
 Project-URL: Homepage, https://uipath.com
 Project-URL: Repository, https://github.com/UiPath/uipath-python

{uipath-2.1.122.dist-info → uipath-2.1.123.dist-info}/RECORD

@@ -73,7 +73,7 @@ uipath/_cli/_evals/mocks/mockito_mocker.py,sha256=opwfELnvuh3krnPAg0MupkHTEmhCpQ
 uipath/_cli/_evals/mocks/mocks.py,sha256=IrvhtTtIuU5geopvCRglNhxKoOcChnnjQZMoYygx0PU,2225
 uipath/_cli/_push/models.py,sha256=K3k6QUMkiNIb3M4U0EgDlKz1UELxeMXLNVAj3qyhZ4U,470
 uipath/_cli/_push/sw_file_handler.py,sha256=ivHj0qzCvEP45M3x-Oi2edO5I-uhyHzgnidDF3JRoTk,36192
-uipath/_cli/_runtime/_contracts.py,sha256=d39hBwydFxMlF5VJSa4Fj_ZIWqr2iVUlHLTupBDrNZQ,36296
+uipath/_cli/_runtime/_contracts.py,sha256=sVHUww13iFsB7tDkbmD4ki41xd6nbAoJkoc9BLiXEh8,36352
 uipath/_cli/_runtime/_escalation.py,sha256=x3vI98qsfRA-fL_tNkRVTFXioM5Gv2w0GFcXJJ5eQtg,7981
 uipath/_cli/_runtime/_hitl.py,sha256=JAwTUKvxO4HpnZMwE4E0AegAPw_uYOwgt0OYcu6EvTg,11474
 uipath/_cli/_runtime/_logging.py,sha256=srjAi3Cy6g7b8WNHiYNjaZT4t40F3XRqquuoGd2kh4Y,14019
@@ -116,7 +116,7 @@ uipath/_services/actions_service.py,sha256=2RPMR-hFMsOlqEyjIf3aF7-lrf57jdrSD0pBj
 uipath/_services/api_client.py,sha256=kGm04ijk9AOEQd2BMxvQg-2QoB8dmyoDwFFDPyutAGw,1966
 uipath/_services/assets_service.py,sha256=pG0Io--SeiRRQmfUWPQPl1vq3csZlQgx30LBNKRmmF8,12145
 uipath/_services/attachments_service.py,sha256=NPQYK7CGjfBaNT_1S5vEAfODmOChTbQZforllFM2ofU,26678
-uipath/_services/buckets_service.py,sha256=5s8tuivd7GUZYj774DDUYTa0axxlUuesc4EBY1V5sdk,18496
+uipath/_services/buckets_service.py,sha256=FGWhJ3ewMEAahcSPY60wtFB0_qwAfaQAaAjqrC52VDk,44603
 uipath/_services/connections_service.py,sha256=tKJHHOKQYKR6LkgB-V_2d0vFpLEdFeMzwj_xmBVHUDw,18416
 uipath/_services/context_grounding_service.py,sha256=Pjx-QQQEiSKD-hY6ityj3QUSALN3fIcKLLHr_NZ0d_g,37117
 uipath/_services/documents_service.py,sha256=2mPZzmOl2r5i8RYvdeRSJtEFWSSsiXqIauTgNTW75s4,45341
@@ -195,13 +195,13 @@ uipath/eval/mocks/mockable.py,sha256=FJEE4iz6nchowGhoGR3FgF9VvymHnWJkUyakKOK4fIg
 uipath/eval/models/__init__.py,sha256=-V610Bw4daQQ2CwNUGwsEW5n56b_G2mMZY4vaChV2r4,716
 uipath/eval/models/llm_judge_types.py,sha256=_kPnyAoWyV_Idx-lAgAbHGq4akQRh-eDC2PCYG6T0Zc,9620
 uipath/eval/models/models.py,sha256=q-g-UDovrkNtA9jQxvAWvQRXG511ZQEVOm9mjTNBeVk,9746
-uipath/models/__init__.py,sha256=au-Bhk7w4Jl8Jn-_a1Ae30RX9N6eQJJ0-bd-QSbRiuU,1335
+uipath/models/__init__.py,sha256=8ZIx9XTjDoPYrnuxxgEfFMaldfcoHfMAt7YZ_LP4_d4,1365
 uipath/models/action_schema.py,sha256=tBn1qQ3NQLU5nwWlBIzIKIx3XK5pO_D1S51IjFlZ1FA,610
 uipath/models/actions.py,sha256=1vRsJ3JSmMdPkbiYAiHzY8K44vmW3VlMsmQUBAkSgrQ,3141
 uipath/models/assets.py,sha256=7x3swJRnG_a4VgjdXKKwraJLT5TF0u4wHsl6coOjX0g,2762
 uipath/models/attachment.py,sha256=lI6BxBY6DY5U6qZbxhkNu-usseA1zovYSTRtLq50ubI,1029
 uipath/models/auth.py,sha256=-CEo5KZVtZZgbAMatN6B1vBmGp8lTTumR8sMthRmL8I,345
-uipath/models/buckets.py,sha256=N3Lj_dVCv709-ywhOOdyCSvsuLn41eGuAfSiik6Q6F8,1285
+uipath/models/buckets.py,sha256=7uDonM5ddfhunP6Vn24kEa-iW_ZluJU4SaWEqB2dWu8,2754
 uipath/models/connections.py,sha256=jmzlfnddqlxjmiVhqsETRV6TQPH3fFqJGsygG0gUf7g,2745
 uipath/models/context_grounding.py,sha256=3MaF2Fv2QYle8UUWvKGkCN5XGpx2T4a34fdbBqJ2fCs,1137
 uipath/models/context_grounding_index.py,sha256=OhRyxZDHDSrEmBFK0-JLqMMMT64jir4XkHtQ54IKtc0,2683
@@ -225,8 +225,8 @@ uipath/tracing/_utils.py,sha256=emsQRgYu-P1gj1q7XUPJD94mOa12JvhheRkuZJpLd9Y,1505
 uipath/utils/__init__.py,sha256=VD-KXFpF_oWexFg6zyiWMkxl2HM4hYJMIUDZ1UEtGx0,105
 uipath/utils/_endpoints_manager.py,sha256=tnF_FiCx8qI2XaJDQgYkMN_gl9V0VqNR1uX7iawuLp8,8230
 uipath/utils/dynamic_schema.py,sha256=w0u_54MoeIAB-mf3GmwX1A_X8_HDrRy6p998PvX9evY,3839
-uipath-2.1.122.dist-info/METADATA,sha256=aAz2QNfA9s6UPHlfo0k5N3g9XKnlvGd_jMEz5oqn90s,6626
-uipath-2.1.122.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-uipath-2.1.122.dist-info/entry_points.txt,sha256=9C2_29U6Oq1ExFu7usihR-dnfIVNSKc-0EFbh0rskB4,43
-uipath-2.1.122.dist-info/licenses/LICENSE,sha256=-KBavWXepyDjimmzH5fVAsi-6jNVpIKFc2kZs0Ri4ng,1058
-uipath-2.1.122.dist-info/RECORD,,
+uipath-2.1.123.dist-info/METADATA,sha256=jnVXMo218T9D5w0meGX_NYFtoA7R64pfTpIg6UKypHo,6626
+uipath-2.1.123.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+uipath-2.1.123.dist-info/entry_points.txt,sha256=9C2_29U6Oq1ExFu7usihR-dnfIVNSKc-0EFbh0rskB4,43
+uipath-2.1.123.dist-info/licenses/LICENSE,sha256=-KBavWXepyDjimmzH5fVAsi-6jNVpIKFc2kZs0Ri4ng,1058
+uipath-2.1.123.dist-info/RECORD,,