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