Support data, http, resource, and suspend templates in decorator syntax (#1501)

**Pull Request Checklist**
- [x] Tests added
- [x] Documentation/examples added
- [x] [Good commit messages](https://cbea.ms/git-commit/) and/or PR
title

**Description of PR**
Currently, decorator syntax only supports `steps`, `dags`, `script`, and
`container`. This PR will add supports on `data`, `http`, `resource`,
and `suspend_template`.

---------

Signed-off-by: Ukjae Jeong <[email protected]>
Signed-off-by: Ukjae Jeong <[email protected]>
Signed-off-by: Elliot Gunton <[email protected]>
Co-authored-by: Elliot Gunton <[email protected]>

Author: jeongukjae

docs/examples/workflows/experimental/new_container_decorator.md

@@ -39,7 +39,7 @@ This example shows the use of the container decorator and special Input/Output c
     # We then use the decorators of the `Workflow` object
     # to set the entrypoint and create a Container template
     @w.set_entrypoint
-    @w.container(
+    @w.container_template(
         image="busybox",
         command=["sh", "-c"],
         args=["echo Hello {{inputs.parameters.user}} | tee /tmp/hello_world.txt"],

docs/examples/workflows/experimental/new_data_decorator.md

@@ -0,0 +1,77 @@
+# New Data Decorator
+
+
+
+This example shows the use of the data decorator and special Input/Output classes.
+
+
+=== "Hera"
+
+    ```python linenums="1"
+    from typing_extensions import Annotated
+
+    from hera.expr import g, it
+    from hera.shared import global_config
+    from hera.workflows import (
+        Artifact,
+        Input,
+        Output,
+        S3Artifact,
+        Workflow,
+    )
+
+    global_config.experimental_features["decorator_syntax"] = True
+
+
+    # We start by defining our Workflow
+    w = Workflow(generate_name="data-workflow-")
+
+
+    # This defines the template's inputs
+    class MyInput(Input):
+        bucket_name: str = "my-bucket"
+
+
+    class MyOutput(Output):
+        file: Annotated[str, Artifact(path="/file")]
+
+
+    # We then use the decorators of the `Workflow` object
+    # to set the entrypoint and create a Data template
+    @w.set_entrypoint
+    @w.data_template(
+        source=S3Artifact(name="test-bucket", bucket=f"{g.inputs.parameters.bucket_name:$}"),
+        transformations=[g.data.filter(it.ends_with("main.log"))],  # type: ignore
+    )
+    def basic_hello_world(my_input: MyInput) -> MyOutput: ...
+    ```
+
+=== "YAML"
+
+    ```yaml linenums="1"
+    apiVersion: argoproj.io/v1alpha1
+    kind: Workflow
+    metadata:
+      generateName: data-workflow-
+    spec:
+      entrypoint: basic-hello-world
+      templates:
+      - name: basic-hello-world
+        data:
+          transformation:
+          - expression: filter(data, {# endsWith 'main.log'})
+          source:
+            artifactPaths:
+              name: test-bucket
+              s3:
+                bucket: '{{inputs.parameters.bucket_name}}'
+        inputs:
+          parameters:
+          - name: bucket_name
+            default: my-bucket
+        outputs:
+          artifacts:
+          - name: file
+            path: /file
+    ```
+

docs/examples/workflows/experimental/new_http_decorator.md

@@ -0,0 +1,86 @@
+# New Http Decorator
+
+
+
+This example shows the use of the http decorator and special Input/Output classes.
+
+
+=== "Hera"
+
+    ```python linenums="1"
+    from typing_extensions import Annotated
+
+    from hera.expr import g
+    from hera.shared import global_config
+    from hera.workflows import Input, Output, Parameter, Workflow
+    from hera.workflows.models import SuppliedValueFrom, ValueFrom
+
+    global_config.experimental_features["decorator_syntax"] = True
+
+
+    # We start by defining our Workflow
+    w = Workflow(generate_name="http-workflow-")
+
+
+    # This defines the template's inputs
+    class MyInput(Input):
+        url: str = "https://example.com"
+
+
+    class MyOutput(Output):
+        approve: Annotated[
+            str,
+            Parameter(
+                name="approve",
+                value_from=ValueFrom(
+                    supplied=SuppliedValueFrom(),
+                ),
+            ),
+        ]
+
+
+    # We then use the decorators of the `Workflow` object
+    # to set the entrypoint and create a HTTP template
+    @w.set_entrypoint
+    @w.http_template(
+        timeout_seconds=20,
+        url=f"{g.inputs.parameters.url:$}",
+        method="GET",
+        headers=[{"name": "x-header-name", "value": "test-value"}],
+        success_condition=str(g.response.body.contains("google")),  # type: ignore
+        body="test body",
+    )
+    def basic_hello_world(my_input: MyInput) -> MyOutput: ...
+    ```
+
+=== "YAML"
+
+    ```yaml linenums="1"
+    apiVersion: argoproj.io/v1alpha1
+    kind: Workflow
+    metadata:
+      generateName: http-workflow-
+    spec:
+      entrypoint: basic-hello-world
+      templates:
+      - name: basic-hello-world
+        http:
+          body: test body
+          method: GET
+          successCondition: response.body contains 'google'
+          timeoutSeconds: 20
+          url: '{{inputs.parameters.url}}'
+          headers:
+          - name: x-header-name
+            value: test-value
+        inputs:
+          parameters:
+          - name: url
+            default: https://example.com
+        outputs:
+          parameters:
+          - name: approve
+            valueFrom:
+              supplied: {}
+    ```
+

docs/examples/workflows/experimental/new_resource_decorator.md

@@ -0,0 +1,95 @@
+# New Resource Decorator
+
+
+
+This example shows the use of the resource decorator and special Input/Output classes.
+
+
+=== "Hera"
+
+    ```python linenums="1"
+    from typing_extensions import Annotated
+
+    from hera.shared import global_config
+    from hera.workflows import Input, Output, Parameter, Workflow
+
+    global_config.experimental_features["decorator_syntax"] = True
+
+
+    # We start by defining our Workflow
+    w = Workflow(generate_name="resource-workflow-")
+
+
+    # This defines the template's inputs
+    class MyInput(Input):
+        pvc_size: Annotated[
+            int,
+            Parameter(name="pvc-size"),
+        ] = 10
+
+
+    class MyOutput(Output):
+        pvc_name: Annotated[
+            str,
+            Parameter(
+                name="pvc-name",
+                value_from={"jsonPath": "{.metadata.name}"},
+            ),
+        ]
+
+
+    # We then use the decorators of the `Workflow` object
+    # to set the entrypoint and create a Resouruce template
+    @w.set_entrypoint
+    @w.resource_template(
+        action="create",
+        set_owner_reference=True,
+        manifest="""apiVersion: v1
+    kind: PersistentVolumeClaim
+    metadata:
+        generateName: pvc-example-
+    spec:
+        accessModes: ['ReadWriteOnce', 'ReadOnlyMany']
+        resources:
+        requests:
+            storage: '{{inputs.parameters.pvc-size}}'
+    """,
+    )
+    def basic_hello_world(my_input: MyInput) -> MyOutput: ...
+    ```
+
+=== "YAML"
+
+    ```yaml linenums="1"
+    apiVersion: argoproj.io/v1alpha1
+    kind: Workflow
+    metadata:
+      generateName: resource-workflow-
+    spec:
+      entrypoint: basic-hello-world
+      templates:
+      - name: basic-hello-world
+        inputs:
+          parameters:
+          - name: pvc-size
+            default: '10'
+        outputs:
+          parameters:
+          - name: pvc-name
+            valueFrom:
+              jsonPath: '{.metadata.name}'
+        resource:
+          action: create
+          manifest: |
+            apiVersion: v1
+            kind: PersistentVolumeClaim
+            metadata:
+                generateName: pvc-example-
+            spec:
+                accessModes: ['ReadWriteOnce', 'ReadOnlyMany']
+                resources:
+                requests:
+                    storage: '{{inputs.parameters.pvc-size}}'
+          setOwnerReference: true
+    ```
+

docs/examples/workflows/experimental/new_suspend_decorator.md

@@ -0,0 +1,80 @@
+# New Suspend Decorator
+
+
+
+This example shows the use of the suspend decorator and special Input/Output classes.
+
+
+=== "Hera"
+
+    ```python linenums="1"
+    from typing_extensions import Annotated
+
+    from hera.shared import global_config
+    from hera.workflows import Input, Output, Parameter, Workflow
+    from hera.workflows.models import SuppliedValueFrom, ValueFrom
+
+    global_config.experimental_features["decorator_syntax"] = True
+
+
+    # We start by defining our Workflow
+    w = Workflow(generate_name="suspend-workflow-")
+
+
+    # This defines the template's inputs
+    class MyInput(Input):
+        approve: Annotated[
+            str,
+            Parameter(
+                description="Choose YES to continue workflow and deploy to production",
+                enum=["YES", "NO"],
+            ),
+        ] = "NO"
+
+
+    class MyOutput(Output):
+        approve: Annotated[
+            str,
+            Parameter(
+                name="approve",
+                value_from=ValueFrom(
+                    supplied=SuppliedValueFrom(),
+                ),
+            ),
+        ]
+
+
+    # We then use the decorators of the `Workflow` object
+    # to set the entrypoint and create a Suspend template
+    @w.set_entrypoint
+    @w.suspend_template()
+    def basic_hello_world(my_input: MyInput) -> MyOutput: ...
+    ```
+
+=== "YAML"
+
+    ```yaml linenums="1"
+    apiVersion: argoproj.io/v1alpha1
+    kind: Workflow
+    metadata:
+      generateName: suspend-workflow-
+    spec:
+      entrypoint: basic-hello-world
+      templates:
+      - name: basic-hello-world
+        inputs:
+          parameters:
+          - name: approve
+            default: 'NO'
+            description: Choose YES to continue workflow and deploy to production
+            enum:
+            - 'YES'
+            - 'NO'
+        outputs:
+          parameters:
+          - name: approve
+            valueFrom:
+              supplied: {}
+        suspend: {}
+    ```
+

docs/user-guides/decorators.md

@@ -10,8 +10,12 @@ The decorators introduced in v5.16 are members of the `Workflow` class, meaning
 
 * `dag`
 * `steps`
-* `container`
 * `script`
+* `container_template` (replacing the deprecated `container`)
+* `data_template`
+* `http_template`
+* `resource_template`
+* `suspend_template`
 * `set_entrypoint`
 
 If you want to declare inputs and outputs in your templates, you must use the special `Input` and `Output` Pydantic
@@ -44,9 +48,9 @@ run as many _dependent_ templates in parallel as possible then use a DAG, which
 first. If you want to run templates sequentially, and have more control over the running order and when to parallelise,
 use `steps`.
 
-## `container`
+## `container_template`
 
-The `container` decorator is a convenient way to declare your container templates in Python, though the feature set is
+The `container_template` decorator is a convenient way to declare your container templates in Python, though the feature set is
 limited. You can specify the `command` and `args` in the decorator arguments, and the inputs and outputs in the function
 signature. You can leave the function as a stub or add some code to be able to run the function locally - consider it as
 a "mockable" function.
@@ -61,6 +65,16 @@ decorator.
 Using this decorator will enforce usage of the `RunnerScriptConstructor`, so you must ensure you use an image built from
 your code.
 
+## `data_template`, `http_template`, `resource_template`, and `suspend_template`
+
+These decorators allow you to define additional Argo Workflow template types in a Pythonic way. For more information on
+how to use these templates, please refer to the relevant examples.
+
+- [`data_template` decorator example](../examples/workflows/experimental/new_data_decorator.md)
+- [`http_template` decorator example](../examples/workflows/experimental/new_http_decorator.md)
+- [`resource_template` decorator example](../examples/workflows/experimental/new_resource_decorator.md)
+- [`suspend_template` decorator example](../examples/workflows/experimental/new_suspend_decorator.md)
+
 ## `set_entrypoint`
 
 The `set_entrypoint` decorator is a simple decorator with no arguments, used to set the `entrypoint` of the `Workflow` that you're declaring.