FileApi¶

class FileApi[source]¶

Bases: supervisely.api.module_api.ModuleApiBase

API for working with Files. FileApi object is immutable.

Parameters

api : Api: API connection to the server.

Usage example

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))
api = sly.Api.from_env()

# Pass values into the API constructor (optional, not recommended)
# api = sly.Api(server_address="https://app.supervise.ly", token="4r47N...xaTatb")

team_id = 8
file_path = "/999_App_Test/"
files = api.file.list(team_id, file_path)

Methods

`dir_exists`	Checks if directory exists in Team Files.
`download`	Download File from Team Files.
`download_directory`	Download Directory from Team Files.
`download_from_agent`	rtype `None`
`download_input`	Downloads data for application from input using environment variables.
`exists`	Checks if file exists in Team Files.
`get_directory_size`	Get directory size in the Team Files.
`get_free_dir_name`	Adds suffix to the end of the Directory name.
`get_free_name`	Adds suffix to the end of the file name.
`get_info_by_id`	Gets information about File by ID.
`get_info_by_path`	Gets File information by path in Team Files.
`get_list_all_pages`	Get list of all or limited quantity entities from the Supervisely server.
`get_list_all_pages_generator`	This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved
`get_url`	Gets URL for the File by ID.
`info_sequence`	NamedTuple FileInfo information about File.
`info_tuple_name`	NamedTuple name - FileInfo.
`is_on_agent`
`list`	List of files in the Team Files.
`list2`	Disclaimer: Method is not recommended.
`list_on_agent`	rtype `List`[`Union`[`Dict`, `FileInfo`]]
`listdir`	List dirs and files in the directiry with given path.
`parse_agent_id_and_path`	rtype `int`
`remove`	Removes a file from the Team Files.
`remove_batch`	Removes list of files from Team Files.
`remove_dir`	Removes folder from Team Files.
`remove_file`	Removes file from Team Files.
`remove_from_agent`	rtype `None`
`rename`	Renames file in Team Files
`upload`	Upload File to Team Files.
`upload_bulk`	Upload Files to Team Files.
`upload_directory`	Upload Directory to Team Files from local path.

Attributes

`MAX_WAIT_ATTEMPTS`	Maximum number of attempts that will be made to wait for a certain condition to be met.
`WAIT_ATTEMPT_TIMEOUT_SEC`	Number of seconds for intervals between attempts.

InfoType¶: alias of supervisely.api.module_api.FileInfo

dir_exists(team_id, remote_directory)[source]¶

Checks if directory exists in Team Files.

Parameters

team_id : int: Team ID in Supervisely.
remote_path : str: Remote path to directory in Team Files.

Returns

True if directory exists, otherwise False

Return type

bool

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

file = api.file.dir_exists(8, "/999_App_Test/")   # True
file = api.file.dir_exists(8, "/10000_App_Test/") # False

download(team_id, remote_path, local_save_path, cache=None, progress_cb=None)[source]¶

Download File from Team Files.

Parameters

team_id : int: Team ID in Supervisely.
remote_path : str: Path to File in Team Files.
local_save_path : str: Local save path.
cache : FileCache, optional: optional
progress_cb : tqdm or callable, optional: Function for tracking download progress.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

path_to_file = "/999_App_Test/ds1/01587.json"
local_save_path = "/home/admin/Downloads/01587.json"

api.file.download(8, path_to_file, local_save_path)

download_directory(team_id, remote_path, local_save_path, progress_cb=None)[source]¶

Download Directory from Team Files.

Parameters

team_id : int: Team ID in Supervisely.
remote_path : str: Path to Directory in Team Files.
local_save_path : str: Local save path.
progress_cb : tqdm or callable, optional: Function for tracking download progress.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

path_to_dir = "/My_App_Test/ds1"
local_save_path = "/home/admin/Downloads/My_local_test"

api.file.download_directory(9, path_to_dir, local_save_path)

download_input(save_path, unpack_if_archive=True, remove_archive=True, force=False, log_progress=False)[source]¶

Downloads data for application from input using environment variables. Automatically detects is data is a file or a directory and saves it to the specified directory. If data is an archive, it will be unpacked to the specified directory if unpack_if_archive is True.

Parameters

save_path : str: path to a directory where data will be saved
unpack_if_archive : Optional[bool]: if True, archive will be unpacked to the specified directory
remove_archive : Optional[bool]: if True, archive will be removed after unpacking
force : Optional[bool]: if True, data will be downloaded even if it already exists in the specified directory
log_progress : Optional[bool]: if True, progress bar will be displayed

Raises

RuntimeError – if both file and folder paths not found in environment variables
RuntimeError – if both file and folder paths found in environment variables (debug)
RuntimeError – if team id not found in environment variables

