feat: support setting task ID on creation

Adds a `task_id` argument to create_task/Task.create, letting callers assign
a UUID or shortened UUID. The ID is passed through to the server, which
validates uniqueness.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: snopoke

taskbadger.yaml

@@ -685,6 +685,11 @@ components:
     PatchedTaskRequest:
       type: object
       properties:
+        id:
+          type: string
+          minLength: 1
+          description: Task ID. May be set on creation to a UUID or shortened UUID;
+            it must be unique and is immutable thereafter. If omitted, an ID is generated.
         name:
           type: string
           minLength: 1
@@ -778,8 +783,8 @@ components:
       properties:
         id:
           type: string
-          readOnly: true
-          description: Task ID
+          description: Task ID. May be set on creation to a UUID or shortened UUID;
+            it must be unique and is immutable thereafter. If omitted, an ID is generated.
         organization:
           type: string
           readOnly: true
@@ -873,7 +878,6 @@ components:
             to 'value'.
       required:
       - created
-      - id
       - name
       - organization
       - project
@@ -884,6 +888,11 @@ components:
     TaskRequest:
       type: object
       properties:
+        id:
+          type: string
+          minLength: 1
+          description: Task ID. May be set on creation to a UUID or shortened UUID;
+            it must be unique and is immutable thereafter. If omitted, an ID is generated.
         name:
           type: string
           minLength: 1

taskbadger/internal/models/patched_task_request.py

@@ -22,6 +22,8 @@
 class PatchedTaskRequest:
     """
     Attributes:
+        id (str | Unset): Task ID. May be set on creation to a UUID or shortened UUID; it must be unique and is
+            immutable thereafter. If omitted, an ID is generated.
         name (str | Unset): Name of the task
         queue (str | Unset): Queue the task is from
         status (StatusEnum | Unset): * `pending` - pending
@@ -48,6 +50,7 @@ class PatchedTaskRequest:
         tags (PatchedTaskRequestTags | Unset): Tags for the task represented as a mapping from 'namespace' to 'value'.
     """
 
+    id: str | Unset = UNSET
     name: str | Unset = UNSET
     queue: str | Unset = UNSET
     status: StatusEnum | Unset = StatusEnum.PENDING
@@ -65,6 +68,8 @@ class PatchedTaskRequest:
     def to_dict(self) -> dict[str, Any]:
         from ..models.patched_task_request_tags import PatchedTaskRequestTags
 
+        id = self.id
+
         name = self.name
 
         queue = self.queue
@@ -124,6 +129,8 @@ def to_dict(self) -> dict[str, Any]:
         field_dict: dict[str, Any] = {}
         field_dict.update(self.additional_properties)
         field_dict.update({})
+        if id is not UNSET:
+            field_dict["id"] = id
         if name is not UNSET:
             field_dict["name"] = name
         if queue is not UNSET:
@@ -156,6 +163,8 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
         from ..models.patched_task_request_tags import PatchedTaskRequestTags
 
         d = dict(src_dict)
+        id = d.pop("id", UNSET)
+
         name = d.pop("name", UNSET)
 
         queue = d.pop("queue", UNSET)
@@ -249,6 +258,7 @@ def _parse_stale_timeout(data: object) -> int | None | Unset:
             tags = PatchedTaskRequestTags.from_dict(_tags)
 
         patched_task_request = cls(
+            id=id,
             name=name,
             queue=queue,
             status=status,

taskbadger/internal/models/task.py

@@ -22,7 +22,6 @@
 class Task:
     """
     Attributes:
-        id (str): Task ID
         organization (str):
         project (str):
         name (str): Name of the task
@@ -31,6 +30,8 @@ class Task:
         updated (datetime.datetime):
         url (str):
         public_url (str):
+        id (str | Unset): Task ID. May be set on creation to a UUID or shortened UUID; it must be unique and is
+            immutable thereafter. If omitted, an ID is generated.
         queue (str | Unset): Queue the task is from
         status (StatusEnum | Unset): * `pending` - pending
             * `pre_processing` - pre_processing
@@ -56,7 +57,6 @@ class Task:
         tags (TaskTags | Unset): Tags for the task represented as a mapping from 'namespace' to 'value'.
     """
 
-    id: str
     organization: str
     project: str
     name: str
@@ -65,6 +65,7 @@ class Task:
     updated: datetime.datetime
     url: str
     public_url: str
+    id: str | Unset = UNSET
     queue: str | Unset = UNSET
     status: StatusEnum | Unset = StatusEnum.PENDING
     value: int | None | Unset = UNSET
@@ -81,8 +82,6 @@ class Task:
     def to_dict(self) -> dict[str, Any]:
         from ..models.task_tags import TaskTags
 
-        id = self.id
-
         organization = self.organization
 
         project = self.project
@@ -100,6 +99,8 @@ def to_dict(self) -> dict[str, Any]:
 
         public_url = self.public_url
 
+        id = self.id
+
         queue = self.queue
 
         status: str | Unset = UNSET
@@ -158,7 +159,6 @@ def to_dict(self) -> dict[str, Any]:
         field_dict.update(self.additional_properties)
         field_dict.update(
             {
-                "id": id,
                 "organization": organization,
                 "project": project,
                 "name": name,
@@ -169,6 +169,8 @@ def to_dict(self) -> dict[str, Any]:
                 "public_url": public_url,
             }
         )
+        if id is not UNSET:
+            field_dict["id"] = id
         if queue is not UNSET:
             field_dict["queue"] = queue
         if status is not UNSET:
@@ -199,8 +201,6 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
         from ..models.task_tags import TaskTags
 
         d = dict(src_dict)
-        id = d.pop("id")
-
         organization = d.pop("organization")
 
         project = d.pop("project")
@@ -222,6 +222,8 @@ def _parse_value_percent(data: object) -> int | None:
 
         public_url = d.pop("public_url")
 
+        id = d.pop("id", UNSET)
+
         queue = d.pop("queue", UNSET)
 
         _status = d.pop("status", UNSET)
@@ -313,7 +315,6 @@ def _parse_stale_timeout(data: object) -> int | None | Unset:
             tags = TaskTags.from_dict(_tags)
 
         task = cls(
-            id=id,
             organization=organization,
             project=project,
             name=name,
@@ -322,6 +323,7 @@ def _parse_stale_timeout(data: object) -> int | None | Unset:
             updated=updated,
             url=url,
             public_url=public_url,
+            id=id,
             queue=queue,
             status=status,
             value=value,

taskbadger/internal/models/task_request.py

@@ -23,6 +23,8 @@ class TaskRequest:
     """
     Attributes:
         name (str): Name of the task
+        id (str | Unset): Task ID. May be set on creation to a UUID or shortened UUID; it must be unique and is
+            immutable thereafter. If omitted, an ID is generated.
         queue (str | Unset): Queue the task is from
         status (StatusEnum | Unset): * `pending` - pending
             * `pre_processing` - pre_processing
@@ -49,6 +51,7 @@ class TaskRequest:
     """
 
     name: str
+    id: str | Unset = UNSET
     queue: str | Unset = UNSET
     status: StatusEnum | Unset = StatusEnum.PENDING
     value: int | None | Unset = UNSET
@@ -67,6 +70,8 @@ def to_dict(self) -> dict[str, Any]:
 
         name = self.name
 
+        id = self.id
+
         queue = self.queue
 
         status: str | Unset = UNSET
@@ -128,6 +133,8 @@ def to_dict(self) -> dict[str, Any]:
                 "name": name,
             }
         )
