Storage Folder

StorageFolder

class encord.storage.StorageFolder(api_client, orm_folder)

Initializes a StorageFolder instance.

Parameters:

api_client (ApiClient): The API client used to interact with the backend.
orm_folder (orm_storage.StorageFolder): The ORM model of the storage folder.

property uuid: UUID

Gets the unique identifier (UUID) of the folder.

Return Type:

UUID

property parent_uuid: Optional[UUID]

Gets the UUID of the parent folder, if any.

Return Type:

Optional[UUID]

property parent: Optional[StorageFolder]

Gets the parent folder as a StorageFolder object, if any.

**Return Type:**

Optional[StorageFolder]

property name: str

Gets the name of the folder.

Return Type:

str

property description: str

Gets the description of the folder.

Return Type:

str

property client_metadata: Optional[Dict[str, Any]]

Gets the parsed client metadata of the folder if available.

Return Type:

Optional[Dict[str, Any]]

list_items

list_items(search, is_in_dataset, item_types, order)

Lists all in the folder.

Parameters:

search (Optional[str]): Search string to filter items by name.
is_in_dataset (Optional[bool]): Filter items by whether they are linked to any Dataset.
item_types (Optional[List[StorageItemType]]): Filter items by type.
order (orm_storage.FoldersSortBy): Sort order.
get_signed_urls (bool): If True, signed URLs for all items are returned.
desc (bool): If True, items are sorted in descending order.
page_size (int): Number of items returned per page.

Return type:

IterableStorageItem

Returns:

An iterable of all Storage items in the folder.

delete

delete()

Deletes the folder.

upload_image

upload_image(file_path, title, client_metadata, cloud_upload_settings)

Uploads an image to the folder.

Parameters:

file_path (Union[Path, str]): Path to the image file.
title (Optional[str]): The title of the image.
client_metadata (Optional[Dict[str, Any]]): Custom metadata you can supply for the image.
cloud_upload_settings (CloudUploadSettings): Settings for cloud upload.

Return type:

UUID

Returns:

The UUID of the newly created image item.

Raises:

AuthorizationError: If the user is not authorized to access the folder.
EncordException: If the image could not be uploaded.

upload_video

upload_video(file_path, title, client_metadata, video_metadata, cloud_upload_settings)

Uploads a video file to a folder in Encord Storage.

Parameters:

file_path (Union[Path, str]): Path to the video file (e.g., '/home/user/data/video.mp4').
title (Optional[str]): Optional title for the video. If not specified, the file name is used as the title.
client_metadata (Optional[Dict[str, Any]]): Custom metadata you can supply for the video.
video_metadata (Optional[CustomerProvidedVideoMetadata]): video_metadata for video files; if provided, frame synchronization checks are skipped.
cloud_upload_settings (CloudUploadSettings): Settings for uploading data into the cloud.

Return Type:

UUID

Returns:

The UUID of the newly created video item.

Raises:

AuthorizationError: If the user lacks authorization to access the folder.
EncordException: If the video could not be uploaded, e.g., due to an unsupported format.

create_dicom_series

create_dicom_series(file_paths, title, client_metadata, cloud_upload_settings)

Uploads a series of DICOM files to a folder in Encord storage.

Parameters:

file_paths (List[str]): A list of paths to the DICOM files.
title (Optional[str]): Optional title for the DICOM series. If not specified, a title is randomly generated.
client_metadata (Optional[Dict[str, Any]]): Custom metadata you can supply for the DICOM series.
cloud_upload_settings (CloudUploadSettings): Settings for uploading data into the cloud.

Returns:

The UUID of the newly created DICOM series item.

Return type:

UUID

Raises:

AuthorizationError: If the user lacks authorization to access the folder.
EncordException: If the DICOM series could not be uploaded, e.g., due to an unsupported format.

create_image_group

create_image_group(file_paths, title, client_metadata, cloud_upload_settings)

Creates an image group in Encord storage, used for non-sequential images that are logically connected.

Parameters:

file_paths (List[str]): List of paths to images.
title (Optional[str]): Optional title for the image group. If not specified, a title is randomly generated.
client_metadata (Optional[Dict[str, Any]]): Custom metadata you can supply for the image sequence.
cloud_upload_settings (CloudUploadSettings): Settings for uploading data into the cloud.

