High-level API

Overview

This layer provides high-level APIs, allowing easier access to server operations.API includesRepositories andEntities. Repositories provide managementoperations for Entities. Entities represent objects on the server(e.g. projects, tasks, jobs etc) and simplify interaction with them. The key differencefrom the low-level API is that operations on this layer are not limited by a singleserver request per operation and encapsulate low-level request machinery behind a high-levelobject-oriented API.

The code of this component is located in thecvat_sdk.core package.

Example

fromcvat_sdkimportmake_client,modelsfromcvat_sdk.core.proxies.tasksimportResourceType,Task# Create a Client instance bound to a local server and authenticate using basic authwithmake_client(host="http://localhost",credentials=('user','password'))asclient:# Let's create a new task.# Fill in task parameters first.# Models are used the same way as in the layer 1.task_spec={"name":"example task","labels":[{"name":"car","color":"#ff00ff","attributes":[{"name":"a","mutable":True,"input_type":"number","default_value":"5","values":["4","5","6"],}],}],}# Now we can create a task using a task repository method.# Repositories can be accessed as the Client class members.# In this case we use 2 local images as the task data.task=client.tasks.create_from_data(spec=task_spec,resource_type=ResourceType.LOCAL,resources=['image1.jpg','image2.png'],)# The returned task object is already up-to-date with its server counterpart.# Now we can access task fields. The fields are read-only and can be optional.# Let's check that we have 2 images in the task data.asserttask.size==2# If an object is modified on the server, the local object is not updated automatically.# To reflect the latest changes, the local object needs to be fetch()-ed.task.fetch()# Let's obtain another task. Again, it can be done via the task repository.# Suppose we have already created the task earlier and know the task id.task2=client.tasks.retrieve(42)# The task object fields can be update()-d. Note that the set of fields that can be# modified can be different from what is available for reading.task2.update({'name':'my task'})# And the task can also be remove()-d from the server. The local copy will remain# untouched.task2.remove()

Client

Thecvat_sdk.core.client.Client class provides session management, implementsauthentication operations and simplifies access to server APIs.It is the starting point for using CVAT SDK.

AClient instance allows you to:

• configure connection options with theConfig class
• check server API compatibility with the current SDK version
• deduce server connection scheme (https orhttp) automatically
• manage user session with thelogin(),logout() and other methods
• obtain Repository objects with theusers,tasks,jobs and other members
• reach to lower-level APIs with the corresponding members

An instance ofClient can be created directly by calling the class constructoror with the utility functioncvat_sdk.core.client.make_client() which can handlesome configuration for you. AClient can be configured withthecvat_sdk.core.client.Config class instance. AConfig object can be passed totheClient constructor and then it will be available in theClient.config field.

TheClient class implements thecontext manager protocol.When the context is closed, the session is finished, and the user is logged outautomatically. Otherwise, these actions can be done with theclose() andlogout() methods.

You can create and start using aClient instance this way:

fromcvat_sdkimportmake_clientwithmake_client('http://localhost',port='8080',credentials=('user','password'))asclient:...

Themake_client() function handles configuration and object creation for you.It also allows to authenticate right after the object is created.

If you need to configureClient parameters, you can do this:

fromcvat_sdkimportConfig,Clientconfig=Config()# set up some config fields ...withClient('http://localhost:8080',config=config)asclient:client.login(('user','password'))...

When the server is located, its version is checked. If an unsupported version is found,an error can be raised or suppressed (controlled byconfig.allow_unsupported_server).If the error is suppressed, some SDK functions may not work as expected with this server.By default, a warning is raised and the error is suppressed.

Users and organizations

AllClient operations rely on the server API and depend on the current userrights. This affects the set of available APIs, objects and actions. For example, a regular usercan only see and modify their tasks and jobs, while an admin user can see all the tasks etc.

Operations are also affected by the current organization context,which can be set with theorganization_slug property ofClient instances.The organization context affects which entities are visible,and where new entities are created.

Setorganization_slug to an organization’s slug (short name)to make subsequent operations work in the context of that organization:

client.organization_slug='myorg'# create a task in the organizationtask=client.tasks.create_from_data(...)

You can also setorganization_slug to an empty stringto work in the context of the user’s personal workspace.By default, it is set toNone,which means that both personal and organizational entities are visible,while new entities are created in the personal workspace.

To temporarily set the organization slug, use theorganization_context function:

withclient.organization_context('myorg'):task=client.tasks.create_from_data(...)# the slug is now reset to its previous value

Entities and Repositories

Entities represent objects on the server. They provide read access to object fieldsand implement additional relevant operations, including both the general Read-Update-Delete andobject-specific ones. The set of available general operations depends on the object type.

Repositories provide management operations for corresponding Entities. You don’tneed to create Repository objects manually. To obtain a Repository object, use thecorrespondingClient instance member:

client.projectsclient.tasksclient.jobsclient.users...

An Entity can be created on the server with the corresponding Repository methodcreate():

task=client.tasks.create(<taskconfig>)

We can retrieve server objects using theretrieve() andlist() methods of the Repository:

job=client.jobs.retrieve(<jobid>)tasks=client.tasks.list()

After calling these functions, we obtain local objects representing their server counterparts.

Object fields can be updated with theupdate() method. Note that the set of fields that can bemodified can be different from what is available for reading.

job.update({'stage':'validation'})

The server object will be updated and the local object will reflect the latest object stateafter calling this operation.

Note that local objects may fall out of sync with their server counterparts for different reasons.If you need to update the local object with the latest server state, use thefetch() method:

# obtain 2 local copies of the same jobjob_ref1=client.jobs.retrieve(1)job_ref2=client.jobs.retrieve(1)# update the server object with the first referencejob_ref1.update(...)# job_ref2 is outdated nowjob_ref2.fetch()# job_ref2 is synced

Finally, if you need to remove the object from the server, you can use theremove() method.The server object will be removed, but the local copy of the object will remain untouched.

task=client.tasks.retrieve(<taskid>)task.remove()

Repositories can also provide group operations over entities. For instance, you can retrieveall available objects using thelist() Repository method. The list of availableEntity and Repository operations depends on the object type.

You can learn more about entity members and how model parameters are passed to functionshere.

The implementation for these components is located incvat_sdk.core.proxies.