Storage

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.

folder_type

@property
def folder_type() -> StorageFolderType

Gets the type of the folder.

Returns:

• StorageFolderType - CLOUD_LINKED for a cloud-synced folder, GENERIC for a regular folder (see also is_cloud_synced).

is_cloud_synced

@property
def is_cloud_synced() -> bool

Whether this folder is cloud-synced (mounted on an external bucket via an integration).

Returns:

• bool - True if the folder is a cloud-synced (CLOUD_LINKED) folder, False for a regular folder.

integration_hash

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

Gets the cloud integration backing this folder.

Returns:

• Optional[UUID] - The UUID of the cloud integration for a cloud-synced folder, or None for a regular folder.

remote_url

@property
def remote_url() -> Optional[str]

Gets the remote bucket/prefix this folder is synced with.

Returns:

• Optional[str] - The remote URL for a cloud-synced folder, or None for a regular folder.

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,
               include_client_metadata: bool = True,
               resolve_client_metadata_locally: 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.
• include_client_metadata bool - Optionally include client metadata into the result of this query. Defaults to True.
• resolve_client_metadata_locally bool - Has no effect unless include_client_metadata is set. When true, the SDK downloads the metadata client-side instead of the server embedding it directly in the response. Use this to prevent server timeouts for projects with large client metadata.
• 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 (for example, multiple views of the same object). See also create_image_sequence() and 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 create_image_group() and 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_nifti

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

Uploads a NIfTI file to an Encord Storage Folder.

Arguments:

file_path (Union[Path, str]): Path to the local NIfTI file (e.g., ‘/home/user/data/brain_scan.nii.gz’).

title (Optional[str]): Title of the NIfTI item in Encord. If not provided, the filename is used. Must include the ‘.nii’ or ‘.nii.gz’ extension.

client_metadata (Optional[Dict[str, Any]]): Custom metadata to associate with the NIfTI file. Must be JSON-serializable.

cloud_upload_settings (CloudUploadSettings): Configuration for how the file is uploaded to the cloud. Use this to override default behavior.

Returns:

• UUID - UUID of the uploaded NIfTI item.

Raises:

• AuthorizationError - If the user lacks permission to access the target folder.
• EncordException - If the file cannot be uploaded (for example due to format or metadata issues).

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

Uploads an audio file to an Encord Storage Folder.

Arguments:

file_path (Union[Path, str]): Path to the local audio file (e.g., ‘/home/user/data/audio.mp3’).

title (Optional[str]): Title of the audio file in Encord. If not provided, the filename is used. The title must include a valid audio file extension (e.g., “encord_audio.mp3”).

client_metadata (Optional[Dict[str, Any]]): Custom metadata to associate with the audio. Must be JSON-serializable.

audio_metadata (Optional[CustomerProvidedAudioMetadata]): Optional media metadata describing the audio file. If provided, the Encord skips scanning the file to extract media metadata.

cloud_upload_settings (CloudUploadSettings): Configuration for cloud upload behavior. Override default settings using this parameter.

Returns:

• UUID - UUID of the uploaded audio item.

Raises:

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

