Edit and delete files and folders

Update folder properties

Use the following script to update the name and description of an existing folder in Files. Ensure that you:

  • Replace <private_key_path> with the path to your private key.
  • Replace Cat Videos with the name of the folder you want to update properties for.
  • Replace Cat videos and images with the new name you want to give the folder.
  • Replace Images and videos of cats with the description you want to give the folder.

👍

Tip

Use the list_storage_folders and find_storage_folders methods to search for specific folders.

from encord import EncordUserClient
from encord.orm.storage import FoldersSortBy

# Instantiate Encord client using your SSH private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Define search parameters
folder_name_to_find = "Cat Videos"
search_result = user_client.find_storage_folders(
    search=folder_name_to_find,
    dataset_synced=None,
    order=FoldersSortBy.NAME,
    desc=False,
    page_size=1
)

# Fetch the folder assuming it's the first one in the search result
folder = next(search_result, None)
if folder is None:
    print(f"No folder found with name {folder_name_to_find}")
else:
    # Define new properties for the folder
    new_name = "Cat videos and images"
    new_description = "Images and videos of cats"

    # Update the folder properties
    folder.update(name=new_name, description=new_description)
    print(f"Folder '{folder_name_to_find}' updated to new name '{new_name}' and description '{new_description}'")

Move folders

You can move folders between different parent folders in Files, including moving them to the root (no parent). The following script demonstrates how a folder with the name Folder Name 3 is moved between 2 different target folders. The script must be modified to suit your needs.

Ensure that you:

  • Replace <private_key_path> with the path to your private key.
  • Replace Folder Name 1 with the name of a target folder.
  • Replace Folder Name 2 with the new name of another target folder.
  • Replace Folder Name 3 with the name of the folder that is moved.
from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>"
            )

# Search for folders by name using the find_storage_folders function
folder_1 = next(user_client.find_storage_folders(search="Folder Name 1", dataset_synced=False, order=FoldersSortBy.NAME, desc=False, page_size=1))
folder_2 = next(user_client.find_storage_folders(search="Folder Name 2", dataset_synced=False, order=FoldersSortBy.NAME, desc=False, page_size=1))
folder_3 = next(user_client.find_storage_folders(search="Folder Name 3", dataset_synced=False, order=FoldersSortBy.NAME, desc=False, page_size=1))

# Move folder_3 under folder_1
folder_3.move_to_folder(folder_1.uuid)

# Move folder_3 under folder_2
folder_3.move_to_folder(folder_2.uuid)

# Move folder_3 to root folder (passing None moves it to the root level)
folder_3.move_to_folder(None)

Delete folders

Use the following script to delete a specific folder from Files. Ensure that you:

  • Replace <private_key_path> with the path to your private key.
  • Replace Specific Folder Name with the name of the folder you want to delete.
from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>"
            )

# Define the search criteria for the folder
folder_search_criteria = "Specific Folder Name"

# Retrieve the target folder
try:
    folder_to_delete = next(user_client.find_storage_folders(search=folder_search_criteria, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1))
    print(f"Deleting folder {folder_to_delete.uuid}")

    # Delete the folder and verify it cannot be accessed anymore
    folder_to_delete.delete()
    print("Folder deleted successfully.")

    try:
        # Try to refetch the folder to verify it's been deleted
        user_client.get_storage_folder(folder_to_delete.uuid)
        print("Error: Folder still accessible after deletion.")
    except Exception as e:
        print(f"Verification successful: {str(e)}")

except StopIteration:
    print("No folder found with the specified criteria.")

Move files

Use the following script to move various types of files to a different folder in Files. Ensure that you:

  • Replace <private_key_path> with the path to your private key.
  • Replace File Name with the name of the file you want to move to a new folder.
  • Replace Target Folder Name with the name of the folder you want to move the file to.
from encord import EncordUserClient
from encord.storage import StorageItemType, FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>"
            )

# Define the search criteria for the data unit and target folder
item_search_criteria = "File Name"  # Change this to match the data unit's name
folder_search_criteria = "Target Folder Name"  # Change this to match the target folder's name

# Retrieve the target folder by its name (assuming only one match)
target_folder = next(user_client.find_storage_folders(search=folder_search_criteria, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1))

