pytaskwarrior 2.0.4__tar.gz → 2.0.5__tar.gz

{pytaskwarrior-2.0.4 → pytaskwarrior-2.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytaskwarrior
-Version: 2.0.4
+Version: 2.0.5
 Summary: Taskwarrior wrapper python module
 Author-email: sznicolas <sznicolas@users.noreply.github.com>
 License-Expression: MIT

{pytaskwarrior-2.0.4 → pytaskwarrior-2.0.5}/README.md

@@ -119,15 +119,18 @@ tw = TaskWarrior(
 | Method | Description |
 |--------|-------------|
 | `add_task(task: TaskInputDTO)` | Create a new task |
-| `get_task(uuid)` | Get a single task by UUID or ID |
+| `get_task(task_ref)` | Get a single task by UUID, ID, or TaskID |
 | `get_tasks(filter="", include_completed=False, include_deleted=False)` | Get tasks matching filter |
-| `modify_task(task: TaskInputDTO, uuid)` | Modify an existing task |
-| `delete_task(uuid)` | Mark task as deleted |
-| `purge_task(uuid)` | Permanently remove task |
-| `done_task(uuid)` | Mark task as completed |
-| `start_task(uuid)` | Start working on task |
-| `stop_task(uuid)` | Stop working on task |
-| `annotate_task(uuid, annotation)` | Add annotation to task |
+| `modify_task(task: TaskInputDTO, task_ref)` | Modify an existing task |
+| `delete_task(task_ref)` | Mark task as deleted |
+| `purge_task(task_ref)` | Permanently remove task |
+| `done_task(task_ref)` | Mark task as completed |
+| `start_task(task_ref)` | Start working on task |
+| `stop_task(task_ref)` | Stop working on task |
+| `annotate_task(task_ref, annotation)` | Add annotation to task |
+
+
+Note: "task_ref" accepts an integer working-set index, a UUID string/object, or a `TaskID` instance for clarity. `TaskID` is exported from the top-level package and can be used to create explicit references (e.g., `TaskID(1)`, `TaskID(uuid_obj)`).
 
 #### Tags Operations
 

{pytaskwarrior-2.0.4 → pytaskwarrior-2.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pytaskwarrior"
-version = "2.0.4"
+version = "2.0.5"
 description = "Taskwarrior wrapper python module"
 readme = "PYPI_README.md"
 requires-python = ">=3.12"

{pytaskwarrior-2.0.4 → pytaskwarrior-2.0.5}/src/pytaskwarrior.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytaskwarrior
-Version: 2.0.4
+Version: 2.0.5
 Summary: Taskwarrior wrapper python module
 Author-email: sznicolas <sznicolas@users.noreply.github.com>
 License-Expression: MIT

{pytaskwarrior-2.0.4 → pytaskwarrior-2.0.5}/src/pytaskwarrior.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ src/taskwarrior/dto/__init__.py
 src/taskwarrior/dto/annotation_dto.py
 src/taskwarrior/dto/context_dto.py
 src/taskwarrior/dto/task_dto.py
+src/taskwarrior/dto/task_id.py
 src/taskwarrior/dto/uda_dto.py
 src/taskwarrior/registry/__init__.py
 src/taskwarrior/registry/uda_registry.py

{pytaskwarrior-2.0.4 → pytaskwarrior-2.0.5}/src/taskwarrior/__init__.py

@@ -37,6 +37,7 @@ import importlib.metadata
 from .dto.annotation_dto import AnnotationDTO
 from .dto.context_dto import ContextDTO
 from .dto.task_dto import TaskInputDTO, TaskOutputDTO
+from .dto.task_id import TaskID
 from .dto.uda_dto import UdaConfig, UdaType
 from .enums import Priority, RecurrencePeriod, TaskStatus
 from .exceptions import (
@@ -61,6 +62,7 @@ __all__ = [
     "version",
     "Priority",
     "RecurrencePeriod",
+    "TaskID",
     "TaskStatus",
     "TaskConfigurationError",
     "TaskInputDTO",

{pytaskwarrior-2.0.4 → pytaskwarrior-2.0.5}/src/taskwarrior/adapters/taskwarrior_adapter.py

@@ -14,6 +14,7 @@ from uuid import UUID
 
 from ..config.config_store import ConfigStore
 from ..dto.task_dto import TaskInputDTO, TaskOutputDTO
+from ..dto.task_id import TaskID, TaskRef
 from ..enums import TaskStatus
 from ..exceptions import (
     TaskConfigurationError,
@@ -26,6 +27,10 @@ from ..exceptions import (
 
 logger = logging.getLogger(__name__)
 
+def _to_taskid(value: TaskRef) -> TaskID:
+    """Normalize a TaskRef into a TaskID instance."""
+    return value if isinstance(value, TaskID) else TaskID(value)
+
 TASKWARRIOR_VIRTUAL_TAGS: tuple[str, ...] = (
     "BLOCKED",
     "UNBLOCKED",
@@ -258,28 +263,29 @@ class TaskWarriorAdapter:
         logger.info(f"Successfully added task with UUID: {added_task.uuid}")
         return added_task
 
-    def modify_task(self, task: TaskInputDTO, task_id_or_uuid: str | int | UUID) -> TaskOutputDTO:
+    def modify_task(self, task: TaskInputDTO, task_id: str | int | UUID | TaskID) -> TaskOutputDTO:
         """Modify an existing task. Returns the updated task."""
-        logger.info(f"Modifying task with UUID: {task_id_or_uuid}")
+        logger.info(f"Modifying task with UUID: {task_id}")
+        tid = _to_taskid(task_id)
 
         args = self._build_args(task)
-        result = self.run_task_command([str(task_id_or_uuid), "modify"] + args)
+        result = self.run_task_command([str(tid), "modify"] + args)
 
         if result.returncode != 0:
             error_msg = f"Failed to modify task: {result.stderr}"
             logger.error(error_msg)
             raise TaskWarriorError(error_msg)
 
-        updated_task = self.get_task(task_id_or_uuid)
-        logger.info(f"Successfully modified task with UUID: {task_id_or_uuid}")
+        updated_task = self.get_task(tid)
+        logger.info(f"Successfully modified task with UUID: {tid}")
         return updated_task
 
-    def get_task(self, task_id_or_uuid: str | int | UUID, filter_args: str = "") -> TaskOutputDTO:
+    def get_task(self, task_id: str | int | UUID | TaskID, filter_args: str = "") -> TaskOutputDTO:
         """Retrieve a single task by ID or UUID."""
-        task_id_or_uuid = str(task_id_or_uuid)
-        logger.debug(f"Retrieving task with ID/UUID: {task_id_or_uuid}")
+        tid = _to_taskid(task_id)
+        logger.debug(f"Retrieving task with ID/UUID: {tid}")
 
-        args = [filter_args, task_id_or_uuid, "export"]
+        args = [filter_args, str(tid), "export"]
         result = self.run_task_command(args)
         if result.returncode == 0:
             try:
@@ -290,17 +296,17 @@ class TaskWarriorAdapter:
                     return task
                 elif len(tasks_data) == 0:
                     raise TaskNotFound(
-                        f"No task ID/UUID {task_id_or_uuid} with filter {filter_args}"
+                        f"No task ID/UUID {tid} with filter {filter_args}"
                     )
                 else:
                     raise TaskWarriorError(
-                        f"More than one task returned for ID/UUID {task_id_or_uuid} with filter '{filter_args}'"
+                        f"More than one task returned for ID/UUID {tid} with filter '{filter_args}'"
                     )
             except json.JSONDecodeError as e:
                 logger.error(f"Failed to parse JSON response: {e}")
                 raise TaskWarriorError(f"Invalid response from TaskWarrior: {result.stdout}") from e
         else:
-            raise TaskNotFound(f"Task ID/UUID {task_id_or_uuid} not found")
+            raise TaskNotFound(f"Task ID/UUID {tid} not found")
 
     def get_tasks(
         self,
@@ -364,13 +370,13 @@ class TaskWarriorAdapter:
             logger.error(f"Failed to parse JSON response: {e}")
             raise TaskWarriorError(f"Invalid response from TaskWarrior: {result.stdout}") from e
 
-    def get_recurring_task(self, task_id_or_uuid: str | int | UUID) -> TaskOutputDTO:
+    def get_recurring_task(self, task_id: str | int | UUID | TaskID) -> TaskOutputDTO:
         """Get the parent recurring task template."""
-        task_id_or_uuid = str(task_id_or_uuid)
-        logger.debug(f"Getting recurring task with UUID: {task_id_or_uuid}")
+        tid = _to_taskid(task_id)
+        logger.debug(f"Getting recurring task with UUID: {tid}")
 
         result = self.run_task_command(
-            [str(task_id_or_uuid), "status:" + TaskStatus.RECURRING, "export"]
+            [str(tid), "status:" + TaskStatus.RECURRING, "export"]
         )
 
         if result.returncode == 0:
@@ -385,16 +391,16 @@ class TaskWarriorAdapter:
                 return task
 
         logger.debug(
-            f"Recurring task {task_id_or_uuid} not found as recurring, trying normal retrieval"
+            f"Recurring task {tid} not found as recurring, trying normal retrieval"
         )
-        return self.get_task(task_id_or_uuid)
+        return self.get_task(tid)
 
-    def get_recurring_instances(self, task_id_or_uuid: str | int | UUID) -> list[TaskOutputDTO]:
+    def get_recurring_instances(self, task_id: str | int | UUID | TaskID) -> list[TaskOutputDTO]:
         """Get all instances of a recurring task."""
-        task_id_or_uuid = str(task_id_or_uuid)
-        logger.debug(f"Getting recurring instances for parent UUID: {task_id_or_uuid}")
+        tid = _to_taskid(task_id)
+        logger.debug(f"Getting recurring instances for parent UUID: {tid}")
 
-        result = self.run_task_command([f"parent:{str(task_id_or_uuid)}", "export"])
+        result = self.run_task_command([f"parent:{str(tid)}", "export"])
 
         if result.returncode != 0:
             if (
@@ -420,9 +426,9 @@ class TaskWarriorAdapter:
             logger.error(f"Failed to parse JSON response: {e}")
             raise TaskWarriorError(f"Invalid response from TaskWarrior: {result.stdout}") from e
 
-    def delete_task(self, task_id_or_uuid: str | int | UUID) -> None:
+    def delete_task(self, task_id: str | int | UUID | TaskID) -> None:
         """Mark a task as deleted."""
-        task_ref = str(task_id_or_uuid)
+        task_ref = str(_to_taskid(task_id))
         logger.info(f"Deleting task: {task_ref}")
 
         result = self.run_task_command([task_ref, "delete"])
@@ -434,9 +440,9 @@ class TaskWarriorAdapter:
 
         logger.info(f"Successfully deleted task: {task_ref}")
 
-    def purge_task(self, task_id_or_uuid: str | int | UUID) -> None:
+    def purge_task(self, task_id: str | int | UUID | TaskID) -> None:
         """Permanently remove a task."""
-        task_ref = str(task_id_or_uuid)
+        task_ref = str(_to_taskid(task_id))
         logger.info(f"Purging task: {task_ref}")
 
         result = self.run_task_command([task_ref, "purge"])
@@ -448,9 +454,9 @@ class TaskWarriorAdapter:
 
         logger.info(f"Successfully purged task: {task_ref}")
 
-    def done_task(self, task_id_or_uuid: str | int | UUID) -> None:
+    def done_task(self, task_id: str | int | UUID | TaskID) -> None:
         """Mark a task as completed."""
-        task_ref = str(task_id_or_uuid)
+        task_ref = str(_to_taskid(task_id))
         logger.info(f"Completing task: {task_ref}")
 
         result = self.run_task_command([task_ref, "done"])
@@ -462,9 +468,9 @@ class TaskWarriorAdapter:
 
         logger.info(f"Successfully completed task: {task_ref}")
 
-    def start_task(self, task_id_or_uuid: str | int | UUID) -> None:
+    def start_task(self, task_id: str | int | UUID | TaskID) -> None:
         """Start working on a task."""
-        task_ref = str(task_id_or_uuid)
+        task_ref = str(_to_taskid(task_id))
         logger.info(f"Starting task: {task_ref}")
 
         result = self.run_task_command([task_ref, "start"])
@@ -476,9 +482,9 @@ class TaskWarriorAdapter:
 
         logger.info(f"Successfully started task: {task_ref}")
 
-    def stop_task(self, task_id_or_uuid: str | int | UUID) -> None:
+    def stop_task(self, task_id: str | int | UUID | TaskID) -> None:
         """Stop working on a task."""
-        task_ref = str(task_id_or_uuid)
+        task_ref = str(_to_taskid(task_id))
         logger.info(f"Stopping task: {task_ref}")
 
         result = self.run_task_command([task_ref, "stop"])
@@ -490,9 +496,9 @@ class TaskWarriorAdapter:
 
         logger.info(f"Successfully stopped task: {task_ref}")
 
-    def annotate_task(self, task_id_or_uuid: str | int | UUID, annotation: str) -> None:
+    def annotate_task(self, task_id: str | int | UUID | TaskID, annotation: str) -> None:
         """Add an annotation to a task."""
-        task_ref = str(task_id_or_uuid)
+        task_ref = str(_to_taskid(task_id))
         logger.info(f"Annotating task {task_ref} with: {annotation}")
 
         sanitized_annotation = shlex.quote(annotation)

{pytaskwarrior-2.0.4 → pytaskwarrior-2.0.5}/src/taskwarrior/dto/__init__.py

@@ -1,5 +1,6 @@
 from .annotation_dto import AnnotationDTO
 from .context_dto import ContextDTO
 from .task_dto import TaskInputDTO, TaskOutputDTO
+from .task_id import TaskID
 
-__all__ = ["AnnotationDTO", "ContextDTO", "TaskInputDTO", "TaskOutputDTO"]
+__all__ = ["AnnotationDTO", "ContextDTO", "TaskID", "TaskInputDTO", "TaskOutputDTO"]

pytaskwarrior-2.0.5/src/taskwarrior/dto/task_id.py

@@ -0,0 +1,102 @@
+"""TaskID — unified identifier for a TaskWarrior task.
+
+A task can be referenced either by its working-set index (``int``) or by its
+persistent UUID.  This class wraps both forms under a single type so that
+every API method only needs one parameter type instead of ``str | int | UUID``.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from ..exceptions import TaskValidationError
+
+
+class TaskID:
+    """Unified identifier for a TaskWarrior task.
+
+    A ``TaskID`` holds either the task's working-set index (a positive integer)
+    or its UUID, and produces the correct string representation for the
+    TaskWarrior CLI via ``str(task_id)``.
+
+    TaskWarrior also supports partial UUID prefixes; these are accepted as-is
+    when provided as a plain string.
+
+    Args:
+        value: The task identifier — one of:
+
+            * ``int``  — working-set index (must be > 0).
+            * ``UUID`` — the task's persistent UUID.
+            * ``str``  — a UUID string, an integer string, or a UUID prefix.
+
+    Raises:
+        TaskValidationError: If *value* is an integer ≤ 0 or an empty string.
+
+    Example:
+        >>> TaskID(1)
+        TaskID('1')
+        >>> TaskID("abc-def-uuid")
+        TaskID('abc-def-uuid')
+        >>> TaskID(some_uuid_obj)
+        TaskID('550e8400-e29b-41d4-a716-446655440000')
+
+        Factory from an existing task output::
+
+            task = tw.get_task(TaskID(1))
+            tw.done_task(TaskID.from_task(task))
+    """
+
+    __slots__ = ("_value",)
+
+    def __init__(self, value: str | int | UUID) -> None:
+        if isinstance(value, int):
+            if value <= 0:
+                raise TaskValidationError(
+                    f"Task working-set index must be a positive integer, got {value}"
+                )
+            self._value: str = str(value)
+        elif isinstance(value, UUID):
+            self._value = str(value)
+        elif isinstance(value, str):
+            stripped = value.strip()
+            if not stripped:
+                raise TaskValidationError("TaskID string cannot be empty")
+            self._value = stripped
+        else:
+            raise TaskValidationError(
+                f"TaskID requires str, int, or UUID — got {type(value).__name__!r}"
+            )
+
+    @classmethod
+    def from_task(cls, task: TaskOutputDTO) -> TaskID:  # type: ignore[name-defined]  # noqa: F821
+        """Create a ``TaskID`` from the UUID of an existing task output.
+
+        Args:
+            task: A :class:`~taskwarrior.dto.task_dto.TaskOutputDTO` instance.
+
+        Returns:
+            A ``TaskID`` wrapping the task's UUID.
+
+        Example:
+            >>> task = tw.get_task(TaskID(1))
+            >>> tw.done_task(TaskID.from_task(task))
+        """
+        return cls(task.uuid)
+
+    def __str__(self) -> str:
+        return self._value
+
+    def __repr__(self) -> str:
+        return f"TaskID({self._value!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, TaskID):
+            return self._value == other._value
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self._value)
+
+
+# Type alias to reduce repeated unions across the codebase
+type TaskRef = str | int | UUID | TaskID

{pytaskwarrior-2.0.4 → pytaskwarrior-2.0.5}/src/taskwarrior/dto/uda_dto.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from enum import Enum
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 
 
 class UdaType(str, Enum):
@@ -36,6 +36,8 @@ class UdaType(str, Enum):
     UUID = "uuid"
 
 
+
+
 class UdaConfig(BaseModel):
     """Data Transfer Object for User Defined Attributes (UDAs).
 
@@ -78,3 +80,18 @@ class UdaConfig(BaseModel):
     )
 
     model_config = {"populate_by_name": True, "extra": "forbid"}
+
+    @model_validator(mode="before")
+    @classmethod
+    def alias_type_to_uda_type(cls, values: object) -> object:
+        # Accept 'type' as an alias for 'uda_type', unless 'uda_type' is already present
+        if isinstance(values, dict):
+            # Accept 'type' as an alias for 'uda_type', unless 'uda_type' is already present
+            if "type" in values and "uda_type" not in values:
+                values = dict(values)  # copy to avoid mutating input
+                values["uda_type"] = values.pop("type")
+            # Remove 'type' if both are present, to avoid extra field error
+            elif "type" in values and "uda_type" in values:
+                values = dict(values)
+                values.pop("type")
+        return values

{pytaskwarrior-2.0.4 → pytaskwarrior-2.0.5}/src/taskwarrior/main.py

@@ -8,11 +8,11 @@ from __future__ import annotations
 import logging
 import os
 from typing import Any
-from uuid import UUID
 
 from .adapters.taskwarrior_adapter import TaskWarriorAdapter
 from .dto.context_dto import ContextDTO
 from .dto.task_dto import TaskInputDTO, TaskOutputDTO
+from .dto.task_id import TaskRef
 from .dto.uda_dto import UdaConfig
 from .enums import TaskStatus  # noqa: F401 — re-exported for public API
 from .services.context_service import ContextService
@@ -114,12 +114,12 @@ class TaskWarrior:
         """
         return self.adapter.add_task(task)
 
-    def modify_task(self, task: TaskInputDTO, task_id_or_uuid: str | int | UUID) -> TaskOutputDTO:
+    def modify_task(self, task: TaskInputDTO, task_id: TaskRef) -> TaskOutputDTO:
         """Modify an existing task.
 
         Args:
             task: The new task data to apply.
-            task_id_or_uuid: The task ID (integer) or UUID to modify.
+            task_id: The task ID (integer) or UUID to modify.
 
         Returns:
             The updated task.
@@ -132,13 +132,13 @@ class TaskWarrior:
             >>> task = TaskInputDTO(description="Updated description")
             >>> updated = tw.modify_task(task, "abc-123-uuid")
         """
-        return self.adapter.modify_task(task, task_id_or_uuid)
+        return self.adapter.modify_task(task, task_id)
 
-    def get_task(self, task_id_or_uuid: str | int | UUID) -> TaskOutputDTO:
+    def get_task(self, task_id: TaskRef) -> TaskOutputDTO:
         """Retrieve a single task by ID or UUID.
 
         Args:
-            task_id_or_uuid: The task ID (integer) or UUID to retrieve.
+            task_id: The task ID (integer) or UUID to retrieve.
 
         Returns:
             The requested task.
@@ -149,8 +149,9 @@ class TaskWarrior:
         Example:
             >>> task = tw.get_task(1)  # By ID
             >>> task = tw.get_task("abc-123-uuid")  # By UUID
+            >>> task = tw.get_task(TaskID(1))  # Using TaskID
         """
-        return self.adapter.get_task(task_id_or_uuid)
+        return self.adapter.get_task(task_id)
 
     def get_tasks(
         self,
@@ -210,11 +211,11 @@ class TaskWarrior:
             include_deleted=include_deleted,
         )
 
-    def get_recurring_task(self, task_id_or_uuid: str | int | UUID) -> TaskOutputDTO:
+    def get_recurring_task(self, task_id: TaskRef) -> TaskOutputDTO:
         """Get the parent recurring task template.
 
         Args:
-            task_id_or_uuid: The UUID of a recurring task or one of its instances.
+            task_id: The UUID of a recurring task or one of its instances.
 
         Returns:
             The parent recurring task template.
@@ -222,13 +223,13 @@ class TaskWarrior:
         Raises:
             TaskNotFound: If the task doesn't exist.
         """
-        return self.adapter.get_recurring_task(task_id_or_uuid)
+        return self.adapter.get_recurring_task(task_id)
 
-    def get_recurring_instances(self, task_id_or_uuid: str | int | UUID) -> list[TaskOutputDTO]:
+    def get_recurring_instances(self, task_id: TaskRef) -> list[TaskOutputDTO]:
         """Get all instances of a recurring task.
 
         Args:
-            task_id_or_uuid: The UUID of the parent recurring task.
+            task_id: The UUID of the parent recurring task.
 
         Returns:
             List of task instances created from the recurring template.
@@ -236,39 +237,39 @@ class TaskWarrior:
         Raises:
             TaskNotFound: If the parent task doesn't exist.
         """
-        return self.adapter.get_recurring_instances(task_id_or_uuid)
+        return self.adapter.get_recurring_instances(task_id)
 
-    def delete_task(self, task_id_or_uuid: str | int | UUID) -> None:
+    def delete_task(self, task_id: TaskRef) -> None:
         """Mark a task as deleted.
 
         The task is not permanently removed; use `purge_task` for that.
 
         Args:
-            task_id_or_uuid: The task ID or UUID to delete.
+            task_id: The task ID or UUID to delete.
 
         Raises:
             TaskOperationError: If the operation fails (e.g., task already deleted).
         """
-        self.adapter.delete_task(task_id_or_uuid)
+        self.adapter.delete_task(task_id)
 
-    def purge_task(self, task_id_or_uuid: str | int | UUID) -> None:
+    def purge_task(self, task_id: TaskRef) -> None:
         """Permanently remove a task from the database.
 
         Unlike `delete_task`, this cannot be undone.
 
         Args:
-            task_id_or_uuid: The task ID or UUID to purge.
+            task_id: The task ID or UUID to purge.
 
         Raises:
             TaskOperationError: If the operation fails (e.g., task was not deleted first).
         """
-        self.adapter.purge_task(task_id_or_uuid)
+        self.adapter.purge_task(task_id)
 
-    def done_task(self, task_id_or_uuid: str | int | UUID) -> None:
+    def done_task(self, task_id: TaskRef) -> None:
         """Mark a task as completed.
 
         Args:
-            task_id_or_uuid: The task ID or UUID to complete.
+            task_id: The task ID or UUID to complete.
 
         Raises:
             TaskOperationError: If the operation fails (e.g., task is already completed).
@@ -276,42 +277,43 @@ class TaskWarrior:
         Example:
             >>> tw.done_task(1)
             >>> tw.done_task("abc-123-uuid")
+            >>> tw.done_task(TaskID(1))
         """
-        self.adapter.done_task(task_id_or_uuid)
+        self.adapter.done_task(task_id)
 
-    def start_task(self, task_id_or_uuid: str | int | UUID) -> None:
+    def start_task(self, task_id: TaskRef) -> None:
         """Start working on a task.
 
         Sets the task's start time to now, indicating active work.
 
         Args:
-            task_id_or_uuid: The task ID or UUID to start.
+            task_id: The task ID or UUID to start.
 
         Raises:
             TaskOperationError: If the operation fails (e.g., task is already started).
         """
-        self.adapter.start_task(task_id_or_uuid)
+        self.adapter.start_task(task_id)
 
-    def stop_task(self, task_id_or_uuid: str | int | UUID) -> None:
+    def stop_task(self, task_id: TaskRef) -> None:
         """Stop working on a task.
 
         Clears the task's start time.
 
         Args:
-            task_id_or_uuid: The task ID or UUID to stop.
+            task_id: The task ID or UUID to stop.
 
         Raises:
             TaskOperationError: If the operation fails (e.g., task was not started).
         """
-        self.adapter.stop_task(task_id_or_uuid)
+        self.adapter.stop_task(task_id)
 
-    def annotate_task(self, task_id_or_uuid: str | int | UUID, annotation: str) -> None:
+    def annotate_task(self, task_id: TaskRef, annotation: str) -> None:
         """Add an annotation (note) to a task.
 
         Annotations are timestamped notes attached to tasks.
 
         Args:
-            task_id_or_uuid: The task ID or UUID to annotate.
+            task_id: The task ID or UUID to annotate.
             annotation: The annotation text to add.
 
         Raises:
@@ -320,7 +322,7 @@ class TaskWarrior:
         Example:
             >>> tw.annotate_task(1, "Discussed with team, need more info")
         """
-        self.adapter.annotate_task(task_id_or_uuid, annotation)
+        self.adapter.annotate_task(task_id, annotation)
 
     def define_context(self, context: ContextDTO) -> None:
         """Define a new context from a ContextDTO.