Api¶

Bases: object

An API connection to the server with which you can communicate with your teams, workspaces and projects. Api object is immutable.

Parameters

server_address : str: Address of the server.
token : str: Unique secret token associated with your agent.
retry_count : int, optional: The number of attempts to connect to the server.
retry_sleep_sec : int, optional: The number of seconds to delay between attempts to connect to the server.
external_logger : logger, optional: Logger class object.
ignore_task_id : bool, optional
api_server_address : str, optional: Address of the API server.
check_instance_version : bool or str, optional: Check if the given version is lower or equal to the current Supervisely instance version. If set to True, will try to read the version from the environment variable “MINIMUM_INSTANCE_VERSION_FOR_SDK”. If set to a string, will use this string as the version to check. If set to False, will skip the check.

Raises

ValueError, if token is None or it length != 128

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.supervisely.com", token="4r47N...xaTatb")

Methods

`add_additional_field`	Add given key and value to additional_fields dictionary.
`add_header`	Add given key and value to headers dictionary.
`from_credentials`	Create Api object using credentials and optionally save them to ".env" file with overriding environment variables.
`from_env`	Initialize API use environment variables.
`get`	Performs GET request to server with given parameters.
`is_version_supported`	Check if the given version is lower or equal to the current Supervisely instance version.
`normalize_server_address`	rtype `str`
`parse_error`	Processes error from response.
`pop_header`	rtype `str`
`post`	Performs POST request to server with given parameters.

Attributes

`api_server_address`	Get API server address.
`instance_version`	Return Supervisely instance version, e.g.

add_additional_field(key, value)[source]¶

Add given key and value to additional_fields dictionary.

Parameters

key : str: New key.
value : str: New value.

Returns

None

Return type

NoneType

add_header(key, value)[source]¶

Add given key and value to headers dictionary.

Parameters

key : str: New key.
value : str: New value.

Raises

RuntimeError, if key is already set

Returns

None

Return type

NoneType

classmethod from_credentials(server_address, login, password, override=False, env_file='/home/docs/supervisely.env', check_instance_version=False)[source]¶

Create Api object using credentials and optionally save them to “.env” file with overriding environment variables. If “.env” file already exists, backup will be created automatically. All backups will be stored in the same directory with postfix “_YYYYMMDDHHMMSS”. You can have not more than 5 last backups. This method can be used also to update “.env” file.

Parameters

server_address : str: Supervisely server url.
login : str: User login.
password : str: User password.
override : bool, optional: If False, return Api object. If True, additionally create “.env” file or overwrite existing (backup file will be created automatically), and override environment variables.
env_file : str, optional: Path to your .env file.
check_instance_version : bool or str, optional: Check if the given version is lower or equal to the current version of the Supervisely instance.

Return type

Api

Returns

Api object

Usage example

import supervisely as sly

server_address = 'https://app.supervisely.com'
login = 'user'
password = 'pass'

api = sly.Api.from_credentials(server_address, login, password)

classmethod from_env(retry_count=10, ignore_task_id=False, env_file='/home/docs/supervisely.env', check_instance_version=False)[source]¶

Initialize API use environment variables.

Parameters

retry_count : int: The number of attempts to connect to the server.
ignore_task_id : bool
env_file : str: Path to your .env file.
check_instance_version : bool or str, optional: Check if the given version is lower or equal to the current version of the Supervisely instance.

Returns

Api object

Return type

Api

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'

api = sly.Api.from_env()

# alternatively you can store SERVER_ADDRESS and API_TOKEN
# in "~/supervisely.env" .env file
# Learn more here: https://developer.supervisely.com/app-development/basics/add-private-app#create-.env-file-supervisely.env-with-the-following-content-learn-more-here

api = sly.Api.from_env()

get(method, params, retries=None, stream=False, use_public_api=True)[source]¶

Performs GET request to server with given parameters.

Parameters

method : bool, optional
params : Dict: Dictionary to send in the body of the Request.
retries : Optional[int]: The number of attempts to connect to the server.
stream : Optional[bool]: Define, if you’d like to get the raw socket response from the server.
use_public_api : Optional[bool]

Returns

Response object

Return type

Response

is_version_supported(version=None)[source]¶

Check if the given version is lower or equal to the current Supervisely instance version. If the version omitted, will try to read it from the environment variable “MINIMUM_INSTANCE_VERSION_FOR_SDK”. If the version is lower or equal, return True, otherwise False. If the version of the instance cannot be determined, return False.

Parameters

version : Optional[str], e.g. "6.9.13": Version to check.

Returns

True if the given version is lower or equal to the current Supervisely instance version, otherwise False.

Return type

bool

Usage example

import supervisely as sly

api = sly.Api(server_address='https://app.supervisely.com', token='4r47N...xaTatb')
version_to_check = "6.9.13"
print(api.is_version_supported(version_to_check))
# Output:
# True

static parse_error(response, default_error='Error', default_message='please, contact administrator')[source]¶

Processes error from response.

Parameters

response : Response: Request object.
default_error : Optional[str]: Error description.
default_message : Optional[str]: Message to user.

Returns

Number of error and message about curren connection mistake

Return type

int, str

post(method, data, retries=None, stream=False, raise_error=False)[source]¶

Performs POST request to server with given parameters.

Parameters

method : str: Method name.
data : dict: Dictionary to send in the body of the Request.
retries : int, optional: The number of attempts to connect to the server.
stream : bool, optional: Define, if you’d like to get the raw socket response from the server.
raise_error : bool, optional: Define, if you’d like to raise error if connection is failed. Retries will be ignored.

Returns

Response object

Return type

Response

property api_server_address¶

Get API server address.

Returns

API server address.

Return type

str

Usage example

import supervisely as sly

api = sly.Api(server_address='https://app.supervisely.com', token='4r47N...xaTatb')
print(api.api_server_address)
# Output:
# 'https://app.supervisely.com/public/api'

property instance_version¶

Return Supervisely instance version, e.g. “6.9.13”. If the version cannot be determined, return “unknown”.

Returns: Supervisely instance version or “unknown” if the version cannot be determined.
Return type: str
Usage example

import supervisely as sly

api = sly.Api(server_address='https://app.supervisely.com', token='4r47N...xaTatb')
print(api.instance_version)
# Output:
# '6.9.13'