+        if id is not UNSET:
+            field_dict["id"] = id
         if queue is not UNSET:
             field_dict["queue"] = queue
         if status is not UNSET:
@@ -160,6 +167,8 @@ def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
         d = dict(src_dict)
         name = d.pop("name")
 
+        id = d.pop("id", UNSET)
+
         queue = d.pop("queue", UNSET)
 
         _status = d.pop("status", UNSET)
@@ -252,6 +261,7 @@ def _parse_stale_timeout(data: object) -> int | None | Unset:
 
         task_request = cls(
             name=name,
+            id=id,
             queue=queue,
             status=status,
             value=value,

taskbadger/sdk.py

@@ -152,6 +152,7 @@ def create_task(
     monitor_id: str = None,
     tags: dict[str, str] = None,
     queue: str = None,
+    task_id: str = None,
 ) -> "Task":
     """Create a Task.
 
@@ -167,6 +168,8 @@ def create_task(
         monitor_id: ID of the monitor to associate this task with.
         tags: Dictionary of namespace -> value tags.
         queue: Name of the queue the task is from.
+        task_id: ID to assign to the task. May be a UUID or shortened UUID; it must be
+            unique and is immutable. If omitted, an ID is generated by the server.
 
     Returns:
         Task: The created Task object.
@@ -175,6 +178,8 @@ def create_task(
         "name": name,
         "status": status,
     }
+    if task_id is not None:
+        task_dict["id"] = task_id
     if queue is not None:
         task_dict["queue"] = queue
     if value is not None:
@@ -335,6 +340,7 @@ def create(
         monitor_id: str = None,
         tags: dict[str, str] = None,
         queue: str = None,
+        task_id: str = None,
     ) -> "Task":
         """Create a new task
 
@@ -352,6 +358,7 @@ def create(
             monitor_id=monitor_id,
             tags=tags,
             queue=queue,
+            task_id=task_id,
         )
 
     def __init__(self, task):

tests/test_sdk.py

@@ -114,6 +114,22 @@ def test_create_with_queue(settings, patched_create):
     )
 
 
+def test_create_with_task_id(settings, patched_create):
+    api_task = task_for_test()
+    patched_create.return_value = Response(HTTPStatus.OK, b"", {}, api_task)
+
+    task_id = "b3f8c1e2-1234-4a5b-8c9d-0e1f2a3b4c5d"
+    Task.create(name="task name", task_id=task_id)
+
+    request = TaskRequest(name="task name", status=StatusEnum.PENDING, id=task_id)
+    patched_create.assert_called_with(
+        client=mock.ANY,
+        organization_slug="org",
+        project_slug="project",
+        body=request,
+    )
+
+
 def test_update_queue(settings, patched_update):
     api_task = task_for_test()
     task = Task(api_task)

tests/utils.py

@@ -15,9 +15,9 @@ def task_for_test(**kwargs):
     kwargs["created"] = datetime.datetime.now(datetime.timezone.utc)
     kwargs["updated"] = datetime.datetime.now(datetime.timezone.utc)
     return TaskInternal(
-        task_id,
         "org",
         "project",
         "task_name",
+        id=task_id,
         **kwargs,
     )