Usage example

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
load_dotenv(os.path.expanduser("~/supervisely.env"))
api = sly.Api.from_env()

# Application is started...
save_path = "/my_app_data"
api.file.download_input(save_path)

# The data is downloaded to the specified directory.

Return type

None

exists(team_id, remote_path)[source]¶

Checks if file exists in Team Files.

Parameters

team_id : int: Team ID in Supervisely.
remote_path : str: Remote path to File in Team Files.

Returns

True if file exists, otherwise False

Return type

bool

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

file = api.file.exists(8, "/999_App_Test/ds1/02163.json") # True
file = api.file.exists(8, "/999_App_Test/ds1/01587.json") # False

get_directory_size(team_id, path)[source]¶

Get directory size in the Team Files. If directory is on local agent, then optimized method will be used (without api requests)

Parameters

team_id : int: Team ID in Supervisely.
path : str: Path to Directory.

Returns

Directory size in the Team Files

Return type

int

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

team_id = 9
path = "/My_App_Test/"
size = api.file.get_directory_size(team_id, path)

print(size)
# Output: 3478687

get_free_dir_name(team_id, dir_path)[source]¶

Adds suffix to the end of the Directory name.

Parameters

team_id : int: Team ID in Supervisely.
dir_path : str: Path to Directory in Team Files.

Returns

New Directory name with suffix at the end

Return type

str

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

new_dir_name = api.file.get_free_dir_name(9, "/My_App_Test")
print(new_dir_name)
# Output: /My_App_Test_001

get_free_name(team_id, path)[source]¶

Adds suffix to the end of the file name.

Parameters

team_id : int: Team ID in Supervisely.
path : str: Remote path to file in Team Files.

Returns

New File name with suffix at the end

Return type

str

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

file = api.file.get_free_name(8, "/999_App_Test/ds1/02163.json")
print(file)
# Output: /999_App_Test/ds1/02163_000.json

get_info_by_id(id)[source]¶

Gets information about File by ID.

Parameters

id : int: File ID in Supervisely.

Returns

Information about File. See info_sequence

Return type

FileInfo

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

file_id = 7660
file_info = api.file.get_info_by_id(file_id)
print(file_info)
# Output: FileInfo(team_id=8,
#                  id=7660,
#                  user_id=7,
#                  name='00135.json',
#                  hash='z7Hv9a7WIC5HIJrfX/69KVrvtDaLqucSprWHoCxyq0M=',
#                  path='/999_App_Test/ds1/00135.json',
#                  storage_path='/h5un6l2bnaz1vj8a9qgms4-public/teams_storage/8/y/P/rn/...json',
#                  mime='application/json',
#                  ext='json',
#                  sizeb=261,
#                  created_at='2021-01-11T09:04:17.959Z',
#                  updated_at='2021-01-11T09:04:17.959Z',
#                  full_storage_url='http://supervise.ly/h5un6l2bnaz1vj8a9qgms4-public/teams_storage/8/y/P/rn/...json')

get_info_by_path(team_id, remote_path)[source]¶

Gets File information by path in Team Files.

Parameters

team_id : int: Team ID in Supervisely.
remote_path : str: Remote path to file in Team Files.

Returns

Information about File. See info_sequence

Return type

FileInfo

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

file_path = "/999_App_Test/ds1/00135.json"
file_info = api.file.get_info_by_id(8, file_path)
print(file_info)
# Output: FileInfo(team_id=8,
#                  id=7660,
#                  user_id=7,
#                  name='00135.json',
#                  hash='z7Hv9a7WIC5HIJrfX/69KVrvtDaLqucSprWHoCxyq0M=',
#                  path='/999_App_Test/ds1/00135.json',
#                  storage_path='/h5un6l2bnaz1vj8a9qgms4-public/teams_storage/8/y/P/rn/...json',
#                  mime='application/json',
#                  ext='json',
#                  sizeb=261,
#                  created_at='2021-01-11T09:04:17.959Z',
#                  updated_at='2021-01-11T09:04:17.959Z',
#                  full_storage_url='http://supervise.ly/h5un6l2bnaz1vj8a9qgms4-public/teams_storage/8/y/P/rn/...json')

get_list_all_pages(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)¶

Get list of all or limited quantity entities from the Supervisely server.

Parameters

method : str: Request method name
data : dict: Dictionary with request body info
progress_cb : Progress, optional: Function for tracking download progress.
convert_json_info_cb : Callable, optional: Function for convert json info
limit : int, optional: Number of entity to retrieve
return_first_response : bool, optional: Specify if return first response

get_list_all_pages_generator(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)¶

This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved

Parameters

method : str: Request method name
data : dict: Dictionary with request body info
progress_cb : Progress, optional: Function for tracking download progress.
convert_json_info_cb : Callable, optional: Function for convert json info
limit : int, optional: Number of entity to retrieve
return_first_response : bool, optional: Specify if return first response

