Confusion around context handler behavior

[flaviuvadan]

Plan

1. Improve documentation on context handlers
2. Consider making Hera accept inline within context definitions of not only scripts but containers, resource, etc.

Discussed in #1252

^{Originally posted by daturkel October 28, 2024}
I'm a bit confused about the behavior of context managers in Hera and exactly how they behave under the hood.

If I have a python prelude like this:

from hera.workflows import Container, Steps, Workflow

def get_container():
    my_container = Container(
        image="my-image",
        command=["bash", "-c"],
        args=["echo hello"],
    )
    return my_container

There are a couple ways I might be inclined to use this container factory function.

I could declare the Container in global scope, which works:

container = get_container()
with Workflow(name="my-workflow", entrypoint="entrypoint") as my_workflow:
    with Steps(name="entrypoint") as my_steps:
        container(name="foo")

I could declare the Container in the Workflow scope, which also works, though I'm not sure what the advantage is:

with Workflow(name="my-workflow", entrypoint="entrypoint") as my_workflow:
    container = get_container()
    with Steps(name="entrypoint") as my_steps:
        container(name="foo")

Lastly, I could declare the container in the Steps scope, which does not work:

with Workflow(name="my-workflow", entrypoint="entrypoint") as my_workflow:
    with Steps(name="entrypoint") as my_steps:
        container = get_container()
        container(name="foo")

# hera.workflows.exceptions.InvalidType: <class 'hera.workflows.container.Container'>

I would love some information on the advantages of the Workflow and Steps context managers and when to use them, and why the third snippet here doesn't work. There doesn't seem to be a ton in the Hera docs on this topic (though maybe I've missed it) and I wouldn't be against contributing some documentation, but first I'll have to understand the behavior better!

There's some relevant discussion on documentation for idiomatic workflows in this issue: #440