[bug/feature request] Documentation for writing operations doesn't match behaviour

[alwaysmpe]

Describe the bug

The documentation page for writing an operation does not match the behaviour. Specifically, documentation says you can use

yield from files.file(
    path="/some/file",
    ...,
)

Running this gives

Exception: Operation called within another operation, this is not allowed! Use the `_inner` function to call the underlying operation.

So this must instead be

yield from files.file._inner(
    path="/some/file",
    ...,
)

Expected behavior

Documentation needs correcting at the least.

However I think it would be quite good if something similar to the documentation worked. This would allow us to group operations together similar to ansible's blocks.

consider the example code:

@operation()
def check_out_code(repo, dest):
    yield files.file(
        name='prepare git credentials',
        path='~/.git-credentials',
        ...,
    )
    yield git.config(
        name='configure git credentials store',
        key='credentials.helper',
        value='store'
    )
    yield git.repo(
        name='checkout code',
        ...,
    )

@operation()
def setup_python_env():
    ...

@operation()
def setup_cron_job():
    ...

@deploy('Install my thing')
def install_my_thing():
    check_out_code(
        name='Check out code for my thing',
        ...,
    )

    setup_python_env(...)
    setup_cron_job(...)

This could also be achieved by adding a @block() style decorator.

Meta

• Include output of pyinfra --support.

    System: Linux
      Platform: Linux-5.15.146.1-microsoft-standard-WSL2-x86_64-with-glibc2.35
      Release: 5.15.146.1-microsoft-standard-WSL2
      Machine: x86_64
    pyinfra: v3.0b0
    Executable: /home/m/build/exp2/.venv/bin/pyinfra
    Python: 3.9.7 (CPython, GCC 12.3.0)

• How was pyinfra installed (source/pip)?
  pip install <3.x branch from github>

[Fizzadar]

Will update the docs, thank you for catching this!

I do agree not having to use the inner attribute would be ideal - however it’s not typing friendly. I couldn’t figure out a sensible way to type check it without using the inner attr (would welcome ideas, as long as there’s not too much magic).

[alwaysmpe]

@Fizzadar are you using a static type checker? I wasn't sure as it's not in the contributing section. I'll have a look.