clean up examples

[zzstoatzz]

• updates all examples to follow python convention w filenames (i.e. underscores not hyphens)
• recommend the runtime module instead of FlowRunContext/TaskRunContext
• use as_completed in task runner concurrency example (existing impl doesn't do what it says it does)

I don't think we ought to recommend the patterns shown in return_custom_state.py and update_flow_run_state_from_hook.py. I imagine these were informed by real use cases, but I would say both of them are anti-patterns. The former should simply use the retry kwargs (retry_delay_seconds and retry_condition_fn) and the latter seems to be a crutch for some infra issue that violates the idea of a state change hook (changing the state itself as a side effect of entering a state is kinda goofy). happy to discuss further

i recognize that if we merge this, we will need to update links here

[EmilRex]

These are all great additions @zzstoatzz! Thanks for the contribution!

[EmilRex]

I don't think we ought to recommend the patterns shown in return_custom_state.py and update_flow_run_state_from_hook.py. I imagine these were informed by real use cases, but I would say both of them are anti-patterns. The former should simply use the retry kwargs (retry_delay_seconds and retry_condition_fn) and the latter seems to be a crutch for some infra issue that violates the idea of a state change hook (changing the state itself as a side effect of entering a state is kinda goofy). happy to discuss further

They are indeed informed by real use cases. They certainly may need to be tweaked, but I think they both demonstrate important concepts:

• return_custom_state.py demonstrates what returning a state does to a flow as opposed to returning an arbitrary result. FWIW I thought it was an elegant way to do a custom retry. What makes it an anti-pattern?
• update_flow_run_state_from_hook.py demonstrates what setting a custom state via the API client looks like. Is there another state we could set that wouldn't be an anti-pattern?

[daniel-prefect]

Note to self to update PrefectHQ/prefect#16966 once this is merged.