# Search for the specific data unit using its name, assuming it will only return one result
item = next(user_client.find_storage_items(
    search=item_search_criteria,
    is_in_dataset=None,  
    item_types=[StorageItemType.IMAGE],
    order=FoldersSortBy.NAME,
    desc=False,
    get_signed_urls=False,
    page_size=1  # Expecting only one data unit
))

# Move the found data unit to the retrieved target folder
print(f"Moving item {item.uuid} to folder {target_folder.uuid}")
item.move_to_folder(target_folder.uuid)
from encord import EncordUserClient
from encord.storage import StorageItemType, FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>"
            )

# Define the search criteria for the video data unit and target folder
video_search_criteria = "File Name"
folder_search_criteria = "Target Folder Name"

# Retrieve the target folder
target_folder = next(user_client.find_storage_folders(search=folder_search_criteria, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1))

# Search and retrieve the video data unit
video_item = next(user_client.find_storage_items(
    search=video_search_criteria,
    is_in_dataset=None,
    item_types=[StorageItemType.VIDEO],
    order=FoldersSortBy.NAME,
    desc=False,
    get_signed_urls=False,
    page_size=1
))

# Move the video
print(f"Moving video {video_item.uuid} to folder {target_folder.uuid}")
video_item.move_to_folder(target_folder.uuid)
from encord import EncordUserClient
from encord.storage import StorageItemType, FoldersSortBy

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>"
            )

# Search criteria
image_group_search_criteria = "File Name"
folder_search_criteria = "Target Folder Name"

# Retrieve the folder
target_folder = next(user_client.find_storage_folders(search=folder_search_criteria, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1))

# Retrieve the image group
image_group = next(user_client.find_storage_items(
    search=image_group_search_criteria,
    is_in_dataset=None,
    item_types=[StorageItemType.IMAGE_GROUP],
    order=FoldersSortBy.NAME,
    desc=False,
    get_signed_urls=False,
    page_size=1
))

# Move the image group
print(f"Moving image group {image_group.uuid} to folder {target_folder.uuid}")
image_group.move_to_folder(target_folder.uuid)
from encord import EncordUserClient
from encord.storage import StorageItemType, FoldersSortBy

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>"
            )

# Search criteria
image_sequence_search_criteria = "File Name"
folder_search_criteria = "Target Folder Name"

# Retrieve the folder
target_folder = next(user_client.find_storage_folders(search=folder_search_criteria, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1))

# Retrieve the image sequence
image_sequence = next(user_client.find_storage_items(
    search=image_sequence_search_criteria,
    is_in_dataset=None,
    item_types=[StorageItemType.IMAGE_SEQUENCE],
    order=FoldersSortBy.NAME,
    desc=False,
    get_signed_urls=False,
    page_size=1
))

# Move the image sequence
print(f"Moving image sequence {image_sequence.uuid} to folder {target_folder.uuid}")
image_sequence.move_to_folder(target_folder.uuid)
from encord import EncordUserClient
from encord.storage import StorageItemType, FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>"
            )

# Define the search criteria for the DICOM series and the target folder
dicom_series_search_criteria = "File Name"
folder_search_criteria = "Target Folder Name"

# Retrieve the target folder
target_folder = next(user_client.find_storage_folders(search=folder_search_criteria, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1))

# Search and retrieve the DICOM series
dicom_series = next(user_client.find_storage_items(
    search=dicom_series_search_criteria,
    is_in_dataset=None,
    item_types=[StorageItemType.DICOM_SERIES],
    order=FoldersSortBy.NAME,
    desc=False,
    get_signed_urls=False,
    page_size=1
))

# Move the DICOM series
print(f"Moving DICOM series {dicom_series.uuid} to folder {target_folder.uuid}")
dicom_series.move_to_folder(target_folder.uuid)

Delete files

Use the following scripts to delete different types of files from Files. Ensure that you:

  • Replace <private_key_path> with the path to your private key.
  • Replace File Name with the name of the file you want to move to a new folder.
  • Replace Parent Folder with the name of the folder containing the file you want to delete.
