StorageFolder

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 files 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]): A JSON file specifying the cloud storage files to be uploaded. This can be a local path to the JSON file, a JSON 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.