From 1821ed2921f8e443fd93aecb70799285b136e200 Mon Sep 17 00:00:00 2001 From: Laverne-Encord <145356218+Laverne-Encord@users.noreply.github.com> Date: Tue, 29 Apr 2025 09:21:47 +0100 Subject: [PATCH] Cloud-synced Folder Docstrings updates --- encord/orm/storage.py | 12 ++++++------ encord/storage.py | 20 ++++++++++---------- encord/user_client.py | 4 ++-- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/encord/orm/storage.py b/encord/orm/storage.py index 84ac69394..5cfacd7b4 100644 --- a/encord/orm/storage.py +++ b/encord/orm/storage.py @@ -757,7 +757,7 @@ class SyncPrivateDataWithCloudSyncedFolderStatus(CamelStrEnum): """ The synchronization job is currently in progress. - This status indicates that either: + This status indicates that: - The job is queued and waiting to be processed - The job is actively processing bucket content - The job is creating or updating items in the Encord storage folder @@ -765,19 +765,19 @@ class SyncPrivateDataWithCloudSyncedFolderStatus(CamelStrEnum): DONE = auto() """ - The synchronization job has successfully completed. + The synchronization job successfully completed. This status indicates that all phases of the synchronization (bucket scanning, - item creation/updating/tombstoning) have been completed without critical errors. - Note that individual items may still have failed to process (check upload_jobs_units_error). + item creation/updating/tombstoning) have completed without critical errors. + NOTE: Individual items may still have failed to process (check upload_jobs_units_error). """ ERROR = auto() """ The synchronization job encountered a critical error. - This status indicates that a severe error occurred during synchronization, - such as: + This status indicates that a severe error occurred during synchronization. + For example: - Unable to access the cloud storage bucket - Database transaction failures - Other system-level errors diff --git a/encord/storage.py b/encord/storage.py index 1217418c6..340df01d7 100644 --- a/encord/storage.py +++ b/encord/storage.py @@ -834,16 +834,16 @@ def add_private_data_to_folder_start( return self._add_data_to_folder_start(integration_id, private_files, ignore_errors) def sync_private_data_with_cloud_synced_folder_start(self) -> UUID: - """Start synchronization of a cloud-synced folder with its remote cloud storage bucket. + """Starts synchronization of a cloud-synced folder with its remote cloud storage bucket. This method triggers a synchronization job that scans the cloud storage bucket linked - to this folder and updates the Encord storage folder to match. The synchronization is - performed asynchronously in the background, and this method returns immediately with - a job UUID that can be used to track the progress. + to the cloud-synced folder. Synchronization between cloud storage and the cloud-synced folder is + performed asynchronously in the background. This method returns immediately with + a job UUID that can be used to track the synchronization progress. The synchronization process: - 1. Scans the cloud bucket for files - 2. Creates new storage items for files that exist in the bucket but not in the folder + 1. Scans the cloud bucket for files. + 2. Creates new storage items for files that exist in the bucket but not in the cloud-synced folder. 3. Updates the tombstone status of items (marks as tombstone if deleted from bucket, restores if re-added) 4. Updates items if they have the same path but different content (different checksum) @@ -858,8 +858,8 @@ def sync_private_data_with_cloud_synced_folder_start(self) -> UUID: Note: This method can only be used with folders created with cloud_synced_folder_params. - The SDK process can be terminated after starting the job - the synchronization - will continue running on the server. + The SDK process can be terminated after starting the job. The synchronization + continues running on the server. """ sync_job_uuid = self._api_client.post( @@ -884,7 +884,7 @@ def sync_private_data_with_cloud_synced_folder_get_result( """Poll for the results of a cloud-synced folder synchronization job. This method polls for the status of a synchronization job started with - `sync_private_data_with_cloud_synced_folder_start()`. It uses long polling to efficiently + `sync_private_data_with_cloud_synced_folder_start()`. It uses long polling to wait for job completion without constantly making API requests. The method returns once the job completes or the timeout is reached. @@ -902,7 +902,7 @@ def sync_private_data_with_cloud_synced_folder_get_result( with this folder. Note: - This method will log progress information as it polls for results. For very large + This method logs progress information as it polls for results. For very large buckets, the synchronization process can take a significant amount of time. """ diff --git a/encord/user_client.py b/encord/user_client.py index ecbe4941e..19578b3f9 100644 --- a/encord/user_client.py +++ b/encord/user_client.py @@ -1204,8 +1204,8 @@ def create_storage_folder( client_metadata: Optional arbitrary metadata to be associated with the folder. Should be a dictionary that is JSON-serializable. parent_folder: The parent folder of the folder; or `None` if the folder is to be created at the root level. - cloud_synced_folder_params: Passing this will create cloud synced folder, leaving this a `None` will create - a normal folder for further data uploads. + cloud_synced_folder_params: Passing this parameter creates a cloud-synced folder. Specifying `None` creates + a normal folder for data uploads. Returns: The created storage folder. See :class:`encord.storage.StorageFolder` for details.