Additional tweaks to task retry docs #9575
Conversation
✅ Deploy Preview for prefect-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
docs/concepts/tasks.md
Outdated
| @@ -204,29 +204,80 @@ def my_flow(): | |||
|
|
|||
| ## Retries | |||
|
|
|||
| Prefect tasks can automatically retry on failure. To enable retries, pass `retries` and `retry_delay_seconds` parameters to your task. | |||
| Prefect can automatically retry tasks on failure. In Prefect, a task _fails_ | |||
| if it returns a value that is not a `State` object, or if it raises an | |||
There was a problem hiding this comment.
| if it returns a value that is not a `State` object, or if it raises an | |
| if its python function raises an exception or, uncommonly, returns a value that is not a `State` object. |
There was a problem hiding this comment.
@billpalombi Isn't a task a function? 😅
There was a problem hiding this comment.
Actually I see what you mean now
There was a problem hiding this comment.
I'm going to leave out the State part for now because it doesn't make sense and I don't understand what would cause that. (It can't be that the user-defined function returned an object other than a State...).
docs/concepts/tasks.md
Outdated
| Prefect tasks can automatically retry on failure. To enable retries, pass `retries` and `retry_delay_seconds` parameters to your task. | ||
| Prefect can automatically retry tasks on failure. In Prefect, a task _fails_ | ||
| if it returns a value that is not a `State` object, or if it raises an | ||
| exception. |
There was a problem hiding this comment.
| exception. |
docs/concepts/tasks.md
Outdated
| from random import randint | ||
| from prefect import task | ||
|
|
||
| @task(retries=3) |
There was a problem hiding this comment.
This doesn't work, right? A task must be in a flow.
There was a problem hiding this comment.
RuntimeError: Tasks cannot be run outside of a flow. To call the underlying task function outside of a flow use task.fn()
There was a problem hiding this comment.
This is the definition of a task. You have to call or submit tasks from a flow.
There was a problem hiding this comment.
Ah I see, you didn't intend for this to be a runnable example. Most (all?) of the other code examples that we include in the docs are runnable, so including a code snippet that can't be run in isolation is a departure from the norm. If we are going to include an example that isn't runnable in isolation, I think we should remove the import statements, so it doesn't look like its code meant to be copied, pasted, and run in isolation.
There was a problem hiding this comment.
We also might want to explicitly call out thats its just a definition, and must be called from a flow.
There was a problem hiding this comment.
Ah, gotcha. I see. The other examples in this section aren't runnable, so I didn't even notice! I'll adapt this to have a flow that calls it.
Clean up the docs for task retries.
Checklist
<link to issue>"fix,feature,enhancement,docs.