​
StorageFolder Objects

class StorageFolder()

Represents a storage folder within the Encord system.

​
uuid

@property
def uuid() -> UUID

Gets the unique identifier of the folder.

Returns:

  • UUID - The UUID of the folder.

​
parent_uuid

@property
def parent_uuid() -> Optional[UUID]

Gets the unique identifier of the parent folder.

Returns:

  • Optional[UUID] - The UUID of the parent folder, or None if there is no parent.

​
parent

@property
def parent() -> Optional["StorageFolder"]

Gets the parent folder.

Returns:

  • Optional[StorageFolder] - The parent StorageFolder object, or None if there is no parent.

​
name

@property
def name() -> str

Gets the name of the folder.

Returns:

  • str - The name of the folder.

​
description

@property
def description() -> str

Gets the description of the folder.

Returns:

  • str - The description of the folder.

​
client_metadata

@property
def client_metadata() -> Optional[Dict[str, Any]]

Gets the client metadata of the folder.

Returns:

Optional[Dict[str, Any]]: The client metadata as a dictionary, or None if there is no metadata.

​
path_to_root

@property
def path_to_root() -> List[PathElement]

Gets the path elements from the current folder to the root.

Returns:

  • List[PathElement] - A list of PathElement objects representing the path to the root.

​
list_items

def list_items(*,
               search: Optional[str] = None,
               is_in_dataset: Optional[bool] = None,
               item_types: Optional[List[StorageItemType]] = None,
               order: FoldersSortBy = FoldersSortBy.NAME,
               get_signed_urls: bool = False,
               desc: bool = False,
               page_size: int = 100) -> Iterable["StorageItem"]

Lists items in the folder.

Arguments:

  • 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. True and False select only linked and only unlinked items, respectively. None includes all items regardless of their dataset links.
  • item_types Optional[List[StorageItemType]] - Filter items by type.
  • order FoldersSortBy - Sort order. Defaults to FoldersSortBy.NAME.
  • get_signed_urls bool - Whether to get signed URLs for the items. Defaults to False.
  • desc bool - Sort in descending order. Defaults to False.
  • page_size int - Number of items to return per page. Default if not specified is 100. Maximum value is 1000.

Returns:

  • Iterable[StorageItem] - Iterable of items in the folder.

​
delete

def delete() -> None

Deletes the folder.

​
upload_image

