Make path optional for input Artifact annotations; deprecate as_name (#…

…792)

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

**Description of PR**
See #787.

Also deprecated `as_name` in favour of `with_name` for artifacts, as the
former builds the artifact rather than making a copy. Also, it now
mirrors the naming and functionality of the `with_name` function from
`Parameter`.

---------

Signed-off-by: Elliot Gunton <egunton@bloomberg.net>
Co-authored-by: Sambhav Kothari <skothari44@bloomberg.net>

docs/examples/workflows/artifact.md

@@ -28,7 +28,7 @@ task, consumer, takes this artifact, places it at its own `/file` path, and prin
     with Workflow(generate_name="artifact-", entrypoint="d") as w:
         with DAG(name="d"):
             w_ = writer()
-            c = consumer(arguments=w_.get_artifact("out-art").as_name("in-art"))
+            c = consumer(arguments=w_.get_artifact("out-art").with_name("in-art"))
             w_ >> c
     ```
 

docs/examples/workflows/artifact_with_fanout.md

@@ -40,7 +40,7 @@
     with Workflow(generate_name="artifact-with-fanout-", entrypoint="d") as w:
         with DAG(name="d"):
             w_ = writer()
-            f = fanout(arguments=w_.get_artifact("out-art").as_name("in-art"))
+            f = fanout(arguments=w_.get_artifact("out-art").with_name("in-art"))
             c = consumer(with_param=f.result)
             w_ >> f >> c
     ```

docs/examples/workflows/script_annotations_artifact_custom_volume.md

@@ -48,7 +48,12 @@ This example will reuse the outputs volume across script steps.
     @script(
         constructor=RunnerScriptConstructor(),  # Has no outputs
     )
-    def use_artifact(successor_in: Annotated[int, Artifact(name="successor_in", loader=ArtifactLoader.json)]):
+    def use_artifact(
+        successor_in: Annotated[
+            int,
+            Artifact(name="successor_in", loader=ArtifactLoader.json),
+        ]
+    ):
         print(successor_in)
 
 
@@ -85,7 +90,7 @@ This example will reuse the outputs volume across script steps.
     ) as w:
         with Steps(name="my-steps") as s:
             out_to_empty_dir = output_artifact_empty_dir(arguments={"a_number": 3})
-            use_artifact(arguments=[out_to_empty_dir.get_artifact("successor_out").as_name("successor_in")])
+            use_artifact(arguments=[out_to_empty_dir.get_artifact("successor_out").with_name("successor_in")])
 
             out_to_my_vol = output_artifact_existing_vol(arguments={"a_number": 3})
             use_artifact_existing_vol()
@@ -155,6 +160,7 @@ This example will reuse the outputs volume across script steps.
       - inputs:
           artifacts:
           - name: successor_in
+            path: /tmp/hera/inputs/artifacts/successor_in
         name: use-artifact
         script:
           args:

docs/examples/workflows/script_annotations_artifact_loaders.md