from encord import EncordUserClient
from encord.storage import StorageItemType, FoldersSortBy

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>")

# Find the image by name
image_name = "File Name"
# Define the search criteria for the folder
folder_search_criteria = "Parent Folder"

# Retrieve the target folder
try:
    folder = next(user_client.find_storage_folders(search=folder_search_criteria, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1))

    images = list(user_client.find_storage_items(search=image_name, item_types=[StorageItemType.IMAGE], order=FoldersSortBy.NAME, desc=False, page_size=1))

    if images:
        # Delete the image
        folder.delete_storage_items(item_uuids=[images[0].uuid], remove_unused_frames=True)
        print("Image deleted successfully.")
    else:
        print("No image found with the specified name.")

except StopIteration:
    print("No folder found with the specified criteria.")
from encord import EncordUserClient
from encord.storage import StorageItemType, FoldersSortBy

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>")

# Find the video by name
video_name = "File Name"
# Define the search criteria for the folder
folder_search_criteria = "Parent Folder"

# Retrieve the target folder
try:
    folder = next(user_client.find_storage_folders(search=folder_search_criteria, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1))

    videos = list(user_client.find_storage_items(search=video_name, item_types=[StorageItemType.VIDEO], order=FoldersSortBy.NAME, desc=False, page_size=1))

    if videos:
        # Delete the video
        folder.delete_storage_items(item_uuids=[videos[0].uuid], remove_unused_frames=True)
        print("Video deleted successfully.")
    else:
        print("No video found with the specified name.")

except StopIteration:
    print("No folder found with the specified criteria.")
from encord import EncordUserClient
from encord.storage import StorageItemType, FoldersSortBy

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>")

# Find the image group by name
image_group_name = "File Name"
# Define the search criteria for the folder
folder_search_criteria = "Parent Folder"

# Retrieve the target folder
try:
    folder = next(user_client.find_storage_folders(search=folder_search_criteria, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1))

    image_groups = list(user_client.find_storage_items(search=image_group_name, item_types=[StorageItemType.IMAGE_GROUP], order=FoldersSortBy.NAME, desc=False, page_size=1))

    if image_groups:
        # Delete the image group
        folder.delete_storage_items(item_uuids=[image_groups[0].uuid], remove_unused_frames=True)
        print("Image group deleted successfully.")
    else:
        print("No image group found with the specified name.")

except StopIteration:
    print("No folder found with the specified criteria.")
from encord import EncordUserClient
from encord.storage import StorageItemType, FoldersSortBy

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>")

# Find the image sequence by name
image_sequence_name = "File Name"
# Define the search criteria for the folder
folder_search_criteria = "Parent Folder"

# Retrieve the target folder
try:
    folder = next(user_client.find_storage_folders(search=folder_search_criteria, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1))

    image_sequences = list(user_client.find_storage_items(search=image_sequence_name, item_types=[StorageItemType.IMAGE_SEQUENCE], order=FoldersSortBy.NAME, desc=False, page_size=1))

    if image_sequences:
        # Delete the image sequence
        folder.delete_storage_items(item_uuids=[image_sequences[0].uuid], remove_unused_frames=True)
        print("Image sequence deleted successfully.")
    else:
        print("No image sequence found with the specified name.")

except StopIteration:
    print("No folder found with the specified criteria.")
from encord import EncordUserClient
from encord.storage import StorageItemType, FoldersSortBy

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="<private_key_path>")

# Find the DICOM series by name
dicom_series_name = "File Name"
# Define the search criteria for the folder
folder_search_criteria = "Parent Folder"

# Retrieve the target folder
try:
    folder = next(user_client.find_storage_folders(search=folder_search_criteria, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1))

    dicom_series = list(user_client.find_storage_items(search=dicom_series_name, item_types=[StorageItemType.DICOM_SERIES], order=FoldersSortBy.NAME, desc=False, page_size=1))

    if dicom_series:
        # Delete the DICOM series
        folder.delete_storage_items(item_uuids=[dicom_series[0].uuid], remove_unused_frames=True)
        print("DICOM series deleted successfully.")
    else:
        print("No DICOM series found with the specified name.")

except StopIteration:
    print("No folder found with the specified criteria.")