Various improvements to the SDK generation process (#5678)
Roman Donchenko
3 years ago
committed by
GitHub
parent
89f403b7e2
commit
87f07fd391
@ -1,40 +0,0 @@
|
|||||||
# OpenAPI Generator Ignore
|
|
||||||
# Generated by openapi-generator https://github.com/openapitools/openapi-generator
|
|
||||||
|
|
||||||
# Use this file to prevent files from being overwritten by the generator.
|
|
||||||
# The patterns follow closely to .gitignore or .dockerignore.
|
|
||||||
|
|
||||||
# As an example, the C# client generator defines ApiClient.cs.
|
|
||||||
# You can make changes and tell OpenAPI Generator to ignore just this file by uncommenting the following line:
|
|
||||||
#ApiClient.cs
|
|
||||||
|
|
||||||
# You can match any string of characters against a directory, file or extension with a single asterisk (*):
|
|
||||||
#foo/*/qux
|
|
||||||
# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux
|
|
||||||
|
|
||||||
# You can recursively match patterns against a directory, file or extension with a double asterisk (**):
|
|
||||||
#foo/**/qux
|
|
||||||
# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux
|
|
||||||
|
|
||||||
# You can also negate patterns with an exclamation (!).
|
|
||||||
# For example, you can ignore all files in a docs folder with the file extension .md:
|
|
||||||
#docs/*.md
|
|
||||||
# Then explicitly reverse the ignore rule for a single file:
|
|
||||||
#!docs/README.md
|
|
||||||
|
|
||||||
# For safety
|
|
||||||
/cvat_sdk/__init__.py
|
|
||||||
/config
|
|
||||||
/gen
|
|
||||||
/helpers.py
|
|
||||||
/utils.py
|
|
||||||
/types.py
|
|
||||||
|
|
||||||
# Don't generate these files
|
|
||||||
/git_push.sh
|
|
||||||
/setup.cfg
|
|
||||||
/test-requirements.txt
|
|
||||||
/tox.ini
|
|
||||||
/.gitlab-ci.yml
|
|
||||||
/.travis.yml
|
|
||||||
/.gitignore
|
|
||||||
@ -1,36 +0,0 @@
|
|||||||
# {{{projectName}}}
|
|
||||||
{{#appDescriptionWithNewLines}}
|
|
||||||
{{{.}}}
|
|
||||||
{{/appDescriptionWithNewLines}}
|
|
||||||
|
|
||||||
This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
|
|
||||||
|
|
||||||
- API version: {{appVersion}}
|
|
||||||
- Package version: {{packageVersion}}
|
|
||||||
{{^hideGenerationTimestamp}}
|
|
||||||
- Build date: {{generatedDate}}
|
|
||||||
{{/hideGenerationTimestamp}}
|
|
||||||
- Build package: {{generatorClass}}
|
|
||||||
{{#infoUrl}}
|
|
||||||
For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
|
|
||||||
{{/infoUrl}}
|
|
||||||
|
|
||||||
## Installation & Usage
|
|
||||||
|
|
||||||
To install a prebuilt package, run the following command in the terminal:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
pip install cvat-sdk
|
|
||||||
```
|
|
||||||
|
|
||||||
To install from the local directory, follow [the developer guide](https://opencv.github.io/cvat/docs/api_sdk/sdk/developer_guide).
|
|
||||||
|
|
||||||
After installation you can import the package:
|
|
||||||
|
|
||||||
```python
|
|
||||||
import cvat_sdk
|
|
||||||
```
|
|
||||||
|
|
||||||
## Getting Started
|
|
||||||
|
|
||||||
{{> README_common }}
|
|
||||||
@ -1,176 +0,0 @@
|
|||||||
API includes 2 layers:
|
|
||||||
- REST API wrappers (`ApiClient`). Located in at `cvat_sdk.api_client`
|
|
||||||
- high-level tools (`core`). Located at `cvat_sdk.core`
|
|
||||||
|
|
||||||
### `ApiClient` (low level)
|
|
||||||
|
|
||||||
This layer is useful if you need to work directly with REST API, but want
|
|
||||||
to have data validation and syntax assistance from your code editor. The code
|
|
||||||
on this layer is autogenerated.
|
|
||||||
|
|
||||||
#### Example
|
|
||||||
|
|
||||||
Let's see how a task with local files can be created. We will use the basic auth
|
|
||||||
to make things simpler.
|
|
||||||
|
|
||||||
```python
|
|
||||||
from time import sleep
|
|
||||||
from cvat_sdk.api_client import Configuration, ApiClient, models, apis, exceptions
|
|
||||||
|
|
||||||
configuration = Configuration(
|
|
||||||
host="{{{basePath}}}",
|
|
||||||
username='YOUR_USERNAME',
|
|
||||||
password='YOUR_PASSWORD',
|
|
||||||
)
|
|
||||||
|
|
||||||
# Enter a context with an instance of the API client
|
|
||||||
with ApiClient(configuration) as api_client:
|
|
||||||
# Parameters can be passed as a plain dict with JSON-serialized data
|
|
||||||
# or as model objects (from cvat_sdk.api_client.models), including
|
|
||||||
# mixed variants.
|
|
||||||
#
|
|
||||||
# In case of dicts, keys must be the same as members of models.I<ModelName>
|
|
||||||
# interfaces and values must be convertible to the corresponding member
|
|
||||||
# value types (e.g. a date or string enum value can be parsed from a string).
|
|
||||||
#
|
|
||||||
# In case of model objects, data must be of the corresponding
|
|
||||||
# models.<ModelName> types.
|
|
||||||
#
|
|
||||||
# Let's use a dict here. It should look like models.ITaskWriteRequest
|
|
||||||
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"]
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}],
|
|
||||||
}
|
|
||||||
|
|
||||||
try:
|
|
||||||
# Apis can be accessed as ApiClient class members
|
|
||||||
# We use different models for input and output data. For input data,
|
|
||||||
# models are typically called like "*Request". Output data models have
|
|
||||||
# no suffix.
|
|
||||||
(task, response) = api_client.tasks_api.create(task_spec)
|
|
||||||
except exceptions.ApiException as e:
|
|
||||||
# We can catch the basic exception type, or a derived type
|
|
||||||
print("Exception when trying to create a task: %s\n" % e)
|
|
||||||
|
|
||||||
# Here we will use models instead of a dict
|
|
||||||
task_data = models.DataRequest(
|
|
||||||
image_quality=75,
|
|
||||||
start_frame=2,
|
|
||||||
stop_frame=5,
|
|
||||||
client_files=[
|
|
||||||
open('image1.jpg', 'rb'),
|
|
||||||
open('image2.jpg', 'rb'),
|
|
||||||
],
|
|
||||||
)
|
|
||||||
|
|
||||||
# If we pass binary file objects, we need to specify content type.
|
|
||||||
# For this endpoint, we don't have response data
|
|
||||||
(_, response) = api_client.tasks_api.create_data(task.id,
|
|
||||||
data_request=task_data,
|
|
||||||
_content_type="multipart/form-data",
|
|
||||||
|
|
||||||
# we can choose to check the response status manually
|
|
||||||
# and disable the response data parsing
|
|
||||||
_check_status=False, _parse_response=False
|
|
||||||
)
|
|
||||||
assert response.status == 202, response.msg
|
|
||||||
|
|
||||||
# Wait till task data is processed
|
|
||||||
for _ in range(100):
|
|
||||||
(status, _) = api_client.tasks_api.retrieve_status(task.id)
|
|
||||||
if status.state.value in ['Finished', 'Failed']:
|
|
||||||
break
|
|
||||||
sleep(0.1)
|
|
||||||
assert status.state.value == 'Finished', status.message
|
|
||||||
|
|
||||||
# Update the task object and check the task size
|
|
||||||
(task, _) = api_client.tasks_api.retrieve(task.id)
|
|
||||||
assert task.size == 4
|
|
||||||
```
|
|
||||||
|
|
||||||
### `Core` (high-level)
|
|
||||||
|
|
||||||
This layer provides high-level APIs, allowing easier access to server operations.
|
|
||||||
API includes *Repositories* and *Entities*. Repositories provide management
|
|
||||||
operations for Entitites. Entitites represent separate objects on the server
|
|
||||||
(e.g. tasks, jobs etc).
|
|
||||||
|
|
||||||
#### Example
|
|
||||||
|
|
||||||
```python
|
|
||||||
from cvat_sdk import make_client, models
|
|
||||||
from cvat_sdk.core.proxies.tasks import ResourceType, Task
|
|
||||||
|
|
||||||
with make_client(host="{{{basePath}}}") as client:
|
|
||||||
# Authorize using the basic auth
|
|
||||||
client.login(('YOUR_USERNAME', 'YOUR_PASSWORD'))
|
|
||||||
|
|
||||||
# Models are used the same way as in the layer 1
|
|
||||||
task_spec = {
|
|
||||||
"name": "example task 2",
|
|
||||||
"labels": [
|
|
||||||
{
|
|
||||||
"name": "car",
|
|
||||||
"color": "#ff00ff",
|
|
||||||
"attributes": [
|
|
||||||
{
|
|
||||||
"name": "a",
|
|
||||||
"mutable": True,
|
|
||||||
"input_type": "number",
|
|
||||||
"default_value": "5",
|
|
||||||
"values": ["4", "5", "6"],
|
|
||||||
}
|
|
||||||
],
|
|
||||||
}
|
|
||||||
],
|
|
||||||
}
|
|
||||||
|
|
||||||
# Different repositories can be accessed as the Client class members.
|
|
||||||
# They may provide both simple and complex operations,
|
|
||||||
# such as entity creation, retrieval and removal.
|
|
||||||
task = client.tasks.create_from_data(
|
|
||||||
spec=task_spec,
|
|
||||||
resource_type=ResourceType.LOCAL,
|
|
||||||
resources=['image1.jpg', 'image2.png'],
|
|
||||||
)
|
|
||||||
|
|
||||||
# Task object is already up-to-date with its server counterpart
|
|
||||||
assert task.size == 2
|
|
||||||
|
|
||||||
# An entity needs to be fetch()-ed to reflect the latest changes.
|
|
||||||
# It can be update()-d and remove()-d depending on the entity type.
|
|
||||||
task.update({'name': 'mytask'})
|
|
||||||
task.remove()
|
|
||||||
```
|
|
||||||
|
|
||||||
## Available API Endpoints
|
|
||||||
|
|
||||||
All URIs are relative to _{{basePath}}_
|
|
||||||
|
|
||||||
Class | Method | HTTP request | Description
|
|
||||||
------------ | ------------- | ------------- | -------------
|
|
||||||
{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}_{{classname}}_ | [**{{>operation_name}}**](apis/{{classname}}#{{>operation_name}}) | **{{httpMethod}}** {{path}} | {{summary}}
|
|
||||||
{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}}
|
|
||||||
|
|
||||||
## Available Models
|
|
||||||
|
|
||||||
{{#models}}{{#model}} - {{{classname}}}
|
|
||||||
{{/model}}{{/models}}
|
|
||||||
|
|
||||||
|
|
||||||
## Author
|
|
||||||
|
|
||||||
{{#apiInfo}}{{#apis}}{{#-last}}{{infoEmail}}
|
|
||||||
{{/-last}}{{/apis}}{{/apiInfo}}
|
|
||||||
@ -1 +0,0 @@
|
|||||||
VERSION = "{{packageVersion}}"
|
|
||||||
Loading…
Reference in New Issue