fix: Handle multiline strings in yaml serialization. (#935)

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

**Description of PR**
Currently, multiline strings serialize to yaml in a way that is not true
to the original content.

For example, copying [argo workflows' exit-handler
example](https://github.com/argoproj/argo-workflows/blob/main/examples/exit-handler-slack.yaml)

excerpt:
```yaml
      args: [
        "curl -X POST --data-urlencode 'payload={
          \"text\": \"{{workflow.name}} finished\",
          \"blocks\": [
            {
              \"type\": \"section\",
              \"text\": {
                \"type\": \"mrkdwn\",
                \"text\": \"Workflow {{workflow.name}} {{workflow.status}}\",
              }
            }
          ]
        }'
        YOUR_WEBHOOK_URL_HERE"
      ]
```

currently produces:
```yaml
        args:
        - "curl -X POST --data-urlencode 'payload={\n          \"text\": \"{{workflow.name}}\
          \ finished\",\n          \"blocks\": [\n            {\n              \"\
          type\": \"section\",\n              \"text\": {\n                \"type\"\
          : \"mrkdwn\",\n                \"text\": \"Workflow {{workflow.name}} {{workflow.status}}\"\
          ,\n              }\n            }\n          ]\n        }'\n        YOUR_WEBHOOK_URL_HERE\"\
          \n        "
```

whereas this PR produces:
```yaml
        args:
        - |-
          curl -X POST --data-urlencode 'payload={
                    "text": "{{workflow.name}} finished",
                    "blocks": [
                      {
                        "type": "section",
                        "text": {
                          "type": "mrkdwn",
                          "text": "Workflow {{workflow.name}} {{workflow.status}}",
                        }
                      }
                    ]
                  }'
                  YOUR_WEBHOOK_URL_HERE";
```

---

Note that this does not fix
yaml/pyyaml#121 (comment). That
is, the following example will revert back to original formatting due to
the trailing `\n` at the end of the string.
```python
args="""
two
"""
```

I would suggest switching `ruamel.yaml` over pyyaml just generally,
which would fix this issue, but that's probably going to be considered a
breaking change.

In any case is probably more tangential to the root issue above (which
affects both libraries in the same way).

---------

Signed-off-by: DanCardin <[email protected]>
Signed-off-by: DanCardin <[email protected]>
Co-authored-by: Elliot Gunton <[email protected]>
Co-authored-by: Flaviu Vadan <[email protected]>

docs/examples/workflows/artifacts/artifact.md

@@ -65,8 +65,12 @@ task, consumer, takes this artifact, places it at its own `/file` path, and prin
           command:
           - python
           image: python:3.8
-          source: "import os\nimport sys\nsys.path.append(os.getcwd())\nwith open('/tmp/file',\
-            \ 'w+') as f:\n    f.write('Hello, world!')"
+          source: |-
+            import os
+            import sys
+            sys.path.append(os.getcwd())
+            with open('/tmp/file', 'w+') as f:
+                f.write('Hello, world!')
       - inputs:
           artifacts:
           - name: in-art
@@ -76,7 +80,11 @@ task, consumer, takes this artifact, places it at its own `/file` path, and prin
           command:
           - python
           image: python:3.8
-          source: "import os\nimport sys\nsys.path.append(os.getcwd())\nwith open('/tmp/file',\
-            \ 'r') as f:\n    print(f.readlines())"
+          source: |-
+            import os
+            import sys
+            sys.path.append(os.getcwd())
+            with open('/tmp/file', 'r') as f:
+                print(f.readlines())
     ```
 

docs/examples/workflows/artifacts/artifact_with_fanout.md

@@ -86,9 +86,14 @@
           command:
           - python
           image: python:3.8
-          source: "import os\nimport sys\nsys.path.append(os.getcwd())\nimport json\n\
-            with open('/tmp/file', 'w+') as f:\n    for i in range(10):\n        f.write(json.dumps(i)\
-            \ + '\\n')"
+          source: |-
+            import os
+            import sys
+            sys.path.append(os.getcwd())
+            import json
+            with open('/tmp/file', 'w+') as f:
+                for i in range(10):
+                    f.write(json.dumps(i) + '\n')
       - inputs:
           artifacts:
           - name: in-art
@@ -98,10 +103,17 @@
           command:
           - python
           image: python:3.8
-          source: "import os\nimport sys\nsys.path.append(os.getcwd())\nimport json\n\
-            import sys\nindices = []\nwith open('/tmp/file', 'r') as f:\n    for line\
-            \ in f.readlines():\n        indices.append(line.strip())\njson.dump(indices,\
-            \ sys.stdout)"
+          source: |-
+            import os
+            import sys
+            sys.path.append(os.getcwd())
+            import json
+            import sys
+            indices = []
+            with open('/tmp/file', 'r') as f:
+                for line in f.readlines():
+                    indices.append(line.strip())
+            json.dump(indices, sys.stdout)
       - inputs:
           parameters:
           - name: i
@@ -110,19 +122,14 @@
           command:
           - python
           image: python:3.8
-          source: 'import os
-
+          source: |-
+            import os
             import sys
-
             sys.path.append(os.getcwd())
-
             import json
+            try: i = json.loads(r'''{{inputs.parameters.i}}''')
+            except: i = r'''{{inputs.parameters.i}}'''
 
-            try: i = json.loads(r''''''{{inputs.parameters.i}}'''''')
-
-            except: i = r''''''{{inputs.parameters.i}}''''''
-
-
-            print(i)'
+            print(i)
     ```
 

docs/examples/workflows/daemon.md

@@ -77,12 +77,21 @@ http requests to the server.
           command:
           - python
           image: python:3.8
-          source: "import os\nimport sys\nsys.path.append(os.getcwd())\nfrom http.server\
-            \ import BaseHTTPRequestHandler, HTTPServer\n\nclass MyServer(BaseHTTPRequestHandler):\n\
-            \n    def do_GET(self):\n        self.send_response(200)\n        self.send_header('Content-type',\
-            \ 'application/json')\n        self.end_headers()\n        self.wfile.write(bytes(\"\
-            {'name':'John'}\", 'utf-8'))\nwebServer = HTTPServer(('0.0.0.0', 8080), MyServer)\n\
-            webServer.serve_forever()"
+          source: |-
+            import os
+            import sys
+            sys.path.append(os.getcwd())
+            from http.server import BaseHTTPRequestHandler, HTTPServer
+
+            class MyServer(BaseHTTPRequestHandler):
+
+                def do_GET(self):
+                    self.send_response(200)
+                    self.send_header('Content-type', 'application/json')
+                    self.end_headers()
+                    self.wfile.write(bytes("{'name':'John'}", 'utf-8'))
+            webServer = HTTPServer(('0.0.0.0', 8080), MyServer)
+            webServer.serve_forever()
       - inputs:
           parameters:
           - name: ip
@@ -91,33 +100,21 @@ http requests to the server.
           command:
           - python
           image: python:3.8
-          source: 'import os
-
+          source: |-
+            import os
             import sys
-
             sys.path.append(os.getcwd())
-
             import json
-
-            try: ip = json.loads(r''''''{{inputs.parameters.ip}}'''''')
-
-            except: ip = r''''''{{inputs.parameters.ip}}''''''
-
+            try: ip = json.loads(r'''{{inputs.parameters.ip}}''')
+            except: ip = r'''{{inputs.parameters.ip}}'''
 
             import http.client
-
             import os
-
             print(os.environ)
-
-            server_ip = ip.replace(''"'', '''')
-
-            connection = http.client.HTTPConnection(''{server_ip}:8080''.format(server_ip=server_ip))
-
-            connection.request(''GET'', ''/'')
-
+            server_ip = ip.replace('"', '')
+            connection = http.client.HTTPConnection('{server_ip}:8080'.format(server_ip=server_ip))
+            connection.request('GET', '/')
             response = connection.getresponse()
-
-            print(response.read())'
+            print(response.read())
     ```
 

docs/examples/workflows/dags/any_success_all_fail.md

@@ -84,10 +84,18 @@
           command:
           - python
           image: python:3.8
-          source: "import os\nimport sys\nsys.path.append(os.getcwd())\nimport json\n\
-            try: a = json.loads(r'''{{inputs.parameters.a}}''')\nexcept: a = r'''{{inputs.parameters.a}}'''\n\
-            \nimport random\nrandom.seed(a)\nif random.random() < 0.5:\n    raise Exception('Oh,\
-            \ no!')"
+          source: |-
+            import os
+            import sys
+            sys.path.append(os.getcwd())
+            import json
+            try: a = json.loads(r'''{{inputs.parameters.a}}''')
+            except: a = r'''{{inputs.parameters.a}}'''
+
+            import random
+            random.seed(a)
+            if random.random() < 0.5:
+                raise Exception('Oh, no!')
       - inputs:
           parameters:
           - name: a
@@ -96,20 +104,15 @@
           command:
           - python
           image: python:3.8
-          source: 'import os
-
+          source: |-
+            import os
             import sys
-
             sys.path.append(os.getcwd())
-
             import json
+            try: a = json.loads(r'''{{inputs.parameters.a}}''')
+            except: a = r'''{{inputs.parameters.a}}'''
 
-            try: a = json.loads(r''''''{{inputs.parameters.a}}'''''')
-
-            except: a = r''''''{{inputs.parameters.a}}''''''
-
-
-            raise Exception(a)'
+            raise Exception(a)
       - inputs:
           parameters:
           - name: a
@@ -118,19 +121,14 @@
           command:
           - python
           image: python:3.8
-          source: 'import os
-
+          source: |-
+            import os
             import sys
-
             sys.path.append(os.getcwd())
-
             import json
+            try: a = json.loads(r'''{{inputs.parameters.a}}''')
+            except: a = r'''{{inputs.parameters.a}}'''
 
-            try: a = json.loads(r''''''{{inputs.parameters.a}}'''''')
-
-            except: a = r''''''{{inputs.parameters.a}}''''''
-
-
-            print(a)'
+            print(a)
     ```
 

docs/examples/workflows/dags/callable_dag.md

@@ -66,20 +66,15 @@
           command:
           - python
           image: python:3.8
-          source: 'import os
-
+          source: |-
+            import os
             import sys
-
             sys.path.append(os.getcwd())
-
             import json
+            try: name = json.loads(r'''{{inputs.parameters.name}}''')
+            except: name = r'''{{inputs.parameters.name}}'''
 
-            try: name = json.loads(r''''''{{inputs.parameters.name}}'''''')
-
-            except: name = r''''''{{inputs.parameters.name}}''''''
-
-
-            print(''Hello, {name}!''.format(name=name))'
+            print('Hello, {name}!'.format(name=name))
       - dag:
           tasks:
           - arguments:

docs/examples/workflows/dags/complex_deps.md

@@ -76,8 +76,16 @@
           command:
           - python
           image: python:3.8
-          source: "import os\nimport sys\nsys.path.append(os.getcwd())\nimport json\n\
-            try: p = json.loads(r'''{{inputs.parameters.p}}''')\nexcept: p = r'''{{inputs.parameters.p}}'''\n\
-            \nif p < 0.5:\n    raise Exception(p)\nprint(42)"
+          source: |-
+            import os
+            import sys
+            sys.path.append(os.getcwd())
+            import json
+            try: p = json.loads(r'''{{inputs.parameters.p}}''')
+            except: p = r'''{{inputs.parameters.p}}'''
+
+            if p < 0.5:
+                raise Exception(p)
+            print(42)
     ```
 

docs/examples/workflows/dags/conditional.md

@@ -67,31 +67,34 @@ This example showcases conditional execution on success, failure, and error
           command:
           - python
           image: python:3.8
-          source: "import os\nimport sys\nsys.path.append(os.getcwd())\nimport random\n\
-            p = random.random()\nif p <= 0.5:\n    raise Exception('failure')\nprint('success')"
+          source: |-
+            import os
+            import sys
+            sys.path.append(os.getcwd())
+            import random
+            p = random.random()
+            if p <= 0.5:
+                raise Exception('failure')
+            print('success')
       - name: success
         script:
           command:
           - python
           image: python:3.8
-          source: 'import os
-
+          source: |-
+            import os
             import sys
-
             sys.path.append(os.getcwd())
-
-            print(''success'')'
+            print('success')
       - name: failure
         script:
           command:
           - python
           image: python:3.8
-          source: 'import os
-
+          source: |-
+            import os
             import sys
-
             sys.path.append(os.getcwd())
-
-            print(''failure'')'
+            print('failure')
     ```
 

docs/examples/workflows/dags/dag_conditional_on_task_status.md

@@ -63,31 +63,32 @@
           command:
           - python
           image: python:3.8
-          source: "import os\nimport sys\nsys.path.append(os.getcwd())\nimport random\n\
-            if random.randint(0, 1) == 0:\n    raise ValueError"
+          source: |-
+            import os
+            import sys
+            sys.path.append(os.getcwd())
+            import random
+            if random.randint(0, 1) == 0:
+                raise ValueError
       - name: when-failed
         script:
           command:
           - python
           image: python:3.8
-          source: 'import os
-
+          source: |-
+            import os
             import sys
-
             sys.path.append(os.getcwd())
-
-            print(''It was a failure'')'
+            print('It was a failure')
       - name: when-succeeded
         script:
           command:
           - python
           image: python:3.8
-          source: 'import os
-
+          source: |-
+            import os
             import sys
-
             sys.path.append(os.getcwd())
-
-            print(''It was a success'')'
+            print('It was a success')
     ```
 

docs/examples/workflows/dags/dag_conditional_parameters.md

@@ -77,9 +77,9 @@
           command:
           - python
           image: python:alpine3.6
-          source: 'import random
-
-            print(''heads'' if random.randint(0, 1) == 0 else ''tails'')'
+          source: |-
+            import random
+            print('heads' if random.randint(0, 1) == 0 else 'tails')
       - name: heads
         script:
           command: