Renames RetryTaskError -> Retry (backwards compatible)

celery/app/task.py

@@ -16,7 +16,7 @@ from celery import current_app
 from celery import states
 from celery._state import _task_stack
 from celery.canvas import subtask
-from celery.exceptions import MaxRetriesExceededError, RetryTaskError, Reject
+from celery.exceptions import MaxRetriesExceededError, Reject, Retry
 from celery.five import class_property, items, with_metaclass
 from celery.result import EagerResult
 from celery.utils import gen_task_name, fun_takes_kwargs, uuid, maybe_reraise
@@ -517,7 +517,7 @@ class Task(object):
         :param kwargs: Keyword arguments to retry with.
         :keyword exc: Custom exception to report when the max restart
             limit has been exceeded (default:
-            :exc:`~celery.exceptions.MaxRetriesExceededError`).
+            :exc:`~@MaxRetriesExceededError`).
 
             If this argument is set and retry is called while
             an exception was raised (``sys.exc_info()`` is set)
@@ -535,13 +535,13 @@ class Task(object):
         :keyword \*\*options: Any extra options to pass on to
                               meth:`apply_async`.
         :keyword throw: If this is :const:`False`, do not raise the
-                        :exc:`~celery.exceptions.RetryTaskError` exception,
+                        :exc:`~@Retry` exception,
                         that tells the worker to mark the task as being
                         retried.  Note that this means the task will be
                         marked as failed if the task raises an exception,
                         or successful if it returns.
 
-        :raises celery.exceptions.RetryTaskError: To tell the worker that
+        :raises celery.exceptions.Retry: To tell the worker that
             the task has been re-sent for retry. This always happens,
             unless the `throw` keyword argument has been explicitly set
             to :const:`False`, and is considered normal operation.
@@ -572,7 +572,7 @@ class Task(object):
         # so just raise the original exception.
         if request.called_directly:
             maybe_reraise()  # raise orig stack if PyErr_Occurred
-            raise exc or RetryTaskError('Task can be retried', None)
+            raise exc or Retry('Task can be retried', None)
 
         if not eta and countdown is None:
             countdown = self.default_retry_delay
@@ -595,7 +595,7 @@ class Task(object):
             # If task was executed eagerly using apply(),
             # then the retry must also be executed eagerly.
             S.apply().get() if is_eager else S.apply_async()
-            ret = RetryTaskError(exc=exc, when=eta or countdown)
+            ret = Retry(exc=exc, when=eta or countdown)
             if throw:
                 raise ret
             return ret

celery/app/trace.py

@@ -29,7 +29,7 @@ from celery import states, signals
 from celery._state import _task_stack
 from celery.app import set_default_app
 from celery.app.task import Task as BaseTask, Context