@@ -0,0 +1,133 @@
+# Script Annotations Artifact Loaders
+
+
+
+
+
+
+=== "Hera"
+
+    ```python linenums="1"
+    import json
+    from pathlib import Path
+    from typing import Dict
+
+    try:
+        from typing import Annotated  # type: ignore
+    except ImportError:
+        from typing_extensions import Annotated  # type: ignore
+
+    from hera.shared import global_config
+    from hera.workflows import Artifact, ArtifactLoader, Parameter, Steps, Workflow, script
+
+    global_config.experimental_features["script_annotations"] = True
+    global_config.experimental_features["script_runner"] = True
+
+
+    @script(constructor="runner")
+    def output_dict_artifact(
+        a_number: Annotated[int, Parameter(name="a_number")],
+    ) -> Annotated[Dict[str, int], Artifact(name="a_dict")]:
+        return {"your-value": a_number}
+
+
+    @script(constructor="runner")
+    def artifact_loaders(
+        a_file_as_path: Annotated[Path, Artifact(name="my-artifact-path", loader=None)],
+        a_file_as_str: Annotated[str, Artifact(name="my-artifact-as-str", loader=ArtifactLoader.file)],
+        a_file_as_json: Annotated[Dict, Artifact(name="my-artifact-as-json", loader=ArtifactLoader.json)],
+    ):
+        assert a_file_as_path.read_text() == a_file_as_str
+        assert json.loads(a_file_as_str) == a_file_as_json
+        print(a_file_as_path)
+        print(a_file_as_str)
+        print(a_file_as_json)
+
+
+    with Workflow(generate_name="test-input-annotations-", entrypoint="my-steps") as w:
+        with Steps(name="my-steps") as s:
+            out = output_dict_artifact(arguments={"a_number": 3})
+            artifact_loaders(
+                arguments=[
+                    out.get_artifact("a_dict").with_name("my-artifact-path"),
+                    out.get_artifact("a_dict").with_name("my-artifact-as-str"),
+                    out.get_artifact("a_dict").with_name("my-artifact-as-json"),
+                ]
+            )
+    ```
+
+=== "YAML"
+
+    ```yaml linenums="1"
+    apiVersion: argoproj.io/v1alpha1
+    kind: Workflow
+    metadata:
+      generateName: test-input-annotations-
+    spec:
+      entrypoint: my-steps
+      templates:
+      - name: my-steps
+        steps:
+        - - arguments:
+              parameters:
+              - name: a_number
+                value: '3'
+            name: output-dict-artifact
+            template: output-dict-artifact
+        - - arguments:
+              artifacts:
+              - from: '{{steps.output-dict-artifact.outputs.artifacts.a_dict}}'
+                name: my-artifact-path
+              - from: '{{steps.output-dict-artifact.outputs.artifacts.a_dict}}'
+                name: my-artifact-as-str
+              - from: '{{steps.output-dict-artifact.outputs.artifacts.a_dict}}'
+                name: my-artifact-as-json
+            name: artifact-loaders
+            template: artifact-loaders
+      - inputs:
+          parameters:
+          - name: a_number
+        name: output-dict-artifact
+        outputs:
+          artifacts:
+          - name: a_dict
+            path: /tmp/hera/outputs/artifacts/a_dict
+        script:
+          args:
+          - -m
+          - hera.workflows.runner
+          - -e
+          - examples.workflows.script_annotations_artifact_loaders:output_dict_artifact
+          command:
+          - python
+          env:
+          - name: hera__script_annotations
+            value: ''
+          - name: hera__outputs_directory
+            value: /tmp/hera/outputs
+          image: python:3.8
+          source: '{{inputs.parameters}}'
+      - inputs:
+          artifacts:
+          - name: my-artifact-path
+            path: /tmp/hera/inputs/artifacts/my-artifact-path
+          - name: my-artifact-as-str
+            path: /tmp/hera/inputs/artifacts/my-artifact-as-str
+          - name: my-artifact-as-json
+            path: /tmp/hera/inputs/artifacts/my-artifact-as-json
+        name: artifact-loaders
+        script:
+          args:
+          - -m
+          - hera.workflows.runner
+          - -e
+          - examples.workflows.script_annotations_artifact_loaders:artifact_loaders
+          command:
+          - python
+          env:
+          - name: hera__script_annotations
+            value: ''
+          image: python:3.8
+          source: '{{inputs.parameters}}'
+    ```
+

docs/examples/workflows/script_annotations_artifact_outputs_defaults.md

@@ -38,7 +38,16 @@ This example will reuse the outputs volume across script steps.
 
 
     @script(constructor="runner")
-    def use_artifact(successor_in: Annotated[int, Artifact(name="successor_in", loader=ArtifactLoader.json)]):
+    def use_artifact(
+        successor_in: Annotated[
+            int,
+            Artifact(
+                name="successor_in",
+                path="/tmp/file",
+                loader=ArtifactLoader.json,
+            ),
+        ]
+    ):
         print(successor_in)
 
 
@@ -49,7 +58,7 @@ This example will reuse the outputs volume across script steps.
     ) as w:
         with Steps(name="my-steps") as s:
             out = output_artifact(arguments={"a_number": 3})
-            use_artifact(arguments=[out.get_artifact("successor_out").as_name("successor_in")])
+            use_artifact(arguments=[out.get_artifact("successor_out").with_name("successor_in")])
     ```
 
 === "YAML"
@@ -102,6 +111,7 @@ This example will reuse the outputs volume across script steps.
       - inputs:
           artifacts:
           - name: successor_in
+            path: /tmp/file
         name: use-artifact
         script:
           args:

docs/examples/workflows/script_annotations_artifact_passing.md

@@ -54,7 +54,7 @@ This example will reuse the outputs volume across script steps.
     ) as w:
         with Steps(name="my-steps") as s:
             out = output_artifact(arguments={"a_number": 3})
-            use_artifact(arguments=[out.get_artifact("successor_out").as_name("successor_in")])
+            use_artifact(arguments=[out.get_artifact("successor_out").with_name("successor_in")])
     ```
 
 === "YAML"

docs/examples/workflows/script_annotations_inputs.md

