annofab-api-python-client
Annofab Web API のPythonクライアントライブラリです。
- Annofab Web API Documentation: https://annofab.com/docs/api/
- Reference Documentation: https://annofab-api-python-client.readthedocs.io/en/latest/
- annofab-cli https://github.com/kurusugawa-computer/annofab-cli
- 「タスクの一括差し戻し」や、「プロジェクト間の差分表示」など、Annofabの画面で実施するには時間がかかる操作を、CLIツールとして提供しています。
- 開発者用ドキュメント: README_for_developer.md
注意
- 作者または著作権者は、ソフトウェアに関してなんら責任を負いません。
- 現在、APIは開発途上版です。予告なく互換性のない変更がある可能性をご了承ください。
- put, post, delete系のメソッドを間違えて実行してしまわないよう、注意してください。特に「プロジェクト削除」や「アノテーション仕様更新」のAPIには十分注意してください。
廃止予定
現在ありません。
Features
cURLやPostmanなどよりも簡単にAnnofab Web APIにアクセスできます。
- ログインを意識せずに、APIを利用できます。
- アクセス過多などで失敗した場合は、リトライされます。
- 「画像を入力データとして登録する」機能など、APIを組み合わせた機能も利用できます。
Requirements
- Python 3.11+
Install
$ pip install annofabapi
https://pypi.org/project/annofabapi/
Usage
インスタンス生成
user_id, passwordをコンストラクタ引数に渡す場合
# APIアクセス用のインスタンスを生成
from annofabapi import build
user_id = "XXXXXX"
password = "YYYYYY"
service = build(user_id, password)
PersonalAccessTokenをコンストラクタ引数に渡す場合
# APIアクセス用のインスタンスを生成
from annofabapi import build
pat = "XXXXXX"
service = build(pat = pat)
.netrcに認証情報を記載する場合
.netrcファイルに、AnnofabのユーザIDとパスワードを記載します。
machine annofab.com
login annofab_user_id
password annofab_password
from annofabapi import build_from_netrc
service = build_from_netrc()
For Linux
- パスは
$HOME/.netrc $ chmod 600 $HOME/.netrcでパーミッションを変更する
For Windows
- パスは
%USERPROFILE%\.netrc
環境変数に認証情報を設定する場合
- IDとパスワードで認証する場合
- 環境変数
ANNOFAB_USER_ID、ANNOFAB_PASSWORDにユーザIDとパスワードを設定します。
- 環境変数
- パーソナルアクセストークンで認証する場合
- 環境変数
ANNOFAB_PATにトークンを設定します。 ANNOFAB_PATが設定されている場合、ANNOFAB_USER_ID、ANNOFAB_PASSWORDは無視されます。
- 環境変数
from annofabapi import build_from_env
service = build_from_env()
.netrcまたは環境変数に認証情報を設定する場合
build() を実行すると、環境変数または .netrc ファイルから認証情報を読み込みます。
from annofabapi import build
service = build()
優先順位は以下の通りです。
- 環境変数
ANNOFAB_PATANNOFAB_USER_ID及びANNOFAB_PASSWORD
.netrc
service.apiのサンプルコード
service.apiには、Web APIに対応するメソッドが定義されています。- メソッド名は、Annofab Web APIのOpenAPI specificationに記載されている
operationIdを、スネークケースに変換したものです。 - 各メソッドの戻り値の型は
Tupple[Content, Response]です。 ResponseはrequestsモジュールのReponseオブジェクトです。 ContentはReponseの中身です。
project_id = "ZZZZZZ"
# `status`が`complete`のタスクを取得する
content, response = service.api.get_tasks(project_id, query_params={"status": "complete"})
print(type(content))
# <class 'dict'>
print(content)
# {'list': [{'project_id': 'ZZZZZZ', 'task_id': '20190317_2', 'phase': 'acceptance', ...
print(type(response))
# <class 'requests.models.Response'>
print(response.headers["Content-Type"])
# application/json
service.wrapperのサンプルコード
service.wrapperには、server.apiを組み合わせたメソッドが定義されています。
# `status`が`complete`のタスクすべてを取得する
tasks = service.wrapper.get_all_tasks(project_id, query_params={"status": "complete"})
print(type(tasks))
# <class 'list'>
print(tasks)
# [{'project_id': 'ZZZZZZ', 'task_id': '20190317_2', 'phase': 'acceptance', ...
# simpleアノテーションzipのダウンロード
service.wrapper.download_annotation_archive(project_id, 'output_dir')
# 画像ファイルを入力データとして登録する
service.wrapper.put_input_data_from_file(project_id, 'sample_input_data_id', f'sample.png')
アノテーションzipの読み込み
ダウンロードしたアノテーションzipを、JSONファイルごとに読み込みます。 zipファイルを展開したディレクトリも読み込み可能です。
import zipfile
from pathlib import Path
from annofabapi.parser import lazy_parse_simple_annotation_dir, lazy_parse_simple_annotation_zip, SimpleAnnotationZipParser, SimpleAnnotationDirParser, lazy_parse_simple_annotation_zip_by_task
# Simpleアノテーションzipの読み込み
iter_parser = lazy_parse_simple_annotation_zip(Path("simple-annotation.zip"))
for parser in iter_parser:
simple_annotation = parser.parse()
print(simple_annotation)
# Simpleアノテーションzipを展開したディレクトリの読み込み
iter_parser = lazy_parse_simple_annotation_dir(Path("simple-annotation-dir"))
for parser in iter_parser:
simple_annotation = parser.parse()
print(simple_annotation)
# Simpleアノテーションzipをタスク単位で読み込む
task_iter_parser = lazy_parse_simple_annotation_zip_by_task(Path("simple-annotation.zip"))
for task_parser in task_iter_parser:
print(task_parser.task_id)
for parser in task_parser.lazy_parse():
simple_annotation = parser.parse()
print(simple_annotation)
# Simpleアノテーションzip内の1個のJSONファイルを読み込み
with zipfile.ZipFile('simple-annotation.zip', 'r') as zip_file:
parser = SimpleAnnotationZipParser(zip_file, "task01/12345678-abcd-1234-abcd-1234abcd5678.json")
simple_annotation = parser.parse()
print(simple_annotation)
# Simpleアノテーションzip内を展開したディレクトリ内の1個のJSONファイルを読み込み
parser = SimpleAnnotationDirParser(Path("task01/12345678-abcd-1234-abcd-1234abcd5678.json"))
simple_annotation = parser.parse()
print(simple_annotation)
塗りつぶし画像の読み込み
annofabapi.segmentation には、アノテーションZIPに格納されている塗りつぶし画像を扱うための関数が用意されています。
利用する場合は、以下のコマンドを実行してください。
$ pip install annofabapi[segmentation]
DataClass
annofabapi.dataclassに、データ構造用のクラスがあります。
これらのクラスを利用すれば、属性で各値にアクセスできます。
from annofabapi.dataclass.task import Task
dict_task, _ = service.api.get_task(project_id, task_id)
task = Task.from_dict(dict_task)
print(task.task_id)
print(task.status)
備考
annofabapiのログを出力する方法（サンプル）
import logging
logging_formatter = '%(levelname)-8s : %(asctime)s : %(name)s : %(message)s'
logging.basicConfig(format=logging_formatter)
logging.getLogger("annofabapi").setLevel(level=logging.DEBUG)
3 maintainers
Metadata
3 maintainers
Release files for annofabapi 1.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| annofabapi-1.8.0.tar.gz | 548.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| annofabapi-1.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.4 MB
Release files / annofabapi-1.8.0.tar.gz
| Download URL | annofabapi-1.8.0.tar.gz |
|---|---|
| Size | 548.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1c08fe12a8d1f898b7c88cd9d06668adcc97f41fcd19ed379078cced52e3b01a
|
|
BLAKE2b-256 checksum How to use checksums |
cf2c5a1ac46e1f39e1e92647a81e4b683d4189357694c4fb31e13d9032efa21a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.14
|
Release files / annofabapi-1.8.0-py3-none-any.whl
| Download URL | annofabapi-1.8.0-py3-none-any.whl |
|---|---|
| Size | 809.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c25fe2ba9883148a15150b259132d8459517fbc431b3250af20892573963f98d
|
|
BLAKE2b-256 checksum How to use checksums |
9acef975753b38de8c4c881c5a1cf04a7cb1b8cf509ffb2523f72113891ff2b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.14
|
