Repository: PrefectHQ/prefect

Issue:
Remove references to `return_tasks` in docs
As identified by @ntaylorwss, some of the docs and tutorials reference the `return_tasks` kwarg that was removed in #693, and will need updating before the next release.


Discussion:
The two places I've identified this so far are:

https://docs.prefect.io/guide/core_concepts/flows.html#running-a-flow

> This will return a State object representing the outcome of the run. To receive task states as well, supply a return_tasks argument to flow.run():

```
state = flow.run(return_tasks=[h])
state.result[h] # the task state of the say_hello task
```

And https://docs.prefect.io/guide/core_concepts/mapping.html#prefect-approach

```
from prefect import Flow, task

numbers = [1, 2, 3]
map_fn = task(lambda x: x + 1)
reduce_fn = task(lambda x: sum(x))

with Flow() as flow:
    mapped_result = map_fn.map(numbers)
    reduced_result = reduce_fn(mapped_result)

state = flow.run(return_tasks=[reduced_result])
assert state.result[reduced_result].result == 9
```

(Also just a note that I think you've tagged the wrong person in the comment)
Whoops, trying to do too many things at once :) Thanks for pointing this out!

Resolving patch:
diff --git a/src/prefect/core/flow.py b/src/prefect/core/flow.py
--- a/src/prefect/core/flow.py
+++ b/src/prefect/core/flow.py
@@ -957,10 +957,14 @@ def run(
         Returns:
             - State: the state of the flow after its final run
         """
+        # protect against old behavior
         if "return_tasks" in kwargs:
             raise ValueError(
-                "The `return_tasks` keywords cannot be provided to `flow.run`; all task states are always returned.  If you wish to only work with a subset, use a FlowRunner directly."
+                "The `return_tasks` keyword cannot be provided to `flow.run()`; "
+                "all task states are always returned. If you want to receive a subset "
+                "of task states, use a FlowRunner directly."
             )
+
         if runner_cls is None:
             runner_cls = prefect.engine.get_default_flow_runner_class()
 
diff --git a/src/prefect/engine/cache_validators.py b/src/prefect/engine/cache_validators.py
--- a/src/prefect/engine/cache_validators.py
+++ b/src/prefect/engine/cache_validators.py
@@ -164,13 +164,12 @@ def daily_db_refresh(nrows, runtime):
         runtime = Parameter("runtime")
         db_state = daily_db_refresh(nrows, runtime)
 
-    state1 = f.run(parameters=dict(nrows=1000, runtime=pendulum.now('utc')),
-                  return_tasks=[db_state])
+    state1 = f.run(parameters=dict(nrows=1000, runtime=pendulum.now('utc')))
 
     ## the second run will use the cache contained within state1.result[db_state]
     ## even though `runtime` has changed
     state2 = f.run(parameters=dict(nrows=1000, runtime=pendulum.now('utc')),
-                   return_tasks=[db_state], task_states={result: state1.result[db_state]})
+                   task_states={result: state1.result[db_state]})
     ```
     """
     parameters = parameters or {}
@@ -233,11 +232,10 @@ def rand_bool():
     with Flow() as f:
         ans = add(1, 2, rand_bool())
 
-    state1 = f.run(return_tasks=[ans])
+    state1 = f.run()
     ## the second run will use the cache contained within state1.result[ans]
     ## even though `rand_bool` might change
-    state2 = f.run(return_tasks=[ans],
-                   task_states={result: state1.result[ans]})
+    state2 = f.run(task_states={result: state1.result[ans]})
     ```
     """
     inputs = inputs or {}
diff --git a/src/prefect/utilities/tasks.py b/src/prefect/utilities/tasks.py
--- a/src/prefect/utilities/tasks.py
+++ b/src/prefect/utilities/tasks.py
@@ -100,10 +100,10 @@ def add(x, y):
         with Flow() as f:
             res = add(4, 4)
 
-        state = f.run(return_tasks=[res])
+        state = f.run()
         state.result[res] # a Paused state
 
-        state = f.run(return_tasks=[res], task_states={res: Resume()})
+        state = f.run(task_states={res: Resume()})
         state.result[res] # a Success state
         ```
     """


Test patch:
diff --git a/tests/core/test_flow.py b/tests/core/test_flow.py
--- a/tests/core/test_flow.py
+++ b/tests/core/test_flow.py
@@ -1415,8 +1415,7 @@ def test_flow_run_raises_informative_error_for_certain_kwargs():
     f = Flow()
     with pytest.raises(ValueError) as exc:
         f.run(return_tasks=f.tasks)
-    assert "return_tasks" in str(exc.value)
-    assert "FlowRunner" in str(exc.value)
+    assert "`return_tasks` keyword cannot be provided" in str(exc.value)
 
 
 def test_flow_run_raises_if_no_more_scheduled_runs():