DataVersion¶

class DataVersion(api)[source]¶

Bases: ModuleApiBase

Class for managing project versions. This class provides methods for creating, restoring, and managing project versions.

Class for managing project versions.

Methods

`cancel_reservation`	Cancel version reservation for a project.
`commit`	Commit project version.
`convert_info_to_json`	Convert information about an entity to a dictionary.
`create`	Create a new project version.
`enable_preview`	Enable preview for the version by creating a snapshot project and linking it to the version.
`get_id_by_number`	Get version ID by version number.
`get_info_by_id`	Get project version information by version ID.
`get_info_by_number`	Get project version information by version number.
`get_list`	Get list of project versions.
`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.
`get_map`	Get project versions map from storage.
`get_or_create_versions_workspace`	Get or create a hidden workspace for storing preview project versions for a team.
`info_sequence`	NamedTuple VersionInfo with API Fields containing information about Project Version.
`info_tuple_name`	NamedTuple name - VersionInfo.
`initialize`	Initialize project versions.
`reserve`	Reserve project version.
`restore`	Restore project to a specific version.
`set_map`	Save project versions map to storage.
`update`	Update version information such as name, description or link preview project to the version.

Attributes

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

InfoType¶: alias of VersionInfo

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]¶: NamedTuple VersionInfo with API Fields containing information about Project Version.

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

cancel_reservation(version_id, commit_token)[source]¶

Cancel version reservation for a project.

Parameters:

version_id : int¶: Version ID
commit_token : str¶: Commit token

Returns:

True if reservation was cancelled, False otherwise

commit(version_id, commit_token, updated_at, file_id, title=None, description=None, preview_project_id=None)[source]¶

Commit project version. This method is used to finalize the version creation process. Requires active reservation. You must call this method after creating project version backup and setting version map

Parameters:

version_id : int¶: Version ID
commit_token : str¶: Commit token
updated_at : str¶: Updated at timestamp
file_id : int¶: File ID
title : Optional[str]¶: Version title
description : Optional[str]¶: Version description
preview_project_id : Optional[int]¶: ID of the cloned project that will be used to preview version data.

Returns:

None

create(project_info, version_title=None, version_description=None, enable_preview=False)[source]¶

Create a new project version. Returns the ID of the new version. If the project is already on the latest version, returns the latest version ID. If the project version cannot be created, returns None.

Parameters:

project_info¶: Project info object or project ID
version_title : Optional[str]¶: Version title
version_description : Optional[str]¶: Version description
enable_preview : bool¶: Enable preview flag that creates clone of the project to hidden workspace making version data available immediately. This option can be used to avoid waiting for version data to be processed on the server before previewing it. Only versions of projects with types VIDEO and IMAGE are supported for preview.

Returns:

Version ID

Return type:

int

enable_preview(project, version_id, overwrite=False, local_binary_path=None)[source]¶

Enable preview for the version by creating a snapshot project and linking it to the version. If the snapshot project already exists and overwrite is False, returns the existing snapshot project ID.

ATTENTION: This method works only for committed versions with successfully uploaded version data.

Parameters:

project : Union[int, ProjectInfo]¶: Source project ID or ProjectInfo object
version_id : int¶: Version ID
overwrite : bool¶: Whether to overwrite existing snapshot project if it exists
local_binary_path : Optional[str]¶: Path to a local version.bin file to use instead of downloading from server.

Returns:

Preview snapshot project information

Return type:

ProjectInfo

get_id_by_number(project_id, version_num)[source]¶

Get version ID by version number.

Parameters:

project_id : int¶: Project ID
version_num : int¶: Version number

Returns:

Version ID

Return type:

int or None

get_info_by_id(project_id, version_id)[source]¶

Get project version information by version ID.

Parameters:

project_id : int¶: Project ID
version_id : int¶: Version ID

Returns:

Project version information

Return type:

Optional[VersionInfo]

get_info_by_number(project_id, version_num)[source]¶

Get project version information by version number.

Parameters:

project_id : int¶: Project ID
version_num : int¶: Version number

Returns:

Project version information

Return type:

Optional[VersionInfo]

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

Get list of project versions.

Parameters:

project_id : int¶: Project ID
filters : Optional[List]¶: Filters

Returns:

List of project versions

Return type:

List[VersionInfo]

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

get_map(project_info, do_initialization=True)[source]¶

Get project versions map from storage.

Parameters:

project_info¶: Project info object or project ID
do_initialization : bool¶: Initialize project versions. Set to False for internal use.

Returns:

Project versions

Return type:

dict

get_or_create_versions_workspace(team_id, description='')[source]¶

Get or create a hidden workspace for storing preview project versions for a team.

Parameters:

team_id : int¶: Team ID
description : str¶: Workspace description

Returns:

Workspace ID

Return type:

int

initialize(project_info)[source]¶

Initialize project versions.

Parameters:

project_info¶: Project info object or project ID

reserve(project_id, retries=6)[source]¶

Reserve project version. This method is used before backing up a version to prevent another attempt to create a version at the same time. The first delay of retry is 2 seconds, which doubles with each subsequent attempt.

Parameters:

project_id : int¶: Project ID
retries : int¶: Number of attempts to reserve version

Returns:

Version ID and commit token

Return type:

Tuple[int, str]

restore(project_info, version_id=None, version_num=None, skip_missed_entities=False, workspace_id=None, project_name=None, project_description=None, local_binary_path=None)[source]¶

Restore project to a specific version. Version can be specified by ID or number.

Parameters:

project_info¶: Project info object or project ID
version_id : Optional[int]¶: Version ID
version_num : Optional[int]¶: Version number
skip_missed_entities : bool, default False¶: Skip missed Images
workspace_id : Optional[int]¶: Workspace ID where the restored project will be created. If None, the project will be restored to the same workspace.
project_name : Optional[str]¶: Name of the restored project. If None, a default name will be used.
project_description : Optional[str]¶: Description of the restored project. If None, a default description will be used.
local_binary_path : Optional[str]¶: Path to the local binary file to restore from. If None, will download from the server.

Returns:

Project info object of the restored project

Return type:

ProjectInfo or None

set_map(project_info, initialize=True)[source]¶

Save project versions map to storage.

Parameters:

project_info¶: Project info object or project ID
initialize : bool¶: Initialize project versions. Set to False for internal use.

Returns:

None

update(version_id, name=None, description=None, preview_project_id=None)[source]¶

Update version information such as name, description or link preview project to the version.

ATTENTION: Do not use preview_project_id parameter to link a regular project as it can cause issues with version data consistency. This parameter is intended to link a cloned project in the hidden workspace that is created when enabling preview for the version. Only versions of projects with types VIDEO and IMAGE are supported for preview.

Parameters:

version_id : int¶: Version ID
name : Optional[str]¶: New name
description : Optional[str]¶: New description
preview_project_id : Optional[int]¶: Preview project ID to link to the version. This project will be used to preview version data. Only versions of projects with types VIDEO and IMAGE are supported for preview.

Returns:

None

Return type:

None