From 6fdadaabe4eebaa6c6431e4122cd4494d85b5d71 Mon Sep 17 00:00:00 2001
From: Ethan Wolinsky <58117461+eswolinsky3241@users.noreply.github.com>
Date: Wed, 24 May 2023 19:26:42 -0400
Subject: [PATCH] Document_stopped_jobs and dependents for enqueue_many (#1922)

* Add documentation for on_stopped callback

* Update dependent jobs documentation

Starting in version 1.15.0, enqueue_many supports dependent jobs.

* Add stopped callback usage example

* Update callback docstring

* Fix arg type

* Remove trailing whitespace
---
 docs/docs/index.md | 27 ++++++++++++++++++++-------
 rq/defaults.py     |  4 ++--
 2 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/docs/docs/index.md b/docs/docs/index.md
index e42539f..9b6a922 100644
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -131,8 +131,7 @@ with q.connection.pipeline() as pipe:
   pipe.execute()
 ```
 
-`Queue.prepare_data` accepts all arguments that `Queue.parse_args` does **EXCEPT** for `depends_on`,
-which is not supported at this time, so dependencies will be up to you to setup.
+`Queue.prepare_data` accepts all arguments that `Queue.parse_args` does.
 
 ## Job dependencies
 
@@ -195,18 +194,18 @@ job_2 = queue.enqueue(say_hello, depends_on=dependency)
 ## Job Callbacks
 _New in version 1.9.0._
 
-If you want to execute a function whenever a job completes or fails, RQ provides
-`on_success` and `on_failure` callbacks.
+If you want to execute a function whenever a job completes, fails, or is stopped, RQ provides
+`on_success`, `on_failure`, and `on_stopped` callbacks.
 
 ```python
-queue.enqueue(say_hello, on_success=report_success, on_failure=report_failure)
+queue.enqueue(say_hello, on_success=report_success, on_failure=report_failure, on_stopped=report_stopped)
 ```
 
 ### Callback Class and Callback Timeouts
 
 _New in version 1.14.0_
 
-RQ lets you configure the method and timeout for each callback - success and failure.   
+RQ lets you configure the method and timeout for each callback - success, failure, and stopped.   
 To configure callback timeouts, use RQ's
 `Callback` object that accepts `func` and `timeout` arguments. For example:
 
@@ -214,7 +213,8 @@ To configure callback timeouts, use RQ's
 from rq import Callback
 queue.enqueue(say_hello, 
               on_success=Callback(report_success),  # default callback timeout (60 seconds) 
-              on_failure=Callback(report_failure, timeout=10))  # 10 seconds timeout
+              on_failure=Callback(report_failure, timeout=10), # 10 seconds timeout
+              on_stopped=Callback(report_stopped, timeout="2m")) # 2 minute timeout  
 ```
 
 ### Success Callback
@@ -249,6 +249,19 @@ def report_failure(job, connection, type, value, traceback):
 Failure callbacks are limited to 60 seconds of execution time.
 
 
+### Stopped Callbacks
+
+Stopped callbacks are functions that accept `job` and `connection` arguments.
+
+```python
+def report_stopped(job, connection):
+  pass
+```
+
+Stopped callbacks are functions that are executed when a worker receives a command to stop
+a job that is currently executing. See [Stopping a Job](https://python-rq.org/docs/workers/#stopping-a-job).
+
+
 ### CLI Enqueueing
 
 _New in version 1.10.0._
diff --git a/rq/defaults.py b/rq/defaults.py
index 0cea711..b8975d7 100644
--- a/rq/defaults.py
+++ b/rq/defaults.py
@@ -71,8 +71,8 @@ in seconds. Defaults to 10 minutes.
 
 CALLBACK_TIMEOUT = 60
 """ The timeout period in seconds for Callback functions
-Means that Functions used in `success_callback` and `failure_callback`
-will timeout after N seconds
+Means that Functions used in `success_callback`, `stopped_callback`,
+and `failure_callback` will timeout after N seconds
 """