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

README.md

@@ -2665,6 +2665,17 @@ annotation_id = client.create_annotation(
     project="YOUR_PROJECT_SLUG", type="bbox", value="cat", title="Cat", color="#FF0000", attributes=attributes)
 ```
 
+Create a new segmentation annotation that allows disjoint regions.
+
+`max_area_count` is the maximum number of separate regions a single segmentation annotation may
+consist of, between 1 and 1000. It only applies to segmentation classes and defaults to `1`, which
+disallows disjoint regions. Set `None` to allow any number of regions.
+
+```python
+annotation_id = client.create_annotation(
+    project="YOUR_PROJECT_SLUG", type="segmentation", value="cat", title="Cat", max_area_count=None)
+```
+
 Create a new classification annotation.
 
 ```python
@@ -2831,6 +2842,16 @@ annotation_id = client.update_annotation(
     annotation_id="YOUR_ANNOTATION_ID", value="cat2", title="Cat2", color="#FF0000", attributes=attributes)
 ```
 
+Update the maximum number of regions of a segmentation annotation.
+
+`max_area_count` accepts a value between 1 and 1000 and is left unchanged when omitted. Set `None`
+to allow any number of regions.
+
+```python
+annotation_id = client.update_annotation(
+    annotation_id="YOUR_ANNOTATION_ID", max_area_count=None)
+```
+
 Update a classification annotation.
 
 ```python

fastlabel/__init__.py

@@ -39,6 +39,38 @@
 )
 
 
+class _Unset:
+    """Marker for arguments the caller did not pass.
+
+    Most optional arguments here have two states and None covers the second
+    one: the field is either sent or left out. maxAreaCount has three, because
+    the API represents "unlimited" as null rather than as 0, so null is itself
+    a value that has to reach the API -- left out, sent as null, sent as a
+    number. None is taken up by that null and cannot also mean "the caller
+    said nothing", so this marker carries that state instead and the argument
+    is read by identity rather than by truthiness.
+
+    A single shared instance, so that the identity checks that read this
+    marker still hold after it has been copied or serialised on its way
+    through caller code.
+    """
+
+    _instance: Optional["_Unset"] = None
+
+    def __new__(cls) -> "_Unset":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+
+# Typed as Any so that the marker stays out of the public signatures that use it
+# as their default. Callers only ever pass an int or None.
+_UNSET: Any = _Unset()
+
+
 class Client:
     api = None
 
