rework status tracker pattern and update the document

Author: MacHu-GWU

docs/source/06-Status-Tracker/index.ipynb

@@ -13,5 +13,4 @@ sub packages and modules
     api <api>
     compressed <compressed>
     encrypted <encrypted>
-    s3backed <s3backed>
 

docs/source/pynamodb_mate/attributes/__init__.rst

@@ -11,5 +11,6 @@ sub packages and modules
     :maxdepth: 1
 
     api <api>
+    exc <exc>
     impl <impl>
 

docs/source/pynamodb_mate/attributes/s3backed.rst

@@ -0,0 +1,5 @@
+exc
+===
+
+.. automodule:: pynamodb_mate.patterns.status_tracker.exc
+    :members:

docs/source/pynamodb_mate/patterns/status_tracker/__init__.rst

@@ -1,9 +1,14 @@
 # -*- coding: utf-8 -*-
 
+from .exc import TaskExecutionError
+from .exc import TaskIsNotInitializedError
+from .exc import TaskIsNotReadyToStartError
+from .exc import TaskLockedError
+from .exc import TaskAlreadySucceedError
+from .exc import TaskIgnoredError
+from .impl import StatusNameEnum
 from .impl import BaseStatusEnum
+from .impl import TrackerConfig
 from .impl import StatusAndUpdateTimeIndex
-from .impl import TaskLockedError
-from .impl import TaskIgnoredError
-from .impl import BaseData
-from .impl import BaseErrors
-from .impl import BaseStatusTracker
+from .impl import BaseTask
+from .impl import ExecutionContext

docs/source/pynamodb_mate/patterns/status_tracker/exc.rst

@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+
+
+class TaskExecutionError(Exception):
+    """
+    The base class for errors raised during task execution.
+    """
+
+    @staticmethod
+    def to_task(use_case_id: str, task_id: str) -> str:
+        return f"Task(use_case_id={use_case_id!r}, task_id={task_id!r})"
+
+
+class TaskIsNotInitializedError(TaskExecutionError):
+    """
+    Raised when a task is not initialized in DynamoDB table.
+    """
+
+    @classmethod
+    def make(cls, use_case_id: str, task_id: str):
+        return cls(
+            f"{cls.to_task(use_case_id, task_id)} is not found in DynamoDB table, "
+            "You have to run ``Task.make_and_save(task_id=...)`` to "
+            "create an initial tracker item first."
+        )
+
+
+class TaskIsNotReadyToStartError(TaskExecutionError):
+    """
+    Raised when a task is not ready to start.
+
+    There are two possible reasons:
+
+    1. Task is locked.
+    2. Task status is not pending or failed.
+    """
+
+    @classmethod
+    def make(cls, use_case_id: str, task_id: str):
+        return cls(
+            f"{cls.to_task(use_case_id, task_id)} is not ready to start, "
+            "either it is locked or status is not in 'pending' or 'failed'. "
+            "You may use ``with Task.start(task_id=..., detailed_error=True) as execution_context:`` "
+            "to get more details."
+        )
+
+
+class TaskLockedError(TaskExecutionError):
+    """
+    Raised when a task worker is trying to work on a locked task.
+    """
+
+    @classmethod
+    def make(cls, use_case_id: str, task_id: str):
+        return cls(f"{cls.to_task(use_case_id, task_id)} is locked")
+
+
+class TaskAlreadySucceedError(TaskExecutionError):
+    """
+    Raised when a task is already in "succeeded" status.
+    """
+
+    @classmethod
+    def make(cls, use_case_id: str, task_id: str):
+        return cls(f"{cls.to_task(use_case_id, task_id)} is already succeeded.")
+
+
+class TaskIgnoredError(TaskExecutionError):
+    """
+    Raised when a task is already in "ignored" status.
+    """
+
+    @classmethod
+    def make(cls, use_case_id: str, task_id: str):
+        return cls(f"{cls.to_task(use_case_id, task_id)} is ignored.")