get_url(file_id)[source]¶

Gets URL for the File by ID.

Parameters

file_id : int: File ID in Supervisely.

Returns

File URL

Return type

str

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

file_id = 7660
file_url = sly.api.file.get_url(file_id)
print(file_url)
# Output: http://supervise.ly/files/7660

static info_sequence()[source]¶

NamedTuple FileInfo information about File.

Example

FileInfo(team_id=8,
         id=7660,
         user_id=7,
         name='00135.json',
         hash='z7Hv9a7WIC5HIJrfX/69KVrvtDaLqucSprWHoCxyq0M=',
         path='/999_App_Test/ds1/00135.json',
         storage_path='/h5un6l2bnaz1vj8a9qgms4-public/teams_storage/8/y/P/rn/...json',
         mime='application/json',
         ext='json',
         sizeb=261,
         created_at='2021-01-11T09:04:17.959Z',
         updated_at='2021-01-11T09:04:17.959Z',
         full_storage_url='http://supervise.ly/h5un6l2bnaz1vj8a9qgms4-public/teams_storage/8/y/P/rn/...json')

static info_tuple_name()[source]¶: NamedTuple name - FileInfo.

list(team_id, path, recursive=True, return_type='dict')[source]¶

List of files in the Team Files.

Parameters

team_id : int: Team ID in Supervisely.
path : str: Path to File or Directory.
recursive : bool: If True return all files recursively.
return_type : str: The specified value between ‘dict’ or ‘fileinfo’. By default: ‘dict’.

Returns

List of all Files with information. See classes info_sequence and FileInfo

Return type

class List[Union[Dict, FileInfo]]

Usage example

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))
api = sly.Api.from_env()

# Pass values into the API constructor (optional, not recommended)
# api = sly.Api(server_address="https://app.supervise.ly", token="4r47N...xaTatb")

team_id = 8
file_path = "/999_App_Test/"

# Get information about file in dict way..
files = api.file.list(team_id, file_path)
file = files[0]
print(file['id'])
# Output: 7660

print(files)
# Output: [
#     {
#         "id":7660,
#         "userId":7,
#         "path":"/999_App_Test/ds1/00135.json",
#         "storagePath":"/h5un6l2bnaz1vj8a9qgms4-public/teams_storage/8/y/P/rn/...json",
#         "meta":{
#             "ext":"json",
#             "mime":"application/json",
#             "size":261
#         },
#         "createdAt":"2021-01-11T09:04:17.959Z",
#         "updatedAt":"2021-01-11T09:04:17.959Z",
#         "hash":"z7Wv1a7WIC5HIJrfX/69XXrqtDaLxucSprWHoCxyq0M=",
#         "fullStorageUrl":"http://supervise.ly/h5un6l2bnaz1vj8a9qgms4-public/teams_storage/8/y/P/rn/...json",
#         "teamId":8,
#         "name":"00135.json"
#     },
#     {
#         "id":7661,
#         "userId":7,
#         "path":"/999_App_Test/ds1/01587.json",
#         "storagePath":"/h5un6l2bnaz1vj8a9qgms4-public/teams_storage/8/9/k/Hs/...json",
#         "meta":{
#             "ext":"json",
#             "mime":"application/json",
#             "size":252
#         },
#         "createdAt":"2021-01-11T09:04:18.099Z",
#         "updatedAt":"2021-01-11T09:04:18.099Z",
#         "hash":"La9+XtF2+cTlAqUE/I72e/xS12LqyH1+z<3T+SgD4CTU=",
#         "fullStorageUrl":"http://supervise.ly/h5un6l2bnaz1vj8a9qgms4-public/teams_storage/8/9/k/Hs/...json",
#         "teamId":8,
#         "name":"01587.json"
#     }
# ]

# ..or as FileInfo with attributes:
files = api.file.list(team_id, file_path, return_type='fileinfo')
file = files[0]
print(file.id)
# Output: 7660

print(files)
# Output: [
# FileInfo(team_id=8, id=7660, user_id=7, name='00135.json', hash='z7Wv1a7WI...
# FileInfo(team_id=8, id=7661, user_id=7, name='01587.json', hash='La9+XtF2+...
# ]

list2(team_id, path, recursive=True)[source]¶

Disclaimer: Method is not recommended. Use api.file.list instead

List of files in the Team Files.

Parameters

team_id : int: Team ID in Supervisely.
path : str: Path to File or Directory.
recursive : bool: If True return all FileInfos recursively.

Returns

List of all Files with information. See class info_sequence

Return type

class List[FileInfo]

Usage example

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))
api = sly.Api.from_env()

# Pass values into the API constructor (optional, not recommended)
# api = sly.Api(server_address="https://app.supervise.ly", token="4r47N...xaTatb")

