Repository: enthought/traits-futures

Issue:
Rename ProgressCancelled exception
(related: #437, #317)

The `ProgressCancelled` exception is generally useful, and should be renamed to `Cancelled` and moved into `base_future.py`. The renaming would be best done before the 0.3.0 release, since `ProgressCancelled` hasn't yet been made available in any released version of the library.

Comments:

Patch:
diff --git a/docs/source/changes.rst b/docs/source/changes.rst
index 56404d1..ffabb7b 100644
--- a/docs/source/changes.rst
+++ b/docs/source/changes.rst
@@ -91,7 +91,7 @@ Fixes
   queue. Instead, it will fail fast with a ``QueueError`` exception. This
   situation should never happen in normal use; please report it if you ever
   witness it.
-* The ``ProgressCancelled`` exception used by the background task submitted
+* The ``TaskCancelled`` exception used by the background task submitted
   via ``submit_progress`` is now public, in case that task needs to catch
   the exception.
 * The marshal_exception function has been fixed not to rely on the global
diff --git a/docs/source/guide/intro.rst b/docs/source/guide/intro.rst
index a6a3b76..4d613bf 100644
--- a/docs/source/guide/intro.rst
+++ b/docs/source/guide/intro.rst
@@ -56,7 +56,7 @@ from |traits_futures.api|:
   "progress" parameter can then be called to send progress reports to the
   associated |ProgressFuture| object. If the future has been cancelled, the
   next call to ``progress`` in the background task will raise a
-  |ProgressCancelled| exception.
+  |TaskCancelled| exception.
 
   For example, your callable might look like this::
 
@@ -393,7 +393,7 @@ needed.
 .. |submit_iteration| replace:: :func:`~traits_futures.background_iteration.submit_iteration`
 .. |result_event| replace:: :attr:`~traits_futures.background_iteration.IterationFuture.result_event`
 
-.. |ProgressCancelled| replace:: :exc:`~traits_futures.background_progress.ProgressCancelled`
+.. |TaskCancelled| replace:: :exc:`~traits_futures.base_future.TaskCancelled`
 .. |ProgressFuture| replace:: :class:`~traits_futures.background_progress.ProgressFuture`
 .. |submit_progress| replace:: :func:`~traits_futures.background_progress.submit_progress`
 .. |progress| replace:: :attr:`~traits_futures.background_progress.ProgressFuture.progress`
diff --git a/traits_futures/api.py b/traits_futures/api.py
index 914b21b..9d00855 100644
--- a/traits_futures/api.py
+++ b/traits_futures/api.py
@@ -28,7 +28,6 @@ Task submission functions
 - :func:`~.submit_call`
 - :func:`~.submit_iteration`
 - :func:`~.submit_progress`
-- :exc:`~.ProgressCancelled`
 
 Types of futures
 ----------------
@@ -36,6 +35,7 @@ Types of futures
 - :class:`~.CallFuture`
 - :class:`~.IterationFuture`
 - :class:`~.ProgressFuture`
+- :exc:`~.TaskCancelled`
 
 Future states
 -------------
@@ -85,12 +85,8 @@ from traits_futures.background_iteration import (
     IterationFuture,
     submit_iteration,
 )
-from traits_futures.background_progress import (
-    ProgressCancelled,
-    ProgressFuture,
-    submit_progress,
-)
-from traits_futures.base_future import BaseFuture, BaseTask
+from traits_futures.background_progress import ProgressFuture, submit_progress
+from traits_futures.base_future import BaseFuture, BaseTask, TaskCancelled
 from traits_futures.ets_event_loop import ETSEventLoop
 from traits_futures.executor_states import (
     ExecutorState,
@@ -119,7 +115,7 @@ __all__ = [
     "CallFuture",
     "IterationFuture",
     "ProgressFuture",
-    "ProgressCancelled",
+    "TaskCancelled",
     # Future states
     "FutureState",
     "CANCELLED",
diff --git a/traits_futures/background_progress.py b/traits_futures/background_progress.py
index 774f3c1..73b1dc3 100644
--- a/traits_futures/background_progress.py
+++ b/traits_futures/background_progress.py
@@ -21,7 +21,7 @@ be cancelled.
 
 from traits.api import Callable, Dict, Event, HasStrictTraits, Str, Tuple
 
-from traits_futures.base_future import BaseFuture, BaseTask
+from traits_futures.base_future import BaseFuture, BaseTask, TaskCancelled
 from traits_futures.i_task_specification import ITaskSpecification
 
 # Message types for messages from ProgressTask
@@ -32,13 +32,6 @@ from traits_futures.i_task_specification import ITaskSpecification
 PROGRESS = "progress"
 
 
-class ProgressCancelled(Exception):
-    """
-    Exception raised when progress reporting is interrupted by
-    task cancellation.
-    """
-
-
 class ProgressReporter:
     """
     Object used by the target callable to report progress.
@@ -63,13 +56,13 @@ class ProgressReporter:
 
         Raises
         ------
-        ProgressCancelled
+        TaskCancelled
             If a cancellation request for this task has already been made.
             In this case, the exception will be raised before any progress
             information is sent.
         """
         if self.cancelled():
-            raise ProgressCancelled("Task was cancelled")
+            raise TaskCancelled("Task was cancelled")
         self.send(PROGRESS, progress_info)
 
 
@@ -94,7 +87,7 @@ class ProgressTask(BaseTask):
                 **self.kwargs,
                 progress=progress.report,
             )
-        except ProgressCancelled:
+        except TaskCancelled:
             return None
 
 
diff --git a/traits_futures/base_future.py b/traits_futures/base_future.py
index f425aae..578cbc7 100644
--- a/traits_futures/base_future.py
+++ b/traits_futures/base_future.py
@@ -125,6 +125,12 @@ _CANCELLABLE_INTERNAL_STATES = {
 }
 
 
+class TaskCancelled(Exception):
+    """
+    Exception raised within the background task on cancellation.
+    """
+
+
 class _StateTransitionError(Exception):
     """
     Exception used to indicate a bad state transition.


Test patch:
diff --git a/traits_futures/tests/background_progress_tests.py b/traits_futures/tests/background_progress_tests.py
index 99d1fce..a7812bd 100644
--- a/traits_futures/tests/background_progress_tests.py
+++ b/traits_futures/tests/background_progress_tests.py
@@ -17,9 +17,9 @@ from traits_futures.api import (
     EXECUTING,
     FAILED,
     FutureState,
-    ProgressCancelled,
     ProgressFuture,
     submit_progress,
+    TaskCancelled,
     WAITING,
 )
 
@@ -81,7 +81,7 @@ def syncing_progress(test_ready, raised, progress):
     # so that we never get to the following code.
     try:
         progress("second")
-    except ProgressCancelled:
+    except TaskCancelled:
         raised.set()
         raise
 
diff --git a/traits_futures/tests/test_api.py b/traits_futures/tests/test_api.py
index e388319..3474bff 100644
--- a/traits_futures/tests/test_api.py
+++ b/traits_futures/tests/test_api.py
@@ -33,7 +33,6 @@ class TestApi(unittest.TestCase):
             IterationFuture,
             MultiprocessingContext,
             MultithreadingContext,
-            ProgressCancelled,
             ProgressFuture,
             RUNNING,
             STOPPED,
@@ -41,6 +40,7 @@ class TestApi(unittest.TestCase):
             submit_call,
             submit_iteration,
             submit_progress,
+            TaskCancelled,
             TraitsExecutor,
             WAITING,
         )