cylc set: update docs and test

cylc · Jan 22, 2025 · b4f7199 · b4f7199
1 parent 1c27a0f
commit b4f7199
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 11 deletions.
diff --git a/cylc/flow/network/schema.py b/cylc/flow/network/schema.py
@@ -2184,7 +2184,8 @@ class Meta:
         description = sstrip("""
             Set task prerequisites or outputs.
 
-            By default, set all required outputs for target task(s).
+            By default, set all required outputs for target task(s) (including
+            `submitted`, `started` and `succeeded` even if they are optional).
 
             Setting prerequisites contributes to the task's readiness to run.
 

diff --git a/cylc/flow/scripts/set.py b/cylc/flow/scripts/set.py
@@ -20,7 +20,8 @@
 
 Command to manually set task prerequisites and outputs in running workflows.
 
-By default, it sets all required outputs (note "succeeded" may be optional).
+By default, it sets all required outputs (including "submitted", "started" and
+"succeeded" even if they are optional).
 
 Setting task prerequisites:
   - contributes to the task's readiness to run, and
@@ -35,14 +36,15 @@
   - contributes to a task's completion, and
   - spawns downstream tasks that depend on those outputs
 
-Note setting final outputs (succeeded, failed, expired) also sets task state.
-Setting the started and submitted outputs spawns downstream tasks that depend
-on them but does not affect task state, because there is no running job.
+Note setting final outputs ("succeeded", "failed", "expired") also sets task
+state. Setting the "started" and "submitted" outputs spawns downstream tasks
+that depend on them but does not affect task state, because there is no
+running job.
 
 Implied outputs are set automatically:
-  - started implies submitted
-  - succeeded and failed imply started
-  - custom outputs and expired do not imply other outputs
+  - "started" implies "submitted"
+  - "succeeded" and "failed" imply "started"
+  - custom outputs and "expired" do not imply other outputs
 
 For custom outputs, use the output names not the associated task messages:
 [runtime]

diff --git a/tests/integration/scripts/test_set.py b/tests/integration/scripts/test_set.py
@@ -186,10 +186,12 @@ async def test_no_required_outputs(flow, scheduler, start):
                     'R1': r"""
                         foo? => alpha
                         foo:submitted? => bravo
+                        foo:started? => charlie
                         foo:x => xray
-                        # Not emitted because optional, and not on success
-                        # pathway:
+                        # Optional custom outputs not emitted:
                         foo:y? => yankee
+                        # Non-success-pathway outputs not emitted:
+                        foo:submit-failed? => delta
                     """,
                 },
             },
@@ -208,4 +210,9 @@ async def test_no_required_outputs(flow, scheduler, start):
         await run_cmd(
             set_prereqs_and_outputs(schd, [foo.identity], [FLOW_ALL])
         )
-        assert schd.pool.get_task_ids() == {'1/alpha', '1/bravo', '1/xray'}
+        assert schd.pool.get_task_ids() == {
+            '1/alpha',
+            '1/bravo',
+            '1/charlie',
+            '1/xray',
+        }