team_id = 9
file_path = "/My_App_Test/"
files = api.file.list2(team_id, file_path)

print(files)
# Output: [
# FileInfo(team_id=9, id=18421, user_id=8, name='5071_3734_mot_video_002.tar.gz', hash='+0nrNoDjBxxJA...
# FileInfo(team_id=9, id=18456, user_id=8, name='5164_4218_mot_video_bitmap.tar.gz', hash='fwtVI+iptY...
# FileInfo(team_id=9, id=18453, user_id=8, name='all_vars.tar', hash='TVkUE+K1bnEb9QrdEm9akmHm/QEWPJK...
# ]

listdir(team_id, path, recursive=False)[source]¶

List dirs and files in the directiry with given path.

Parameters

team_id : int: Team ID in Supervisely.
path : str: Path to directory.
recursive : bool: If True return all paths recursively.

Returns

List of paths

Return type

List[str]

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

team_id = 8
path = "/999_App_Test/"
files = api.file.listdir(team_id, path)

print(files)
# Output: ["/999_App_Test/ds1", "/999_App_Test/image.png"]

remove(team_id, path)[source]¶

Removes a file from the Team Files. If the specified path is a directory, the entire directory (including all recursively included files) will be removed.

Parameters

team_id : int: Team ID in Supervisely.
path : str: Path in Team Files.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

api.file.remove(8, "/999_App_Test/ds1/01587.json") # remove file
api.file.remove(8, "/999_App_Test/ds1/") # remove folder

remove_batch(team_id, paths, progress_cb=None)[source]¶

Removes list of files from Team Files.

Parameters

team_id : int: Team ID in Supervisely.
paths : List[str]: List of paths to Files in Team Files.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

paths_to_del = [
    "/999_App_Test/ds1/01587.json",
    "/999_App_Test/ds1/01588.json",
    "/999_App_Test/ds1/01587.json"
]
api.file.remove(8, paths_to_del)

remove_dir(team_id, path, silent=False)[source]¶

Removes folder from Team Files.

Parameters

team_id : int: Team ID in Supervisely.
path : str: Path to folder in Team Files.
silent : bool: Ignore if directory not exists.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

api.file.remove_dir(8, "/999_App_Test/ds1/")

remove_file(team_id, path)[source]¶

Removes file from Team Files.

Parameters

team_id : int: Team ID in Supervisely.
path : str: Path to File in Team Files.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

api.file.remove_file(8, "/999_App_Test/ds1/01587.json")

rename(old_name, new_name)[source]¶

Renames file in Team Files

Parameters

old_name : str: Old File name.
new_name : str: New File name.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

# NotImplementedError('Method is not supported')

upload(team_id, src, dst, progress_cb=None)[source]¶

Upload File to Team Files.

Parameters

team_id : int: Team ID in Supervisely.
src : str: Local source file path.
dst : str: Path to File in Team Files.
progress_cb : tqdm or callable, optional: Function for tracking download progress.

Returns

Information about File. See info_sequence

Return type

FileInfo

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

src_path = "/home/admin/Downloads/01587.json"
dst_remote_path = "/999_App_Test/ds1/01587.json"

api.file.upload(8, src_path, dst_remote_path)

upload_bulk(team_id, src_paths, dst_paths, progress_cb=None)[source]¶

Upload Files to Team Files.

Parameters

team_id : int: Team ID in Supervisely.
src : List[str]: Local source file paths.
dst : List[str]: Destination paths for Files to Team Files.
progress_cb : tqdm or callable, optional: Function for tracking download progress.

Returns

Information about Files. See info_sequence

Return type

List[FileInfo]

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

src_paths = ["/home/admin/Downloads/01587.json", "/home/admin/Downloads/01588.json","/home/admin/Downloads/01589.json"]
dst_remote_paths = ["/999_App_Test/ds1/01587.json", "/999_App_Test/ds1/01588.json", "/999_App_Test/ds1/01589.json"]

api.file.upload_bulk(8, src_paths, dst_remote_paths)

upload_directory(team_id, local_dir, remote_dir, change_name_if_conflict=True, progress_size_cb=None, replace_if_conflict=False)[source]¶

Upload Directory to Team Files from local path.

Parameters

team_id : int: Team ID in Supervisely.
local_dir : str: Path to local Directory.
remote_dir : str: Path to Directory in Team Files.
change_name_if_conflict : bool, optional: Checks if given name already exists and adds suffix to the end of the name.
progress_size_cb : Progress, optional: Function for tracking download progress.

Returns

Path to Directory in Team Files

Return type

str

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

path_to_dir = "/My_App_Test/ds1"
local_path = "/home/admin/Downloads/My_local_test"

api.file.upload_directory(9, local_path, path_to_dir)