The Client class provides session management, authentication, and access to CVAT server APIs.
Creating a Client
Basic Initialization
from cvat_sdk import Client
client = Client(url="cvat.example.com")
"cvat.example.com" - Auto-detects HTTPS/HTTP"https://cvat.example.com" - Explicit HTTPS"http://localhost:8080" - Explicit HTTP with port
Using make_client Helper
The make_client function provides a convenient way to create and authenticate a client:
from cvat_sdk import make_client
# With password authentication
client = make_client(
host="cvat.example.com",
credentials=("username", "password")
)
# With access token
client = make_client(
host="cvat.example.com",
access_token="your_personal_access_token"
)
# With custom port
client = make_client(
host="cvat.example.com",
port=8080,
credentials=("username", "password")
)
Authentication
The SDK supports two authentication methods: password-based and token-based.
Password Authentication
Authenticate with username and password:
from cvat_sdk import Client, PasswordCredentials
client = Client(url="cvat.example.com")
# Using tuple
client.login(("username", "password"))
# Using PasswordCredentials class
credentials = PasswordCredentials(user="username", password="password")
client.login(credentials)
Token Authentication
Authenticate with a Personal Access Token (PAT):
from cvat_sdk import Client, AccessTokenCredentials
client = Client(url="cvat.example.com")
# Using AccessTokenCredentials class
credentials = AccessTokenCredentials(token="your_token_here")
client.login(credentials)
Checking Authentication Status
if client.has_credentials():
print("Client is authenticated")
else:
print("Client is not authenticated")
Logging Out
Configuration
Customize client behavior with the Config class:
from cvat_sdk import Client, Config
config = Config(
status_check_period=5.0, # Operation status check interval in seconds
allow_unsupported_server=True, # Allow unsupported server versions
verify_ssl=True, # Verify SSL certificates (or None for default)
cache_dir="/custom/cache/path" # Custom cache directory
)
client = Client(url="cvat.example.com", config=config)
Configuration Options
Interval in seconds between status checks for long-running operations (uploads, exports, etc.)
Whether to allow connection to unsupported CVAT server versions. If False, raises IncompatibleVersionException.
verify_ssl
bool | None
default:"None"
SSL certificate verification. Set to False to disable (not recommended for production).
cache_dir
Path
default:"~/.cache/cvat-sdk"
Directory for caching server data (used by datasets and PyTorch adapters).
Context Manager
Use the client as a context manager for automatic cleanup:
with Client(url="cvat.example.com") as client:
client.login(("username", "password"))
# Perform operations
tasks = client.tasks.list()
# Connection automatically closed
client = Client(url="cvat.example.com")
try:
client.login(("username", "password"))
# Perform operations
finally:
client.close()
API Access
The client provides access to various CVAT resources through repository properties:
Tasks Repository
# Access tasks repository
tasks_repo = client.tasks
# List all tasks
tasks = tasks_repo.list()
# Get specific task
task = tasks_repo.retrieve(123)
# Create task
task = tasks_repo.create(spec=task_spec)
Projects Repository
# Access projects repository
projects_repo = client.projects
projects = projects_repo.list()
project = projects_repo.retrieve(456)
Jobs Repository
# Access jobs repository
jobs_repo = client.jobs
jobs = jobs_repo.list()
job = jobs_repo.retrieve(789)
Users Repository
# Access users repository
users_repo = client.users
users = users_repo.list()
user = users_repo.retrieve(1)
Organizations Repository
# Access organizations repository
orgs_repo = client.organizations
orgs = orgs_repo.list()
org = orgs_repo.retrieve(10)
# Access issues
issues_repo = client.issues
issues = issues_repo.list()
# Access comments
comments_repo = client.comments
comments = comments_repo.list()
Organization Context
Set an organization context for all operations:
# Set organization context by slug
client.organization_slug = "my-organization"
# All operations now use this organization
tasks = client.tasks.list() # Only tasks in 'my-organization'
# Clear organization context (use personal workspace)
client.organization_slug = None
# Temporarily use different organization
with client.organization_context("other-org"):
tasks = client.tasks.list() # Tasks in 'other-org'
# Reverts to previous context after block
Low-Level API Access
Access the underlying auto-generated API client:
from cvat_sdk.api_client import Configuration, ApiClient
# The client exposes the low-level API client
api_client = client.api_client
# Access specific API endpoints
server_api = api_client.server_api
about, response = server_api.retrieve_about()
print(f"Server version: {about.version}")
# Access configuration
api_config = api_client.configuration
print(f"Host: {api_config.host}")
Server Version Checking
The SDK checks server version compatibility on initialization:
# Disable version check during initialization
client = Client(url="cvat.example.com", check_server_version=False)
# Manually check version later
try:
client.check_server_version(fail_if_unsupported=True)
except IncompatibleVersionException as e:
print(f"Incompatible server version: {e}")
# Get server version
from packaging.version import Version
server_version: Version = client.get_server_version()
print(f"Server version: {server_version}")
Waiting for Long Operations
Some operations (uploads, exports) are asynchronous. Use wait_for_completion to wait for them:
# After starting an async operation that returns a request ID
rq_id = "some-request-id"
request, response = client.wait_for_completion(
rq_id,
status_check_period=3, # Check every 3 seconds
log_prefix="My operation" # Custom log message prefix
)
print(f"Operation completed with status: {request.status}")
Logging
The client uses Python’s standard logging module:
import logging
# Create custom logger
logger = logging.getLogger("my_cvat_client")
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler()
handler.setFormatter(logging.Formatter('%(asctime)s - %(levelname)s - %(message)s'))
logger.addHandler(handler)
# Pass logger to client
client = Client(url="cvat.example.com", logger=logger)
# Access client's logger
client.logger.info("Custom log message")
API URL Construction
The client provides URL construction utilities:
# Access the API URL builder
api_map = client.api_map
# Get base URL
print(f"Host: {api_map.host}") # e.g., "https://cvat.example.com"
print(f"API base: {api_map.base}") # e.g., "https://cvat.example.com/api/"
# Build custom endpoint URL
url = api_map.make_endpoint_url(
"/api/tasks/{id}/data",
kwsub={"id": 123},
query_params={"quality": "compressed"}
)
Exception Handling
from cvat_sdk.core.exceptions import (
IncompatibleVersionException,
InvalidHostException,
BackgroundRequestException
)
from cvat_sdk.api_client.exceptions import ApiException
try:
client = Client(url="invalid://url")
except InvalidHostException as e:
print(f"Invalid host: {e}")
try:
client.check_server_version(fail_if_unsupported=True)
except IncompatibleVersionException as e:
print(f"Version mismatch: {e}")
try:
task = client.tasks.retrieve(99999)
except ApiException as e:
print(f"API error: {e.status} - {e.reason}")
Next Steps