@@ -4297,6 +4329,7 @@ def create_annotation(
         color: str = None,
         order: int = None,
         attributes: list = [],
+        max_area_count: Optional[int] = _UNSET,
     ) -> str:
         """
         Create an annotation.
@@ -4308,6 +4341,11 @@ def create_annotation(
         title is a display name of value (Required).
         color is hex color code like #ffffff (Optional).
         attributes is a list of attribute (Optional).
+        max_area_count is the maximum number of separate regions a single
+        segmentation annotation may consist of, between 1 and 1000 (Optional).
+        It only applies to segmentation classes. When omitted the API applies
+        its default of 1, which disallows disjoint regions. Set None to allow
+        any number of regions.
         """
         endpoint = "annotations"
         payload = {
@@ -4322,6 +4360,13 @@ def create_annotation(
             payload["order"] = order
         if attributes:
             payload["attributes"] = attributes
+        # maxAreaCount represents "unlimited" as null rather than as 0, so
+        # passing None is itself a meaningful call and None cannot double as
+        # "not passed" the way it does for the other optional arguments. The
+        # three states are read by identity: left out keeps the API's default,
+        # None removes the limit, an int sets it.
+        if max_area_count is not _UNSET:
+            payload["maxAreaCount"] = max_area_count
         return self.api.post_request(endpoint, payload=payload)
 
     def create_classification_annotation(self, project: str, attributes: list) -> str:
@@ -4343,6 +4388,7 @@ def update_annotation(
         color: str = None,
         order: int = None,
         attributes: list = [],
+        max_area_count: Optional[int] = _UNSET,
     ) -> str:
         """
         Update an annotation.
@@ -4352,6 +4398,10 @@ def update_annotation(
         title is a display name of value (Optional).
         color is hex color code like #ffffff (Optional).
         attributes is a list of attribute (Optional).
+        max_area_count is the maximum number of separate regions a single
+        segmentation annotation may consist of, between 1 and 1000 (Optional).
+        It only applies to segmentation classes and is left unchanged when
+        omitted. Set None to allow any number of regions.
         """
         endpoint = "annotations/" + annotation_id
         payload = {}
@@ -4365,6 +4415,13 @@ def update_annotation(
             payload["order"] = order
         if attributes:
             payload["attributes"] = attributes
+        # maxAreaCount represents "unlimited" as null rather than as 0, so
+        # passing None is itself a meaningful call and None cannot double as
+        # "not passed" the way it does for the other optional arguments. The
+        # three states are read by identity: left out keeps the stored value,
+        # None removes the limit, an int sets it.
+        if max_area_count is not _UNSET:
+            payload["maxAreaCount"] = max_area_count
         return self.api.put_request(endpoint, payload=payload)
 
     def update_classification_annotation(

tests/conftest.py

@@ -4,6 +4,8 @@
 import numpy as np
 import pytest
 
+import fastlabel
+
 
 def _write_synthetic_video(
     path: Path,
@@ -48,3 +50,26 @@ def _factory(
         )
 
     return _factory
+
+
+@pytest.fixture
+def client(monkeypatch):
+    monkeypatch.setenv("FASTLABEL_ACCESS_TOKEN", "dummy-token")
+    return fastlabel.Client()
+
+
+@pytest.fixture
+def capture_request(monkeypatch):
+    """Replace an api.*_request method with a recorder and return the calls list."""
+
+    def _factory(client, method_name, return_value=None):
+        calls = []
+
+        def fake(endpoint, *args, **kwargs):
+            calls.append({"endpoint": endpoint, "args": args, "kwargs": kwargs})
+            return return_value
+
+        monkeypatch.setattr(client.api, method_name, fake)
+        return calls
+
+    return _factory

tests/test_annotation.py

@@ -0,0 +1,119 @@
+"""Tests for the annotation class API client methods.
+
+These verify that create_annotation and update_annotation build the correct
+endpoint and payload, with a focus on max_area_count. The HTTP layer
+(client.api.*_request) is stubbed so no real request is made.
+"""
+
+import copy
+import pickle
+
+import pytest
+
+import fastlabel
+
+# --- create_annotation -----------------------------------------------------
+
+
+def test_create_annotation_omits_max_area_count_by_default(client, capture_request):
+    calls = capture_request(client, "post_request", return_value="anno-id")
+
+    client.create_annotation(
+        project="my-project", type="segmentation", value="cat", title="Cat"
+    )
+
+    # The field is left out entirely so the API applies its own default of 1
+    assert calls[0]["endpoint"] == "annotations"
+    assert calls[0]["kwargs"]["payload"] == {
+        "project": "my-project",
+        "type": "segmentation",
+        "value": "cat",
+        "title": "Cat",
+    }
+
+
+def test_create_annotation_with_max_area_count(client, capture_request):
+    calls = capture_request(client, "post_request", return_value="anno-id")
+
+    client.create_annotation(
+        project="my-project",
+        type="segmentation",
+        value="cat",
+        title="Cat",
+        max_area_count=10,
+    )
+
+    assert calls[0]["kwargs"]["payload"]["maxAreaCount"] == 10
+
+
+def test_create_annotation_without_max_area_count_limit(client, capture_request):
+    calls = capture_request(client, "post_request", return_value="anno-id")
+
+    client.create_annotation(
+        project="my-project",
+        type="segmentation",
+        value="cat",
+        title="Cat",
+        max_area_count=None,
+    )
+
+    # None is sent as an explicit null, which means no limit on the server side
+    assert calls[0]["kwargs"]["payload"]["maxAreaCount"] is None
+
+
+# --- update_annotation -----------------------------------------------------
+
+
+def test_update_annotation_omits_max_area_count_by_default(client, capture_request):
+    calls = capture_request(client, "put_request", return_value="anno-id")
+
+    client.update_annotation(annotation_id="anno-id", title="Cat")
+
+    assert calls[0]["endpoint"] == "annotations/anno-id"
+    assert calls[0]["kwargs"]["payload"] == {"title": "Cat"}
+
+
+def test_update_annotation_with_max_area_count(client, capture_request):
+    calls = capture_request(client, "put_request", return_value="anno-id")
+
+    client.update_annotation(annotation_id="anno-id", max_area_count=10)
+
+    assert calls[0]["kwargs"]["payload"] == {"maxAreaCount": 10}
+
+
+def test_update_annotation_without_max_area_count_limit(client, capture_request):
+    calls = capture_request(client, "put_request", return_value="anno-id")
+
+    client.update_annotation(annotation_id="anno-id", max_area_count=None)
+
+    # None is sent as an explicit null, which means no limit on the server side
+    assert calls[0]["kwargs"]["payload"] == {"maxAreaCount": None}
+
+
+# --- the "not passed" marker -----------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "round_trip",
+    [copy.deepcopy, lambda value: pickle.loads(pickle.dumps(value))],
+    ids=["deepcopy", "pickle"],
+)
+def test_create_annotation_keeps_marker_meaning_after_round_trip(
+    client, capture_request, round_trip
+):
+    calls = capture_request(client, "post_request", return_value="anno-id")
+
+    # Callers that collect keyword arguments and pass them around must still
+    # get "omitted" out of the default, which relies on the marker's identity
+    kwargs = round_trip(
+        {
+            "project": "my-project",
+            "type": "segmentation",
+            "value": "cat",
+            "title": "Cat",
+            "max_area_count": fastlabel._UNSET,
+        }
+    )
+    client.create_annotation(**kwargs)
+
+    assert "maxAreaCount" not in calls[0]["kwargs"]["payload"]