def upload_image(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Uploads an image to a folder in Encord storage.

Arguments:

  • file_path Union[Path, str] - Path to the image file (e.g., ‘/home/user/data/image.png’).
  • title Optional[str] - The image title. If unspecified, this will be the file name.
  • client_metadata Optional[Dict[str, Any]] - Optional arbitrary metadata to be associated with the image. Should be a dictionary that is JSON-serializable.
  • cloud_upload_settings CloudUploadSettings - Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

  • UUID - 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, e.g., due to being in an unsupported format.

​
upload_video

def upload_video(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    video_metadata: Optional[CustomerProvidedVideoMetadata] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Uploads a video to a folder in Encord storage.

Arguments:

  • file_path Union[Path, str] - Path to the video file (e.g., ‘/home/user/data/video.mp4’).
  • title Optional[str] - The video title. If unspecified, this will be the file name. This title should include an extension. For example, “encord_video.mp4”.
  • client_metadata Optional[Dict[str, Any]] - Optional arbitrary metadata to be associated with the video. Should be a dictionary that is JSON-serializable.
  • video_metadata Optional[CustomerProvidedVideoMetadata] - Optional media metadata for a video file; if provided, Encord service will skip frame synchronization checks and will use the values specified here to render the video in the label editor.
  • cloud_upload_settings CloudUploadSettings - Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

  • UUID - The UUID of the newly created video item.

Raises:

  • AuthorizationError - If the user is not authorized to access the folder.
  • EncordException - If the video could not be uploaded, e.g., due to being in an unsupported format.

​
re_encode_videos

def re_encode_videos(storage_items: List[UUID], process_title: str,
                     force_full_reencoding: bool) -> UUID

Re-encodes the specified video items.

Arguments:

  • storage_items List[UUID] - List of UUIDs representing the video items to be re-encoded.
  • process_title str - Title for the re-encoding process.
  • force_full_reencoding bool - Flag to force full re-encoding.

Returns:

  • UUID - The UUID of the re-encoding process.

​
get_re_encoding_status

def get_re_encoding_status(process_hash: UUID) -> ReencodeVideoItemsResponse

Retrieves the status of a re-encoding process.

Arguments:

  • process_hash UUID - The UUID of the re-encoding process.

Returns:

  • ReencodeVideoItemsResponse - Response object containing the status of the re-encoding process.

​
create_dicom_series

def create_dicom_series(
    file_paths: Sequence[Union[str, Path]],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Uploads a DICOM series to a folder in Encord storage.

Arguments:

  • file_paths Sequence[Union[str, Path]] - A list of paths to DICOM files, e.g., [‘/home/user/data/DICOM_1.dcm’, ‘/home/user/data/DICOM_2.dcm’].
  • title Optional[str] - The title of the DICOM series. If unspecified, this will be randomly generated. This title should NOT include an extension. For example, “encord_image_group”.
  • client_metadata Optional[Dict[str, Any]] - Optional arbitrary metadata to be associated with the DICOM series. Should be a dictionary that is JSON-serializable.
  • cloud_upload_settings CloudUploadSettings - Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

  • UUID - The UUID of the newly created DICOM series item.

Raises:

  • AuthorizationError - If the user is not authorized to access the folder.
  • EncordException - If the series could not be uploaded, e.g., due to being in an unsupported format.

​
create_image_group

def create_image_group(
    file_paths: Collection[Union[Path, str]],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Creates an image group in Encord storage. Choose this type of image upload for non-sequential images that are logically connected (e.g., multiple views of the same object). See also :meth:.Folder.create_image_sequence and :meth:.Folder.upload_image.

Arguments:

  • file_paths Collection[Union[Path, str]] - A list of paths to images, e.g., [‘/home/user/data/img1.png’, ‘/home/user/data/img2.png’].
  • title Optional[str] - The title of the image group. If unspecified, this will be randomly generated. This title should NOT include an extension. For example, “encord_image_group”.
  • client_metadata Optional[Dict[str, Any]] - Optional arbitrary metadata to be associated with the image group. Should be a dictionary that is JSON-serializable.
  • cloud_upload_settings CloudUploadSettings - Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

  • UUID - The UUID of the newly created image group item.

Raises:

  • AuthorizationError - If the user is not authorized to access the folder.
  • EncordException - If the images could not be uploaded, e.g., due to being in an unsupported format.

​
create_image_sequence

def create_image_sequence(
    file_paths: Collection[Union[Path, str]],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Creates an image sequence in Encord storage. Choose this type of image upload for sequential images (a timelapse or similar). A compressed video will be created from the images.

See also :meth:.Folder.create_image_group and :meth:.Folder.upload_image.

Arguments:

  • file_paths Collection[Union[Path, str]] - A list of paths to images, e.g., [‘/home/user/data/img1.png’, ‘/home/user/data/img2.png’].
  • title Optional[str] - The title of the image sequence. If unspecified, this will be randomly generated. This title should NOT include an extension. For example, “front camera 2024-04-01”.
  • client_metadata Optional[Dict[str, Any]] - Optional arbitrary metadata to be associated with the image sequence. Should be a dictionary that is JSON-serializable.
  • cloud_upload_settings CloudUploadSettings - Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

  • UUID - The UUID of the newly created image sequence item.

Raises:

  • AuthorizationError - If the user is not authorized to access the folder.
  • EncordException - If the images could not be uploaded, e.g., due to being in an unsupported format.

​
upload_audio

def upload_audio(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    audio_metadata: Optional[CustomerProvidedAudioMetadata] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Upload audio to a Folder in Encord storage.

Arguments:

  • file_path - File path to audio. For example: ‘/home/user/data/audio.mp3’ title: The audio title. If unspecified, the file name is the title. This title should include an extension. For example “encord_audio.mp3”. client_metadata: Optional custom metadata to be associated with the audio. Should be a dictionary that is JSON-serializable. audio_metadata: Optional media metadata for an audio file; if provided, Encord service skips scanning the audio file cloud_upload_settings: Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

UUID of the newly created audio item.

Raises:

  • AuthorizationError - If the user is not authorized to access the folder.

  • EncordException - If the audio could not be uploaded. For example, due to being in an unsupported format.

    audio_metadata

    audio_metadata for audio files; if provided, frame synchronization checks are skipped.

    • duration: float - Audio duration in seconds.
    • file_size: int - Size of the audio file in bytes.
    • mime_type: str - MIME type of the audio file (for example: audio/mpeg or audio/wav).
    • sample_rate: int - Sample rate (int) in Hz.
    • bit_depth: int - Size of each sample (int) in bits.
    • codec: str - Codec (for example: mp3, pcm).
    • num_channels: int - Number of channels.

​
add_private_data_to_folder_start

def add_private_data_to_folder_start(integration_id: str,
                                     private_files: Union[str, Dict, Path,
                                                          TextIO,
                                                          DataUploadItems],
                                     ignore_errors: bool = False) -> UUID

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

Arguments:

  • integration_id str - The integration ID for the folder. private_files (Union[str, Dict, Path, TextIO, DataUploadItems]): The specification of private files to be added. Can be either a JSON in Encord upload format (see the relevant documentation), or an :class:encord.orm.storage.DataUploadItems object.
  • ignore_errors bool - If True, errors will be ignored during the upload process.

Returns:

  • UUID - The UUID of the upload job.

​
add_private_data_to_folder_get_result

def add_private_data_to_folder_get_result(
        upload_job_id: UUID,
        timeout_seconds: int = 7 * 24 * 60 * 60) -> UploadLongPollingState

Retrieves the result of adding private data to a folder in Encord storage.

Arguments:

  • upload_job_id UUID - The UUID of the upload job.
  • timeout_seconds int - The timeout in seconds for the upload job.

Returns:

  • UploadLongPollingState - The state of the upload job.

​
list_subfolders

def list_subfolders(*,
                    search: Optional[str] = None,
                    dataset_synced: Optional[bool] = None,
                    order: FoldersSortBy = FoldersSortBy.NAME,
                    desc: bool = False,
                    page_size: int = 100) -> Iterable["StorageFolder"]

Lists subfolders of the current folder.

Arguments:

  • search Optional[str] - Search string to filter folders by name.
  • dataset_synced Optional[bool] - Include or exclude folders that are mirrored by a dataset. If None, no filtering is applied.
  • order FoldersSortBy - Sort order for the folders. See :class:encord.storage.FoldersSortBy for available options.
  • desc bool - If True, sort in descending order.
  • page_size int - Number of folders to return per page. Default if not specified is 100. Maximum value is 1000.

Returns:

  • Iterable[StorageFolder] - An iterable of :class:encord.StorageFolder objects.

​
find_subfolders

def find_subfolders(search: Optional[str] = None,
                    dataset_synced: Optional[bool] = None,
                    order: FoldersSortBy = FoldersSortBy.NAME,
                    desc: bool = False,
                    page_size: int = 100) -> Iterable["StorageFolder"]

Recursively searches for storage folders, starting from this folder.

Arguments:

  • search Optional[str] - Search string to filter folders by name.
  • dataset_synced Optional[bool] - Include or exclude folders that are mirrored by a dataset. If None, no filtering is applied.
  • order FoldersSortBy - Sort order for the folders. See :class:encord.storage.FoldersSortBy for available options.
  • desc bool - If True, sort in descending order.
  • page_size int - Number of folders to return per page. Default if not specified is 100. Maximum value is 1000.

Returns:

  • Iterable[StorageFolder] - An iterable of :class:encord.StorageFolder objects.

​
create_subfolder

def create_subfolder(
        name: str,
        description: Optional[str] = None,
        client_metadata: Optional[Dict[str, Any]] = None) -> "StorageFolder"

Create a new subfolder of this folder. See also :meth:encord.user_client.EncordUserClient.create_storage_folder.

Arguments:

  • name - The name of the folder.
  • description - The description of the folder.
  • client_metadata - Optional arbitrary metadata to be associated with the folder. Should be a dictionary that is JSON-serializable.

Returns:

The created storage folder. See :class:encord.storage.StorageFolder for details.

​
find_items

def find_items(search: Optional[str] = None,
               is_in_dataset: Optional[bool] = None,
               item_types: Optional[List[StorageItemType]] = None,
               order: FoldersSortBy = FoldersSortBy.NAME,
               desc: bool = False,
               get_signed_urls: bool = False,
               page_size: int = 100) -> Iterable["StorageItem"]

Recursively search for storage items, starting from this folder.

Arguments:

  • 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. True and False select only linked and only unlinked items, respectively. None includes all items regardless of their dataset links.
  • item_types Optional[List[StorageItemType]] - Filter items by type.
  • order FoldersSortBy - Sort order.
  • desc bool - Sort in descending order.
  • get_signed_urls bool - If True, return signed URLs for the items.
  • page_size int - Number of items to return per page. Default if not specified is 100. Maximum value is 1000.

Returns:

  • Iterable[StorageItem] - An iterable of items in the folder and its subfolders.

Raises:

  • ValueError - If neither search nor item_types are provided.

​
get_summary

def get_summary() -> StorageFolderSummary

Get a summary of the folder (total size, number of items, etc).

Returns:

  • StorageFolderSummary - A summary of the folder.

See Also:

:class:encord.StorageFolderSummary for the exact set of information provided.

​
update

def update(name: Optional[str] = None,
           description: Optional[str] = None,
           client_metadata: Optional[Dict[str, Any]] = None,
           bundle: Optional[Bundle] = None) -> None

Update the folder’s modifiable properties. Any parameters that are not provided will not be updated.

Arguments:

  • name Optional[str] - New folder name.
  • description Optional[str] - New folder description.
  • client_metadata Optional[Dict[str, Any]] - New client metadata.
  • bundle Optional[Bundle] - Optional :class:encord.http.Bundle to use for the operation. If provided, the operation will be bundled into a single server call with other item updates using the same bundle.

Returns:

None

​
move_to_folder

def move_to_folder(
        target_folder: Optional[Union["StorageFolder", UUID]]) -> None

Move the folder to another folder (specify folder object or UUID), or to the root level if target_folder is None.

Arguments:

  • target_folder Optional[Union[StorageFolder, UUID]] - The target folder to move to, or None to move to the root level.

Returns:

None

​
move_items_to_folder

def move_items_to_folder(target_folder: Union["StorageFolder", UUID],
                         items_to_move: Sequence[Union[UUID, "StorageItem"]],
                         allow_mirror_dataset_changes: bool = False) -> None

Move items (list of StorageItem objects or UUIDs) to another folder (specify folder object or UUID).

Arguments:

  • target_folder Union[StorageFolder, UUID] - Target folder to move items to.
  • items_to_move Sequence[Union[UUID, StorageItem]] - List of items to move. All the items should be immediate children of the current folder.
  • allow_mirror_dataset_changes bool - If True, allow moving items that are linked to a mirror dataset. By default, moving such items is prohibited, as it would result in data units being removed from a dataset, potentially deleting related annotations and other data.

Returns:

None

​
delete_storage_items

def delete_storage_items(item_uuids: List[UUID],
                         remove_unused_frames: bool = True) -> None

Delete storage items by their UUIDs.

Arguments:

  • item_uuids List[UUID] - List of UUIDs of items to delete. All the items should be immediate children of the current folder.
  • remove_unused_frames bool - If True (default), remove individual images or DICOM files from image groups or DICOM series that are not used in any other item.

Returns:

None

​
list_groups

def list_groups() -> Iterable[StorageFolderGroup]

List all groups that have access to this folder.

​
add_group

def add_group(group_hash: Union[List[UUID], UUID], user_role: StorageUserRole)

Allow access to this folder for members of a group.

Arguments:

  • group_hash - Group hash, or a list of group hashes to be added.
  • user_role - User role that the group will be given.

Returns:

None

​
remove_group

def remove_group(group_hash: Union[List[UUID], UUID])

Revoke access to the folder from the members of a group.

Arguments:

  • group_hash - Group hash, or a list of group hashes to be removed.

Returns:

None

​
refetch_data

def refetch_data() -> None

Refetch data for the folder.

Returns:

None

Was this page helpful?

FilterPresetStorageItem