Reschedule increases `attempt` value

[srgnk]

This might not be the issue of the code at all, but reschedule method confused me a bit.

The following snippet of code would increase the job's attempt value by 1:

with rq.dequeue("tasks") as job:
    job.reschedule()

While the reschedule's docstring explicitly says

the current attempt won't count towards the maximum number of retries.

Turns out that it's not the reschedule that bumps up the attempt value but context manager dequeue.
That is, the following code would leave the attempt intact:

job = rq.jobs("tasks")[0]
job.reschedule()

From the user's perspective these 2 ways of rescheduling jobs don't differ much, but they work differently.

I am also assuming that dequeue is the recommended way of picking up jobs but this option would almost always add 1 to the attempt value which contradicts the example in the README file:

The reschedule() method is used to reprocess the job at a later time. The job will remain in the queue with a new scheduled execution time, and the current attempt won't count towards the maximum number of retries.

This method should only be called inside the dequeue() context manager.

with rq.dequeue("my-queue") as job:
    # Check if we have everything ready to process the job, and if not,
    # reschedule the job to run 10 minutes from now
    if not is_everything_ready_to_process(job.payload):
        job.reschedule(delay=timedelta(minutes=10))
    else:
        # Otherwise, process the job
        do_work(job.payload)

[vduseev]

Summary

We've discussed this issue with @srgnk and the most elegant solution requires a redesign of the Job action methods paradigm, such as reschedule() or cancel().

Why so?

Allowing developers to call job.reschedule() on any job instance is confusing. While the method documentation explicitly advises against it, the library won't complain if you do it. Which is... confusing.

What's the alternative?

Raise mechanism. The same way raise StopIteration is used to stop the subscription loop, a different exception could be used to reschedule the thing. We could base this control exceptions on BaseException to distinguish them from normal Exception derived classes.

The good side of it

• Common control mechanism within context based on raise. Examples: raise StopIteration(), raise RescheduleJob(delay=timedelta(minutes=10)), raise CancelJob().
• No way to use it incorrectly. You wouldn't raise a control.

The ugly side of it

• No one in their right mind would use exception raising as a main way to control your business logic in Python. This is such a counter intuitive way to manage a job. It might be even more confusing to developers.
  What's the first thing that comes to your mind if you want to reschedule a job you've just consumed? Probably some method, right? Not to raise an exception.

Conclusion

Need to think about it for another 6 months or so.