@@ -8,6 +8,8 @@
 === "Hera"
 
     ```python linenums="1"
+    from typing import Dict
+
     try:
         from typing import Annotated  # type: ignore
     except ImportError:
@@ -20,28 +22,40 @@
     global_config.experimental_features["script_runner"] = True
 
 
+    @script(constructor="runner")
+    def output_dict_artifact(
+        a_number: Annotated[int, Parameter(name="a_number")],
+    ) -> Annotated[Dict[str, int], Artifact(name="a_dict")]:
+        return {"your-value": a_number}
+
+
     @script(constructor="runner")
     def echo_all(
         an_int: Annotated[int, Parameter(description="an_int parameter", default=1)],
         a_bool: Annotated[bool, Parameter(description="a_bool parameter", default=True)],
         a_string: Annotated[str, Parameter(description="a_string parameter", default="a")],
-        # note that this artifact is loaded from tmp/file into an_artifact as a string
-        an_artifact: Annotated[str, Artifact(name="my-artifact", path="tmp/file", loader=ArtifactLoader.file)],
+        # note that this artifact is loaded from /tmp/file into an_artifact as a string
+        an_artifact: Annotated[str, Artifact(name="my-artifact", path="/tmp/file", loader=ArtifactLoader.file)],
+        # note that this automatically uses the path /tmp/hera/inputs/artifacts/my-artifact-no-path
+        an_artifact_no_path: Annotated[str, Artifact(name="my-artifact-no-path", loader=ArtifactLoader.file)],
     ):
         print(an_int)
         print(a_bool)
         print(a_string)
         print(an_artifact)
+        print(an_artifact_no_path)
 
 
     with Workflow(generate_name="test-input-annotations-", entrypoint="my-steps") as w:
         with Steps(name="my-steps") as s:
+            out = output_dict_artifact(arguments={"a_number": 3})
             echo_all(
                 arguments=[
                     Parameter(name="an_int", value=1),
                     Parameter(name="a_bool", value=True),
                     Parameter(name="a_string", value="a"),
-                    Artifact(name="my-artifact", from_="somewhere"),
+                    out.get_artifact("a_dict").with_name("my-artifact"),
+                    out.get_artifact("a_dict").with_name("my-artifact-no-path"),
                 ]
             )
     ```
@@ -58,10 +72,18 @@
       templates:
       - name: my-steps
         steps:
+        - - arguments:
+              parameters:
+              - name: a_number
+                value: '3'
+            name: output-dict-artifact
+            template: output-dict-artifact
         - - arguments:
               artifacts:
-              - from: somewhere
+              - from: '{{steps.output-dict-artifact.outputs.artifacts.a_dict}}'
                 name: my-artifact
+              - from: '{{steps.output-dict-artifact.outputs.artifacts.a_dict}}'
+                name: my-artifact-no-path
               parameters:
               - name: an_int
                 value: '1'
@@ -71,10 +93,35 @@
                 value: a
             name: echo-all
             template: echo-all
+      - inputs:
+          parameters:
+          - name: a_number
+        name: output-dict-artifact
+        outputs:
+          artifacts:
+          - name: a_dict
+            path: /tmp/hera/outputs/artifacts/a_dict
+        script:
+          args:
+          - -m
+          - hera.workflows.runner
+          - -e
+          - examples.workflows.script_annotations_inputs:output_dict_artifact
+          command:
+          - python
+          env:
+          - name: hera__script_annotations
+            value: ''
+          - name: hera__outputs_directory
+            value: /tmp/hera/outputs
+          image: python:3.8
+          source: '{{inputs.parameters}}'
       - inputs:
           artifacts:
           - name: my-artifact
-            path: tmp/file
+            path: /tmp/file
+          - name: my-artifact-no-path
+            path: /tmp/hera/inputs/artifacts/my-artifact-no-path
           parameters:
           - default: '1'
             description: an_int parameter

docs/examples/workflows/script_artifact_passing.md

@@ -29,7 +29,7 @@
             whale_step = whalesay(name="generate-artifact")
             print_message(
                 name="consume-artifact",
-                arguments=whale_step.get_artifact("hello-art").as_name("message"),
+                arguments=whale_step.get_artifact("hello-art").with_name("message"),
             )
     ```
 

docs/examples/workflows/upstream/artifact_passing.md

@@ -34,7 +34,7 @@ The upstream example can be [found here](https://github.com/argoproj/argo-workfl
             Step(
                 name="consume-artifact",
                 template=print_message,
-                arguments=gen_step.get_artifact("hello-art").as_name("message"),
+                arguments=gen_step.get_artifact("hello-art").with_name("message"),
             )
     ```
 

examples/workflows/artifact.py

@@ -21,5 +21,5 @@ def consumer():
 with Workflow(generate_name="artifact-", entrypoint="d") as w:
     with DAG(name="d"):
         w_ = writer()
-        c = consumer(arguments=w_.get_artifact("out-art").as_name("in-art"))
+        c = consumer(arguments=w_.get_artifact("out-art").with_name("in-art"))
         w_ >> c

examples/workflows/artifact_with_fanout.py

@@ -30,6 +30,6 @@ def consumer(i: int):
 with Workflow(generate_name="artifact-with-fanout-", entrypoint="d") as w:
     with DAG(name="d"):
         w_ = writer()
-        f = fanout(arguments=w_.get_artifact("out-art").as_name("in-art"))
+        f = fanout(arguments=w_.get_artifact("out-art").with_name("in-art"))
         c = consumer(with_param=f.result)
         w_ >> f >> c

examples/workflows/script-annotations-artifact-custom-volume.yaml

@@ -59,6 +59,7 @@ spec:
   - inputs:
       artifacts:
       - name: successor_in
+        path: /tmp/hera/inputs/artifacts/successor_in
     name: use-artifact
     script:
       args: