StorageFolder Objects
uuid
UUID
- The UUID of the folder.
parent_uuid
Optional[UUID]
- The UUID of the parent folder, or None if there is no parent.
parent
Optional[StorageFolder]
- The parent StorageFolder object, or None if there is no parent.
name
str
- The name of the folder.
description
str
- The description of the folder.
client_metadata
path_to_root
List[PathElement]
- A list of PathElement objects representing the path to the root.
list_items
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
andFalse
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.
Iterable[StorageItem]
- Iterable of items in the folder.
delete
upload_image
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.
UUID
- The UUID of the newly created image item.
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
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.
UUID
- The UUID of the newly created video item.
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
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.
UUID
- The UUID of the re-encoding process.
get_re_encoding_status
process_hash
UUID - The UUID of the re-encoding process.
ReencodeVideoItemsResponse
- Response object containing the status of the re-encoding process.
create_dicom_series
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.
UUID
- The UUID of the newly created DICOM series item.
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
.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.
UUID
- The UUID of the newly created image group item.
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
.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.
UUID
- The UUID of the newly created image sequence item.
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
UUID
- UUID of the uploaded NIfTI item.
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
UUID
- UUID of the uploaded audio item.
-
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
oraudio/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_text
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.
-
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
ortext/plain
).
upload_pdf
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.
-
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.
add_private_data_to_folder_start
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.
UUID
- The UUID of the upload job.
sync_private_data_with_cloud_synced_folder_start
- Scans the cloud bucket for files
- Creates new storage items for files that exist in the bucket but not in the folder
- Updates the tombstone status of items (marks as tombstone if deleted from bucket, restores if re-added)
- Updates items if they have the same path but different content (different checksum)
UUID
- The unique identifier for the sync job that can be used withsync_private_data_with_cloud_synced_folder_get_result
to poll for results.
InvalidArgumentsError
- If the folder is not a cloud-synced folder, or if there are permission issues with the cloud storage bucket.
sync_private_data_with_cloud_synced_folder_get_result
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).
SyncPrivateDataWithCloudSyncedFolderGetResultResponse
- An object containing the results of the synchronization job.
InvalidArgumentsError
- If the synchronization job UUID does not exist or is not associated with this folder.
add_private_data_to_folder_get_result
upload_job_id
UUID - The UUID of the upload job.timeout_seconds
int - The timeout in seconds for the upload job.
UploadLongPollingState
- The state of the upload job.
list_subfolders
search
Optional[str] - Search string to filter folders by name.dataset_synced
Optional[bool] - Include or exclude folders that are mirrored by a dataset. IfNone
, 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.
Iterable[StorageFolder]
- An iterable of :class:encord.StorageFolder
objects.
find_subfolders
search
Optional[str] - Search string to filter folders by name.dataset_synced
Optional[bool] - Include or exclude folders that are mirrored by a dataset. IfNone
, 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.
Iterable[StorageFolder]
- An iterable of :class:encord.StorageFolder
objects.
create_subfolder
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.
encord.storage.StorageFolder
for details.
find_items
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
andFalse
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.
Iterable[StorageItem]
- An iterable of items in the folder and its subfolders.
ValueError
- If neithersearch
noritem_types
are provided.
get_summary
StorageFolderSummary
- A summary of the folder.
encord.StorageFolderSummary
for the exact set of information provided.
update
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.
move_to_folder
target_folder
is None.
Arguments:
target_folder
Optional[Union[StorageFolder, UUID]] - The target folder to move to, orNone
to move to the root level.
create_data_group
params
Union[DataGroupInput, List[UUID]] - Parameters for the data group. When a list of UUIDs is provided, the group will be created with a grid layout. For custom layouts, use DataGroupGrid, DataGroupList or DataGroupCustom.
UUID
- The UUID of the data group storage item.
move_items_to_folder
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 - IfTrue
, 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.
delete_storage_items
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 - IfTrue
(default), remove individual images or DICOM files from image groups or DICOM series that are not used in any other item.
list_groups
add_group
group_hash
- Group hash, or a list of group hashes to be added.user_role
- User role that the group will be given.
remove_group
group_hash
- Group hash, or a list of group hashes to be removed.
refetch_data
add_data_to_folder_job_cancel
upload_job_id
UUID - The unique identifier for the upload job.
AddDataToFolderJobCancelResponse
- A response indicating the result of the cancelled job.