-from celery.exceptions import Ignore, RetryTaskError, Reject
+from celery.exceptions import Ignore, Reject, Retry
 from celery.utils.log import get_logger
 from celery.utils.objects import mro_lookup
 from celery.utils.serialization import (
@@ -85,7 +85,7 @@ class TraceInfo(object):
 
     def handle_retry(self, task, store_errors=True):
         """Handle retry exception."""
-        # the exception raised is the RetryTaskError semi-predicate,
+        # the exception raised is the Retry semi-predicate,
         # and it's exc' attribute is the original exception raised (if any).
         req = task.request
         type_, _, tb = sys.exc_info()
@@ -132,7 +132,7 @@ def build_tracer(name, task, loader=None, hostname=None, store_errors=True,
     If the call was successful, it saves the result to the task result
     backend, and sets the task status to `"SUCCESS"`.
 
-    If the call raises :exc:`~celery.exceptions.RetryTaskError`, it extracts
+    If the call raises :exc:`~@Retry`, it extracts
     the original exception, uses that as the result and sets the task state
     to `"RETRY"`.
 
@@ -217,7 +217,7 @@ def build_tracer(name, task, loader=None, hostname=None, store_errors=True,
                 except Ignore as exc:
                     I, R = Info(IGNORED, exc), ExceptionInfo(internal=True)
                     state, retval = I.state, I.retval
-                except RetryTaskError as exc:
+                except Retry as exc:
                     I = Info(RETRY, exc)
                     state, retval = I.state, I.retval
                     R = I.handle_error_state(task, eager=eager)

celery/exceptions.py

@@ -16,7 +16,7 @@ from billiard.exceptions import (  # noqa
 
 __all__ = ['SecurityError', 'Ignore', 'SystemTerminate', 'QueueNotFound',
            'ImproperlyConfigured', 'NotRegistered', 'AlreadyRegistered',
-           'TimeoutError', 'MaxRetriesExceededError', 'RetryTaskError',
+           'TimeoutError', 'MaxRetriesExceededError', 'Retry',
            'TaskRevokedError', 'NotConfigured', 'AlwaysEagerIgnored',
            'InvalidTaskError', 'ChordError', 'CPendingDeprecationWarning',
            'CDeprecationWarning', 'FixupWarning', 'DuplicateNodenameWarning',
@@ -83,7 +83,7 @@ class MaxRetriesExceededError(Exception):
     """The tasks max restart limit has been exceeded."""
 
 
-class RetryTaskError(Exception):
+class Retry(Exception):
     """The task is to be retried later."""
 
     #: Optional message describing context of retry.
@@ -119,6 +119,7 @@ class RetryTaskError(Exception):
 
     def __reduce__(self):
         return self.__class__, (self.message, self.excs, self.when)
+RetryTaskError = Retry   # XXX compat
 
 
 class TaskRevokedError(Exception):

celery/tests/app/test_exceptions.py

@@ -4,17 +4,32 @@ import pickle
 
 from datetime import datetime
 
-from celery.exceptions import RetryTaskError
+from celery.exceptions import Reject, Retry
 
 from celery.tests.case import AppCase
 
 
-class test_RetryTaskError(AppCase):
+class test_Retry(AppCase):
 
     def test_when_datetime(self):
-        x = RetryTaskError('foo', KeyError(), when=datetime.utcnow())
+        x = Retry('foo', KeyError(), when=datetime.utcnow())
         self.assertTrue(x.humanize())
 
     def test_pickleable(self):
-        x = RetryTaskError('foo', KeyError(), when=datetime.utcnow())
+        x = Retry('foo', KeyError(), when=datetime.utcnow())
+        self.assertTrue(pickle.loads(pickle.dumps(x)))
+
+
+class test_Reject(AppCase):
+
+    def test_attrs(self):
+        x = Reject('foo', requeue=True)
+        self.assertEqual(x.reason, 'foo')
+        self.assertTrue(x.requeue)
+
+    def test_repr(self):
+        self.assertTrue(repr(Reject('foo', True)))
+
+    def test_pickleable(self):
+        x = Retry('foo', True)
         self.assertTrue(pickle.loads(pickle.dumps(x)))

celery/tests/tasks/test_tasks.py

@@ -8,7 +8,7 @@ from kombu import Queue
 
 from celery import Task
 
-from celery.exceptions import RetryTaskError
+from celery.exceptions import Retry
 from celery.five import items, range, string_t
 from celery.result import EagerResult
 from celery.utils import uuid
@@ -129,7 +129,7 @@ class test_task_retries(TasksCase):
     def test_retry_kwargs_can_be_empty(self):
         self.retry_task_mockapply.push_request()
         try:
-            with self.assertRaises(RetryTaskError):
+            with self.assertRaises(Retry):
                 self.retry_task_mockapply.retry(args=[4, 4], kwargs=None)
         finally:
             self.retry_task_mockapply.pop_request()
@@ -149,7 +149,7 @@ class test_task_retries(TasksCase):
                 self.retry_task_mockapply.applied = 0
 
             try:
-                with self.assertRaises(RetryTaskError):
+                with self.assertRaises(Retry):
                     self.retry_task_mockapply.retry(
                         args=[4, 4], kwargs={'task_retries': 0},
                         exc=exc, throw=True)

celery/tests/tasks/test_trace.py

@@ -5,7 +5,7 @@ from mock import Mock, patch
 from celery import uuid
 from celery import signals
 from celery import states
-from celery.exceptions import RetryTaskError, Ignore
+from celery.exceptions import Ignore, Retry
 from celery.app.trace import (
     TraceInfo,
     eager_trace_task,
@@ -131,8 +131,8 @@ class test_trace(TraceCase):
         with self.assertRaises(SystemExit):
             self.trace(self.raises, (SystemExit(), ), {})
 
-    def test_trace_RetryTaskError(self):
-        exc = RetryTaskError('foo', 'bar')
+    def test_trace_Retry(self):
+        exc = Retry('foo', 'bar')
         _, info = self.trace(self.raises, (exc, ), {})
         self.assertEqual(info.state, states.RETRY)
         self.assertIs(info.retval, exc)

celery/tests/worker/test_request.py

@@ -28,12 +28,12 @@ from celery.app.trace import (
 )
 from celery.concurrency.base import BasePool
 from celery.exceptions import (
-    RetryTaskError,
-    WorkerLostError,
+    Ignore,
     InvalidTaskError,
+    Retry,
     TaskRevokedError,
     Terminated,
-    Ignore,
+    WorkerLostError,
 )
 from celery.five import keys
 from celery.signals import task_revoked
@@ -114,13 +114,13 @@ class test_default_encode(AppCase):
             sys.getfilesystemencoding = gfe
 
 
-class test_RetryTaskError(AppCase):
+class test_Retry(AppCase):
 
-    def test_retry_task_error(self):
+    def test_retry_semipredicate(self):
         try:
             raise Exception('foo')
         except Exception as exc:
-            ret = RetryTaskError('Retrying task', exc)
+            ret = Retry('Retrying task', exc)
             self.assertEqual(ret.exc, exc)
 
 
@@ -361,7 +361,7 @@ class test_Request(AppCase):
         )
         job.eventer = MockEventDispatcher()
         try:
-            raise RetryTaskError('foo', KeyError('moofoobar'))
+            raise Retry('foo', KeyError('moofoobar'))
         except:
             einfo = ExceptionInfo()
             job.on_failure(einfo)
@@ -736,15 +736,14 @@ class test_Request(AppCase):
             self.assertIsInstance(res, ExceptionInfo)
 
     def test_worker_task_trace_handle_retry(self):
-        from celery.exceptions import RetryTaskError
         tid = uuid()
         self.mytask.push_request(id=tid)
         try:
             raise ValueError('foo')
         except Exception as exc:
             try:
-                raise RetryTaskError(str(exc), exc=exc)
-            except RetryTaskError as exc:
+                raise Retry(str(exc), exc=exc)
+            except Retry as exc:
                 w = TraceInfo(states.RETRY, exc)
                 w.handle_retry(self.mytask, store_errors=False)
                 self.assertEqual(

celery/worker/job.py

@@ -24,7 +24,7 @@ from celery.app.trace import trace_task, trace_task_ret
 from celery.exceptions import (
     Ignore, TaskRevokedError, InvalidTaskError,
     SoftTimeLimitExceeded, TimeLimitExceeded,
-    WorkerLostError, Terminated, RetryTaskError, Reject,
+    WorkerLostError, Terminated, Retry, Reject,
 )
 from celery.five import items, monotonic
 from celery.platforms import signals as _signals
@@ -385,7 +385,7 @@ class Request(object):
         if not exc_info.internal:
             exc = exc_info.exception
 
-            if isinstance(exc, RetryTaskError):
+            if isinstance(exc, Retry):
                 return self.on_retry(exc_info)
 
             # These are special cases where the process would not have had

docs/django/first-steps-with-django.rst

@@ -9,13 +9,13 @@ Using Celery with Django
 
 .. note::
 
-Previous versions of Celery required a separate library to work with Django,
-but since 3.1 this is no longer the case. Django is supported out of the
-box now so this document only contains a basic way to integrate Celery and
-Django.  You will use the same API as non-Django users so it's recommended that
-you read the :ref:`first-steps` tutorial
-first and come back to this tutorial.  When you have a working example you can
-continue to the :ref:`next-steps` guide.
+    Previous versions of Celery required a separate library to work with Django,
+    but since 3.1 this is no longer the case. Django is supported out of the
+    box now so this document only contains a basic way to integrate Celery and
+    Django.  You will use the same API as non-Django users so it's recommended that
+    you read the :ref:`first-steps` tutorial
+    first and come back to this tutorial.  When you have a working example you can
+    continue to the :ref:`next-steps` guide.
 
 To use Celery with your Django project you must first define
 an instance of the Celery library (called an "app")