アノテーションクラスの領域数上限を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 を渡さない従来どおりの呼び出しを確認しています。

[h-iwata]

他の箇所では0が無制限、Noneがデフォルトという実装になっており、
_UNSET = デフォルト
という実装について理解に非常に時間がかかりました。
大抵の場合は0が無制限を表し、省略時はデフォルト値を表します。

今回の実装については、maxAreaCountのdb側が無制限= nullだからUNSETという新しい概念を追加したという判断で合ってますか？
かなり特殊な実装なので、なぜこのような実装になっているかコメントがほしいです。次に実装する人が混乱します

[soymd]

ご認識のとおりです。maxAreaCount は無制限が null で、null 自体が API へ送る値になるため None が「未指定」を兼ねられず、省略 / null / 整数の三値になっています。

他の項目の二値の慣習から外れる点はご指摘どおりなので、マーカーの定義側と create / update 双方の使用箇所に、三値であることとそれぞれの意味をコメントで残しました。

[h-iwata]

maxAreaCount は無制限が null で、null 自体が API へ送る値になるため None が「未指定」を兼ねられず、省略 / null / 整数の三値になっています。
という点がコメントで確認できませんでした。

この点がないと、次の実装者がdbまで見に行かないと実装意図がわかりません

[h-iwata]

sdkは全てのコメントが英語で書かれているので英語でお願いしますー

[soymd]

英語に戻しました！

[h-iwata]

このようなセンチネルはsdkとして公開する都合上、念のためシングルトンにしておいた方がいいですね。copy.deepcopy や pickle を通ると is 判定が壊れて _Unset が payload に載ってしまうので。

シングルトンとしては普通にこんな感じ

  _instance = None

    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

[soymd]

シングルトンにしました。deepcopy / pickle を往復しても is 判定が保たれ、payload にマーカーが載らないことをテストで固定しています。

[h-iwata]

maxAreaCount は無制限が null で、null 自体が API へ送る値になるため None が「未指定」を兼ねられず、省略 / null / 整数の三値になっています。
という点がコメントで確認できませんでした。

この点がないと、次の実装者がdbまで見に行かないと実装意図がわかりません

[soymd]

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

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

[h-iwata]

sdkは全てのコメントが英語で書かれているので英語でお願いしますー