Returns:

The UUID of the newly created image group item.

Return type:

UUID

Raises:

AuthorizationError: If the user lacks authorization to access the folder.
EncordException: If the images could not be uploaded, e.g., due to an unsupported format.

create_image_sequence

create_image_sequence(file_paths, title, client_metadata, cloud_upload_settings)

Creates an image sequence in Encord storage, used for sequential images.

Parameters:

file_paths (List[str]): List of paths to images.
title (Optional[str]): Optional title for the image sequence. If not specified, a title is randomly generated.
client_metadata (Optional[Dict[str, Any]]): Custom metadata you can supply for the image sequence.
cloud_upload_settings (CloudUploadSettings): Settings for uploading data into the cloud.

Returns:

The UUID of the newly created image sequence item.

Return type:

UUID

Raises:

AuthorizationError: If the user lacks authorization to access the folder.
EncordException: If the images could not be uploaded, e.g., due to an unsupported format.

Here are the SDK reference entries for the methods you provided in the style of the initial example:

add_private_data_to_folder_start

add_private_data_to_folder_start(integration_id, private_files, ignore_errors)

Starts the process of adding private cloud data to a folder in Encord storage.

Parameters:

integration_id (str): Identifier for the integration under which the data is being uploaded.
private_files (Union[str, Dict, Path, TextIO]): The private files to be uploaded. This can be a path, a dictionary of file data, or a text stream.
ignore_errors (bool, optional): If True, continues processing when errors are encountered. Default value is False.

Returns:

The UUID of the upload job.

Return Type:

UUID

add_private_data_to_folder_get_result

add_private_data_to_folder_get_result(upload_job_id, timeout_seconds)

Retrieves the result of an upload job to add private data to a folder.

Parameters:

upload_job_id (UUID): The UUID of the upload job.
timeout_seconds (int, optional): The maximum time in seconds to wait for the upload job to complete. Defaults to 604800 seconds (7 days).

Returns:

The state of the upload job, which includes status and any errors encountered.

Return type:

orm_storage.UploadLongPollingState

list_subfolders

list_subfolders(search, dataset_synced, order, desc, page_size)

Lists the subfolders of the current folder.

Parameters:

search (Optional[str], optional): Search string to filter folders by name.
dataset_synced (Optional[bool], optional): Filter folders based on whether they are synced with a dataset.
order (FoldersSortBy): Order in which to sort the folders. Defaults to FoldersSortBy.NAME.
desc (optional bool): If True, items are sorted in descending order.
page_size (int, optional): Number of folders to return per page. Defaults to 100.

Returns:

An iterable of StorageFolder objects.

Return type:

Iterable[StorageFolder]

get_summary

get_summary()

Gets a summary of the folder.

Returns:

A summary of the folder, including total size, number of items, and other relevant information.

Return type:

StorageFolderSummary

update

update()

Updates the properties of the folder.

Parameters:

name (Optional[str], optional): The new name of the folder.
description (Optional[str], optional): The new description of the folder.
client_metadata (Optional[Dict[str, Any]], optional): New metadata to associate with the folder.

move_to_folder

move_to_folder(target_folder)

Moves the folder to another folder, or to the root level.

Parameters:

target_folder (Optional[Union["StorageFolder", UUID]], optional): The target folder or its UUID. If None, the folder is moved to the root level.

move_items_to_folder

move_items_to_folder(target_folder, items_to_move)

Moves items to another folder.

Parameters:

target_folder (Union["StorageFolder", UUID]): The target folder or its UUID.
items_to_move (List[Union[UUID, "StorageItem"]]): List of items to move, specified by their UUIDs or StorageItem objects.

delete_storage_items

delete_storage_items(item_uuids, remove_unused_frames)

Deletes specified items from the folder.

Parameters:

item_uuids (List[UUID]): List of UUIDs of the items to delete.
remove_unused_frames (bool, optional): If True unused frames associated with deleted items are also removed. Defaults to True.

refetch_data

refetch_data()

Refetches the data for the folder from Encord storage.