WorkspaceApi¶

class WorkspaceApi(api)[source]¶

Bases: ModuleApi, UpdateableModule

API for working with workspaces.

Parameters:

api¶: Api object to use for API connection.

Usage Example:

import supervisely as sly
api = sly.Api.from_env()
workspace_info = api.workspace.get_info_by_id(workspace_id)

Methods

`archive`	Archive Workspace by ID.
`change_visibility`	Change Workspace visibility by Workspace ID.
`convert_info_to_json`	Convert information about an entity to a dictionary.
`create`	Create a new Workspace with the given name in the given Team.
`exists`	Checks if an entity with the given parent_id and name exists
`get_free_name`	Generates a free name for an entity with the given parent_id and name.
`get_info_by_id`	Get Workspace information by Workspace ID.
`get_info_by_name`	Get information about an entity by its name from the Supervisely server.
`get_list`	List of Workspaces in the given Team on the Supervisely instance.
`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_list_idx_page_async`	Get the list of items for a given page number.
`get_list_page_generator_async`	Yields list of images in dataset asynchronously page by page.
`info_sequence`	Sequence of fields that are returned by the API to represent WorkspaceInfo.
`info_tuple_name`	Name of the tuple that represents WorkspaceInfo.
`remove_permanently`	!!! WARNING !!! Be careful, this method deletes data from the database, recovery is not possible.
`update`	Update an entity with the specified ID.

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 WorkspaceInfo

classmethod convert_info_to_json(info)¶

Convert information about an entity to a dictionary.

Parameters:

info : NamedTuple¶: Information about the entity.

Returns:

Dictionary with information about the entity.

Return type:

dict

static info_sequence()[source]¶

Sequence of fields that are returned by the API to represent WorkspaceInfo.

Usage Example:

WorkspaceInfo(
    id=15,
    name='Cars',
    description='Workspace contains Project with annotated Cars',
    team_id=8,
    created_at='2020-04-15T10:50:41.926Z',
    updated_at='2020-04-15T10:50:41.926Z'
)

static info_tuple_name()[source]¶: Name of the tuple that represents WorkspaceInfo.

archive(id)[source]¶

Archive Workspace by ID.

The Workspace is not deleted from the database, it is hidden from the Workspace list and can be restored. To delete the Workspace and all its data permanently use remove_permanently().

Parameters:

id : int¶: Workspace ID in Supervisely.

Returns:

None

Return type:

None

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

api.workspace.archive(58)

change_visibility(id, visible)[source]¶

Change Workspace visibility by Workspace ID.

Parameters:

id : int¶: Workspace ID.
visible : bool¶: Visibility status.

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

api.workspace.change_visibility(58, False)

create(team_id, name, description='', change_name_if_conflict=False, hidden=False)[source]¶

Create a new Workspace with the given name in the given Team.

Parameters:

team_id : int¶: Team ID in Supervisely where Workspace will be created.
name : str¶: Workspace Name.
description : str¶: Workspace description.
change_name_if_conflict : bool¶: Checks if given name already exists and adds suffix to the end of the name.
hidden : bool¶: Whether the workspace should be hidden or not.

Returns:

Information about Workspace.

Return type:

WorkspaceInfo

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

new_workspace = api.workspace.create(8, "Vehicle Detection")
print(new_workspace)
# Output: WorkspaceInfo(id=274,
#                       name='Vehicle Detection"',
#                       description='',
#                       team_id=8,
#                       created_at='2021-03-11T12:24:21.773Z',
#                       updated_at='2021-03-11T12:24:21.773Z')

exists(parent_id, name)¶

Checks if an entity with the given parent_id and name exists

Parameters:

parent_id : int¶: ID of the parent entity.
name : str¶: Name of the entity.

Returns:

Returns True if entity exists, and False if not

Return type:

bool

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

name = "IMG_0315.jpeg"
dataset_id = 55832
exists = api.image.exists(dataset_id, name)
print(exists) # True

get_free_name(parent_id, name)¶

Generates a free name for an entity with the given parent_id and name. Adds an increasing suffix to original name until a unique name is found.

Parameters:

parent_id : int¶: ID of the parent entity.
name : str¶: Name of the entity.

Returns:

Returns free name.

Return type:

str

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

name = "IMG_0315.jpeg"
dataset_id = 55832
free_name = api.image.get_free_name(dataset_id, name)
print(free_name) # IMG_0315_001.jpeg

get_info_by_id(id, raise_error=False)[source]¶

Get Workspace information by Workspace ID.

Parameters:

id : int¶: Workspace ID in Supervisely.

Returns:

Information about Workspace.

Return type:

WorkspaceInfo

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

