Api¶

class Api[source]¶

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

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.supervise.ly", 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.
normalize_server_address	rtype str
parse_error	Processes error from response.
pop_header	rtype str
post	Performs POST request to server with given parameters.

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

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')[source]¶

Initialize API use environment variables.

Parameters

retry_count : int

The number of attempts to connect to the server.

ignore_task_id : bool

path : str

Path to your .env file.

Returns

Api object

Return type

Api

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

# alternatively you can store SERVER_ADDRESS and API_TOKEN
# in "~/supervisely.env" .env file
# Learn more here: https://developer.supervise.ly/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

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)[source]¶

Performs POST request to server with given parameters.

Parameters

method : str

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.

Returns

Response object

Return type

Response