アノテーションクラスの領域数上限をSDKから指定できるようにする

[soymd]

概要

アノテーションクラスの「1アノテーションあたりの領域数上限」（maxAreaCount）を、SDKから指定・変更できるようにしました。

これまでSDKでアノテーションクラスを作成すると、この値がAPI側で常に 1 に固定されていました。1 だと飛び地のセグメンテーションができないため、SDKでクラスを同期している案件では、作成後に画面から1クラスずつ「なし」に直す必要がありました。更新メソッドでも変更できず、既存クラスをまとめて直す手段もありませんでした。

省略時の値は従来どおり 1 です（API側の既定値）。既存の連携の振る舞いが変わらないようにするためです。

対応内容

• create_annotation に max_area_count を追加。省略時はリクエストに含めず、API側の既定値 1 に委ねる。None を指定すると「なし」（無制限）、整数を指定するとその値
• update_annotation に max_area_count を追加。省略時はリクエストに含めないため変更されず、None を指定すると「なし」（無制限）
• 既存の引数の並びは変えず、いずれも末尾に追加しています
• READMEに使用例と有効範囲（1〜1000）を追記

作成・更新のどちらも「引数を渡さなかった」と「None を渡した」を区別する必要があります。None は「上限なし」という意味でAPIへ送る値なので、「未指定」の意味を兼ねられません。そのためモジュール内にセンチネル _UNSET を置き、それ以外が渡されたときだけ maxAreaCount をリクエストに載せています。センチネルの型注釈は Any にして、公開されるシグネチャが Optional[int] のままになるようにしています。

有効範囲（1〜1000）と整数かどうかの検証はAPI側に委ねています（422が返ります）。同じ Client に limit などをクライアント側で弾く例はありますが、上限値をリポジトリを跨いで二重に持たないほうがよいと判断しました。

テスト

• tests/test_annotation.py を追加。作成・更新それぞれで、省略時にキーを送らないこと、None と整数がそのまま載ることを検証
• テスト用の client fixture とリクエスト記録ヘルパーを tests/conftest.py へ移動。tests/test_workspace_user.py に同じものが定義されていたため、そちらも共有fixtureを使う形に書き換えています（振る舞いの変更はありません）

依存

API側の対応（fastlabel/fastlabel-application#11670）のリリース後に、このPRをマージ・リリースしてください。max_area_count を指定したときだけAPI側の対応が必要で、指定しない既存の呼び出しはリクエスト内容が従来と同一のため、API側のリリース前でも影響ありません。

• fastlabel/fastlabel-application#11670
• fastlabel/fastlabel-application#11669

動作確認

pytest tests/            # 20 passed
black --check . && flake8 . && isort --check .

CIはlintとPython 3.10〜3.14のマトリクスが全てpassしています。

あわせて、ローカル環境のAPI（#11670 のブランチのコード）に対してこのSDKから実際にリクエストを投げ、作成（省略時 1 / None / 整数 / 境界値 / 範囲外は422）、更新（省略時は変更なし / None / 整数 / 範囲外は422で既存値も変わらない）、読み出し、max_area_count を渡さない従来どおりの呼び出しを確認しています。

[soymd]

@h-iwata san
すみません意図汲み取れておりませんでした
以下のコメントを書くようにしておりますので確認お願いいたします

このモジュールの任意引数は大半が「送る / 送らない」の二値で、後者を None
    が兼ねられる。一方、null 自体が API へ送る意味のある値になる引数 (領域数
    上限 maxAreaCount は 0 ではなく null が「無制限」を表す) は「省略 / null /
    値」の三値になる。この場合 None は API へ届ける null の側に取られるため
    「呼び出し側が何も言わなかった」を表せず、その状態をこのマーカーが担う。