workspace_info = api.workspace.get_info_by_id(58)
print(workspace_info)
# Output: WorkspaceInfo(id=58,
#                       name='Test',
#                       description='',
#                       team_id=8,
#                       created_at='2020-11-09T18:21:08.202Z',
#                       updated_at='2020-11-09T18:21:08.202Z')

get_info_by_name(parent_id, name, fields=[])¶

Get information about an entity by its name from the Supervisely server.

Parameters:

parent_id : int¶: ID of the parent entity.
name : str¶: Name of the entity for which the information is being retrieved.
fields : List[str]¶: The list of api fields which will be returned with the response.

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

dataset_id = 55832
name = "IMG_0315.jpeg"
info = api.image.get_info_by_name(dataset_id, name)
print(info)
# Output: ImageInfo(id=19369643, name='IMG_0315.jpeg', ...)

get_list(team_id, filters=None)[source]¶

List of Workspaces in the given Team on the Supervisely instance.

Parameters:

team_id : int¶: Team ID in which the Workspaces are located.
filters : List[Dict[str, str]], optional¶: List of params to sort output Workspaces.

Returns:

List of all Workspaces with information for the given Team.

Return type:

List[WorkspaceInfo]

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

workspace_infos = api.workspace.get_list(8)
print(workspace_infos)
# Output: [
# WorkspaceInfo(id=15,
#               name='Cars',
#               description='',
#               team_id=8,
#               created_at='2020-04-15T10:50:41.926Z',
#               updated_at='2020-04-15T10:50:41.926Z'),
# WorkspaceInfo(id=18,
#               name='Heart',
#               description='',
#               team_id=8,
#               created_at='2020-05-20T15:01:54.172Z',
#               updated_at='2020-05-20T15:01:54.172Z'),
# WorkspaceInfo(id=20,
#               name='PCD',
#               description='',
#               team_id=8,
#               created_at='2020-06-24T11:51:11.336Z',
#               updated_at='2020-06-24T11:51:11.336Z')
# ]

# Filtered Workspace list
workspace_infos = api.workspace.get_list(8, filters=[{ 'field': 'name', 'operator': '=', 'value': 'Heart'}])
print(workspace_infos)
# Output: [WorkspaceInfo(id=18,
#                       name='Heart',
#                       description='',
#                       team_id=8,
#                       created_at='2020-05-20T15:01:54.172Z',
#                       updated_at='2020-05-20T15:01:54.172Z')
# ]

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

Returns:

List of entities.

Return type:

List[dict]

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

async get_list_idx_page_async(method, data)¶

Get the list of items for a given page number. Page number is specified in the data dictionary.

Parameters:

method : str¶: Method to call for listing items.
data : dict¶: Data to pass to the API method.

Returns:

List of items.

Return type:

Tuple[int, List[NamedTuple]]

async get_list_page_generator_async(method, data, pages_count=None, semaphore=None)¶

Yields list of images in dataset asynchronously page by page.

Parameters:

method : str¶: Method to call for listing items.
data : dict¶: Data to pass to the API method.
pages_count : int, optional¶: Preferred number of pages to retrieve if used with a per_page limit. Will be automatically adjusted if the pagesCount differs from the requested number.
semaphore=None¶: Semaphore for limiting the number of simultaneous requests.

Returns:

List of images in dataset.

Return type:

AsyncGenerator[List[ImageInfo]]

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

method = 'images.list'
data = {'datasetId': 123456}

loop = sly.utils.get_or_create_event_loop()
images = loop.run_until_complete(api.image.get_list_generator_async(method, data))

remove_permanently(ids, batch_size=50, progress_cb=None)[source]¶

!!! WARNING !!! Be careful, this method deletes data from the database, recovery is not possible.

Delete permanently workspaces with given IDs from the Supervisely server. Workspaces must be archived with archive() before calling this method, otherwise the server rejects the request. The method is available only for the instance administrator (root user), a regular user token is not enough.

Parameters:

ids : Union[int, List]¶: IDs of workspaces in Supervisely.
batch_size : int, optional¶: The number of entities that will be deleted by a single API call. This value must be in the range 1-50 inclusive, if you set a value out of range it will automatically adjust to the boundary values.
progress_cb : Callable, optional¶: Function for control delete progress.

Returns:

A list of response content in JSON format for each API call.

Return type:

List[dict]

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

workspace_ids = [58, 59]
for workspace_id in workspace_ids:
    api.workspace.archive(workspace_id)
responses = api.workspace.remove_permanently(workspace_ids)

update(id, name=None, description=None)¶

Update an entity with the specified ID.

Parameters:

id : int¶: ID of the entity to update.
name : str, optional¶: New name of the entity.
description : str, optional¶: New description of the entity.

Returns:

Entity with updated information.

Return type:

dict