• EncordException - If the upload fails (for example due to an unsupported audio 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.

upload_time_series

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

Upload a time-series file to an Encord storage folder.

Arguments:

• file_path - Local time-series file to upload, commonly CSV.
• title - Optional item title. Defaults to the local file name.
• client_metadata - Optional JSON-serializable metadata.
• cloud_upload_settings - Retry settings for the file upload.
• settings - Optional initial channel visualization settings.

Returns:

UUID of the newly uploaded time-series item.

upload_text

def upload_text(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    text_metadata: Optional[orm_storage.CustomerProvidedTextMetadata] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Upload a text file to a Folder in Encord storage.

Arguments:

• file_path - File path of the text file. For example: ‘/home/user/data/report.txt’
• title - The item title. If unspecified, the file name is used as the title.
• client_metadata - Optional custom metadata to be associated with the text file. Should be a dictionary that is JSON-serializable.
• text_metadata - Optional media metadata for a text file. The Encord platform uses the specified values instead of scanning the files.
• cloud_upload_settings - Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

UUID of the newly created text 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.

  text_metadata

  text_metadata for text files. The Encord platform uses the specified values instead of scanning the files.

  • file_size: int - Size of the text file in bytes.
  • mime_type: str - MIME type of the text file (for example: application/json or text/plain).

upload_pdf

def upload_pdf(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    pdf_metadata: Optional[orm_storage.CustomerProvidedPdfMetadata] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID

Upload a PDF file to a Folder in Encord storage.

Arguments:

• file_path - File path of the PDF file. For example: ‘/home/user/data/report.pdf’
• title - The item title. If unspecified, the file name is used as the title.
• client_metadata - Optional custom metadata to be associated with the PDF file. Should be a dictionary that is JSON-serializable.
• pdf_metadata - Optional media metadata for a PDF file. The Encord platform uses the specified values instead of scanning the files.
• cloud_upload_settings - Settings for uploading data into the cloud. Change this object to overwrite the default values.

Returns:

UUID of the newly created PDF item.

Raises:

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

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

  pdf_metadata

  pdf_metadata for PDF files. The Encord platform uses the specified values instead of scanning the files.

  • file_size: int - Size of the PDF file in bytes.
  • num_pages: int - Number of pages in the PDF file.

upload_scene_file

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

Upload a self-contained scene file to Encord-managed storage.

Supported formats include BAG, DB3, E57, LAS, LAZ, MCAP, PCD, and PLY.

Arguments:

• file_path - Path to the local scene file.
• title - Optional item title. Defaults to the local file name.
• client_metadata - Optional JSON-serializable metadata to associate with the scene.
• cloud_upload_settings - Retry settings for the file upload.

Returns:

UUID of the newly uploaded scene item.

Raises:

• EncordException - If the scene format is unsupported or the upload cannot be completed.

upload_scene

def upload_scene(scene: SceneBuilder,
                 title: str,
                 integration_id: str,
                 client_metadata: Optional[Dict[str, Any]] = None) -> UUID

Upload a scene to a folder in Encord storage.

Arguments:

• scene - Scene builder containing the streams and events to upload.
• title - The scene item title.
• integration_id - UUID of the cloud storage integration that can access the scene asset URIs.
• client_metadata - Optional custom metadata to associate with the scene item.

Returns:

UUID of the newly created scene item.

Raises:

• EncordException - If the scene could not be registered.

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 DataUploadItems object.
• ignore_errors bool - If True, errors will be ignored during the upload process.

Returns:

• UUID - The UUID of the upload job.

sync_private_data_with_cloud_synced_folder_start

def sync_private_data_with_cloud_synced_folder_start() -> UUID

Start 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.

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
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)

Returns:

• UUID - The unique identifier for the sync job that can be used with sync_private_data_with_cloud_synced_folder_get_result to poll for results.

Raises:

• InvalidArgumentsError - If the folder is not a cloud-synced folder, or if there are permission issues with the cloud storage bucket.

Notes:

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.

sync_private_data_with_cloud_synced_folder_get_result

def sync_private_data_with_cloud_synced_folder_get_result(
    sync_job_uuid: UUID,
    timeout_seconds: int = 7 * 24 * 60 * 60
) -> orm_storage.SyncPrivateDataWithCloudSyncedFolderGetResultResponse

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 wait for job completion without constantly making API requests. The method returns once the job completes or the timeout is reached.

Arguments:

• sync_job_uuid UUID - The UUID of the synchronization job to poll for results.
• timeout_seconds int - Maximum time in seconds to wait for the job to complete. Default is 7 days (604800 seconds).

Returns:

• SyncPrivateDataWithCloudSyncedFolderGetResultResponse - An object containing the results of the synchronization job.

Raises:

• InvalidArgumentsError - If the synchronization job UUID does not exist or is not associated with this folder.

Notes:

This method will log progress information as it polls for results. For very large buckets, the synchronization process can take a significant amount of time.

get_folder_config

def get_folder_config() -> orm_storage.StorageFolderConfig

Get the configuration of this storage folder.

Exposes the optional cloud-synced-folder metadata ingestion configuration (metadata_ingestion), which is None unless metadata ingestion has been enabled on the folder.

Returns:

• StorageFolderConfig - The current configuration of the folder.

See Also:

StorageFolderConfig for the exact set of information provided.

enable_metadata_ingestion

def enable_metadata_ingestion(matcher: Optional[
    orm_storage.SidecarMatcherSuffix] = None,
                              *,
                              paused: bool = False) -> None

Enable metadata sidecar ingestion on this cloud-synced folder.

Reads the current folder config, sets metadata_ingestion and writes it back. Any configuration the SDK does not model is preserved.

Arguments:

• matcher Optional[SidecarMatcherSuffix] - How to identify metadata sidecar files. Defaults to a .metadata.json suffix matcher.
• paused bool - When True, matched files are claimed as sidecars but not attached to data files. Defaults to False.

Notes:

Requires the API key’s user to have the folder-admin role.

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,
                    organisation_tags_allof: Optional[Union[
                        List[str], List[OrganisationTag]]] = 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.
• organisation_tags_allof Optional[Union[List[str], List[OrganisationTag]]] - Optional organisation-tag filter; matches only folders tagged with all of the given tags. Accepts either tag name strings or OrganisationTag instances (as returned by list_organisation_tags()). Tag names are matched exactly and are case-sensitive. The whole filter is a conjunction, so every name must resolve: if any string name is unknown, no folders are listed and a ResourceNotFoundError naming every unknown tag is raised before the folders are listed.
• order FoldersSortBy - Sort order for the folders. See 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 StorageFolder objects.

Raises:

• ResourceNotFoundError - One or more organisation_tags_allof names do not match any organization tag. The error lists every unknown name.

find_subfolders

def find_subfolders(search: Optional[str] = None,
                    dataset_synced: Optional[bool] = None,
                    organisation_tags_allof: Optional[Union[
                        List[str], List[OrganisationTag]]] = 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.
• organisation_tags_allof Optional[Union[List[str], List[OrganisationTag]]] - Optional organisation-tag filter; matches only folders tagged with all of the given tags. Accepts either tag name strings or OrganisationTag instances (as returned by list_organisation_tags()). Tag names are matched exactly and are case-sensitive. The whole filter is a conjunction, so every name must resolve: if any string name is unknown, no folders are listed and a ResourceNotFoundError naming every unknown tag is raised before the folders are listed.
• order FoldersSortBy - Sort order for the folders. See 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 StorageFolder objects.

Raises:

• ResourceNotFoundError - One or more organisation_tags_allof names do not match any organization tag. The error lists every unknown name.

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 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 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.

Warning: This method is slow. We recommend using storage_folder.list_items instead.

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:

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. Parameters that are not provided are not 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 Bundle to use for the operation. If provided, the operation is 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

create_data_group

def create_data_group(params: Union[DataGroupInput, List[UUID]]) -> UUID

Creates a data group storage item in this folder.

You need Admin access to this folder, and the folder can’t be a cloud-synced folder. You can’t change a data group’s items, layout or settings after you create it. To make a change, create a new data group.

Arguments:

• params - Parameters for the data group. Can be:
  • DataGroupInput (DataGroupGrid, DataGroupCarousel, DataGroupCustom): Layout with optional client_metadata
  • List[UUID]: List of item UUIDs (creates a carousel layout)

Returns:

• UUID - The UUID of the data group storage item.

create_data_groups

def create_data_groups(
        params: List[Union[DataGroupInput, List[UUID]]]) -> List[UUID]

Creates multiple data group storage items in this folder.

You need Admin access to this folder, and the folder can’t be a cloud-synced folder. All the data groups are created in one request, up to 1,500 per call. If any data group is invalid, none of them are created. You can’t change a data group’s items, layout or settings after you create it.

Arguments:

• params - List of parameters for each data group. Each item can be:
  • DataGroupInput (DataGroupGrid, DataGroupCarousel, DataGroupCustom): Layout with optional client_metadata
  • List[UUID]: List of item UUIDs (creates a carousel layout)

Returns:

• List[UUID] - List of UUIDs of the created data group storage items

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

add_data_to_folder_job_cancel

def add_data_to_folder_job_cancel(
        upload_job_id: UUID) -> orm_storage.AddDataToFolderJobCancelResponse

Cancels a data upload in progress job, associated with this folder.

Arguments:

• upload_job_id UUID - The unique identifier for the upload job.

Returns:

• AddDataToFolderJobCancelResponse - A response indicating the result of the canceled job.

StorageItemInaccessible Objects

class StorageItemInaccessible()

uuid

@property
def uuid() -> UUID

UUID: The unique identifier of the storage item.

ClientMetadataPatchJobs Objects

@dataclass(frozen=True)
class ClientMetadataPatchJobs()

The background jobs applying a set of client metadata patches.

item_uuids_by_job_uuid

The items each job patches; check a job with get_client_metadata_patch_job().

ClientMetadataPatchJobsByUrl Objects

@dataclass(frozen=True)
class ClientMetadataPatchJobsByUrl(ClientMetadataPatchJobs)

The background jobs applying client metadata patches by object URL, and the items found for each URL.

item_uuids_by_url

The items found for each object URL; empty for a URL that matches no item.

ClientMetadataPatchByUrlResult Objects

@dataclass(frozen=True)
class ClientMetadataPatchByUrlResult()

The items found for each object URL, and the patches that could not be confirmed as applied to them.

item_uuids_by_url

The items found for each object URL; empty for a URL that matches no item.

failures

The patches that could not be confirmed as applied, with the reason where available.

StorageItem Objects

class StorageItem()

uuid

@property
def uuid() -> UUID

UUID: The unique identifier of the storage item.

parent_folder_uuid

@property
def parent_folder_uuid() -> UUID

UUID: The UUID of the parent folder.

parent_folder

def parent_folder() -> StorageFolder

Retrieve the parent folder of the storage item.

Returns:

• StorageFolder - The parent folder.

item_type

@property
def item_type() -> StorageItemType

StorageItemType: The type of the storage item.

name

@property
def name() -> str

str: The name of the storage item.

description

@property
@deprecated(version="0.1.177")
def description() -> str

str: This is always an empty string; descriptions on individual items are not supported.

client_metadata

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

Optional[Dict[str, Any]]: The client metadata of the storage item.

timeseries_settings

@property
def timeseries_settings() -> Optional[TimeSeriesViewSettings]

Optional persisted visualization settings for a time-series item.

created_at

@property
def created_at() -> datetime

datetime: The creation time of the storage item.

last_edited_at

@property
def last_edited_at() -> datetime

datetime: The last edited time of the storage item.

backed_data_units_count

@property
def backed_data_units_count() -> int

int: The number of backed data units.

storage_location

@property
def storage_location() -> StorageLocationName

StorageLocationName: The storage location name.

integration_hash

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

Optional[UUID]: The integration hash.

url

@property
def url() -> Optional[str]

Optional[str]: The URL of the storage item.

file_size

@property
def file_size() -> Optional[int]

Optional[int]: The file size of the storage item.

mime_type

@property
def mime_type() -> Optional[str]

Optional[str]: The MIME type of the storage item.

duration

@property
def duration() -> Optional[float]

Optional[float]: The duration of the storage item.

fps

@property
def fps() -> Optional[float]

Optional[float]: The frames per second of the storage item.

height

@property
def height() -> Optional[int]

Optional[int]: The height of the storage item.

width

@property
def width() -> Optional[int]

Optional[int]: The width of the storage item.

dicom_instance_uid

@property
def dicom_instance_uid() -> Optional[str]

Optional[str]: The DICOM instance UID of the storage item.

dicom_study_uid

@property
def dicom_study_uid() -> Optional[str]

Optional[str]: The DICOM study UID of the storage item.

dicom_series_uid

@property
def dicom_series_uid() -> Optional[str]

Optional[str]: The DICOM series UID of the storage item.

frame_count

@property
def frame_count() -> Optional[int]

Optional[int]: The frame count of the storage item.

audio_sample_rate

@property
def audio_sample_rate() -> Optional[int]

Optional[int]: The number of samples taken per second (in Hz).

audio_bit_depth

@property
def audio_bit_depth() -> Optional[int]

Optional[int]: The number of bits used to record each audio sample.

audio_codec

@property
def audio_codec() -> Optional[str]

Optional[int]: The codec of the audio file (e.g., mp3 or flac).

audio_num_channels

@property
def audio_num_channels() -> Optional[int]

Optional[int]: The number of channels.

get_signed_url

def get_signed_url(refetch: bool = False) -> Optional[str]

Get a signed URL for downloading the item.

Returns None for composite items that have no single file URL:

• For scenes, use SceneReader to get signed URLs for all constituent files.
• For image groups and DICOM series, use get_child_items() to get signed URLs for individual frames.

Arguments:

• refetch - If True, forces fetching a new signed URL even if one is cached.

Returns:

• Optional[str] - Signed URL for downloading the item, or None for composite items.

get_summary

def get_summary() -> StorageItemSummary

Retrieve a summary of the item, including linked datasets and other information.

Returns:

• StorageItemSummary - Object containing summary information about the item.

get_child_items

def get_child_items(get_signed_urls: bool = False) -> Iterable["StorageItem"]

Get child items of the item, such as frames of an image group or files of DICOM series.

Arguments:

• get_signed_urls - If True, include signed URLs for child items.

Returns:

• Iterable[StorageItem] - List of child items accessible to the user.

update

def update(
    name: Optional[str] = None,
    description: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    timeseries_settings: Union[TimeSeriesViewSettings, None,
                               _NotProvided] = _NOT_PROVIDED,
    bundle: Optional[Bundle] = None,
    scene_view_settings: Union[SceneViewSettings, None,
                               _NotProvided] = _NOT_PROVIDED,
    scene_layout: Union[SceneLayout, None,
                        _NotProvided] = _NOT_PROVIDED) -> None

Update modifiable properties of the item.

Arguments:

• name - New item name.
• description - New item description.
• client_metadata - New client metadata.
• timeseries_settings - New time-series channel visualization settings. Pass None to restore defaults; omit to leave the existing settings unchanged.
• bundle - Optional Bundle to use for the operation. If provided, the operation
• scene_view_settings - New scene visualization settings. Pass None to restore defaults; omit to leave the existing settings unchanged.
• scene_layout - New scene tile and timeline layout. Pass None to remove the layout; omit to leave the existing layout unchanged.

Returns:

None

Notes:

If no parameters are provided, the function does nothing.

If bundle is provided, the operation is bundled into a single server call with other item updates using the same bundle.

patch_client_metadata

def patch_client_metadata(patch: Dict[str, Any]) -> None

Change some of the item’s client metadata keys, leaving all other keys as they are.

patch is applied as an RFC 7396 JSON merge patch:

• A key with a value adds the key, or replaces its current value.
• A key with None removes the key.
• A dict value is merged into the current dict value by the same rules.
• Any other value, including a list, replaces the current value as a whole.

Keys not included in patch are left unchanged. After the call, client_metadata holds the merged metadata; a patch refused with one of the errors below changes nothing. To replace the whole client metadata, use update() instead.

For example, the patch below sets reviewed, sets camera.fps while keeping the other camera keys, and removes draft.

Example:

item.patch_client_metadata({"reviewed": True, "camera": {"fps": 60}, "draft": None})

Arguments:

• patch - The keys to add, change or remove.

Returns:

None

Raises:

• AuthorisationError - The item does not exist or you cannot edit it.
• InvalidArgumentsError - The patch can’t be applied, for example because the item is in a cloud synced folder or the merged metadata would be too large.
• ResourceExistsError - Other changes to the item’s client metadata kept conflicting with the patch (retry), or its current client metadata can’t be read (replace it with update()).

delete

def delete(remove_unused_frames=True) -> None

Delete the item from the storage.

Arguments:

• remove_unused_frames - If True (default), remove individual images or DICOM files not used elsewhere.

Returns:

None

move_to_folder

def move_to_folder(target_folder: Union[StorageFolder, UUID],
                   allow_mirror_dataset_changes: bool = False) -> None

Move the item to another folder.

Arguments:

• target_folder - Target folder to move the item to. Can be a StorageFolder object or a UUID.
• allow_mirror_dataset_changes - If True, allows moving items linked to a mirror dataset. Default is False, which prohibits such moves to prevent data loss.

Returns:

None

Notes:

This method updates the item’s parent folder and refetches item data after the move.

refetch_data

def refetch_data(get_signed_url: bool = False) -> None

Refetches data for the item, updating its attributes.

Arguments:

• get_signed_url - If True, refetches the signed URL for downloading the item.

Returns:

None