added suite state xtrigger for back-compat (#5864)

added suite state xtrigger for back commpat
extended back compat a unit test
added deprecation log message
Replace icky unit test with functional test (#4)

---------

Co-authored-by: Mark Dawson <mark.dawson@metoffice.gov.ukpython>

changes.d/5864.feat.md

@@ -0,0 +1 @@
+Reimplemented the `suite-state` xtrigger for interoperability with Cylc 7.

cylc/flow/xtriggers/suite_state.py

@@ -0,0 +1,81 @@
+# THIS FILE IS PART OF THE CYLC WORKFLOW ENGINE.
+# Copyright (C) NIWA & British Crown (Met Office) & Contributors.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from cylc.flow import LOG
+import cylc.flow.flags
+from cylc.flow.xtriggers.workflow_state import workflow_state
+
+if not cylc.flow.flags.cylc7_back_compat:
+    LOG.warning(
+        "The suite_state xtrigger is deprecated. "
+        "Please use the workflow_state xtrigger instead."
+    )
+
+
+def suite_state(suite, task, point, offset=None, status='succeeded',
+                message=None, cylc_run_dir=None, debug=False):
+    """Suite state xtrigger, required for interoperability with Cylc 7.
+
+    * The suite_state xtrigger was renamed to workflow_state, this breaks Cylc 7-8 interoperability.
+    * This suite_state xtrigger replicates workflow_state - ensuring back-support.
+
+    Arguments:
+        suite:
+            The workflow to interrogate.
+        task:
+            The name of the task to query.
+        point:
+            The cycle point.
+        offset:
+            The offset between the cycle this xtrigger is used in and the one
+            it is querying for as an ISO8601 time duration.
+            e.g. PT1H (one hour).
+        status:
+            The task status required for this xtrigger to be satisfied.
+        message:
+            The custom task output required for this xtrigger to be satisfied.
+            .. note::
+
+               This cannot be specified in conjunction with ``status``.
+
+        cylc_run_dir:
+            The directory in which the workflow to interrogate.
+
+            .. note::
+
+               This only needs to be supplied if the workflow is running in a
+               different location to what is specified in the global
+               configuration (usually ``~/cylc-run``).
+
+    Returns:
+        tuple: (satisfied, results)
+
+        satisfied:
+            True if ``satisfied`` else ``False``.
+        results:
+            Dictionary containing the args / kwargs which were provided
+            to this xtrigger.
+
+    """
+    return workflow_state(
+        workflow=suite,
+        task=task,
+        point=point,
+        offset=offset,
+        status=status,
+        message=message,
+        cylc_run_dir=cylc_run_dir
+    )

setup.cfg

@@ -220,6 +220,7 @@ cylc.xtriggers =
     echo = cylc.flow.xtriggers.echo:echo
     wall_clock = cylc.flow.xtriggers.wall_clock:wall_clock
     workflow_state = cylc.flow.xtriggers.workflow_state:workflow_state
+    suite_state = cylc.flow.xtriggers.suite_state:suite_state
     xrandom = cylc.flow.xtriggers.xrandom:xrandom
 
 [bdist_rpm]

tests/functional/xtriggers/04-suite_state.t

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# THIS FILE IS PART OF THE CYLC WORKFLOW ENGINE.
+# Copyright (C) NIWA & British Crown (Met Office) & Contributors.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# Test that deprecation warnings are printed appropriately for the suite_state
+# xtrigger.
+
+. "$(dirname "$0")/test_header"
+
+set_test_number 4
+
+init_workflow "$TEST_NAME_BASE" << __FLOW_CONFIG__
+[scheduling]
+    initial cycle point = 2000
+    [[dependencies]]
+        [[[R1]]]
+            graph = @upstream => foo
+    [[xtriggers]]
+        upstream = suite_state(suite=thorin/oin/gloin, task=mithril, point=1)
+[runtime]
+    [[foo]]
+__FLOW_CONFIG__
+
+msg='WARNING - The suite_state xtrigger is deprecated'
+
+TEST_NAME="${TEST_NAME_BASE}-val"
+run_ok "$TEST_NAME" cylc validate "$WORKFLOW_NAME"
+
+grep_ok "$msg" "${TEST_NAME}.stderr"
+
+# Rename flow.cylc to suite.rc:
+mv "${WORKFLOW_RUN_DIR}/flow.cylc" "${WORKFLOW_RUN_DIR}/suite.rc"
+
+TEST_NAME="${TEST_NAME_BASE}-val-2"
+run_ok "$TEST_NAME" cylc validate "$WORKFLOW_NAME"
+
+grep_fail "$msg" "${TEST_NAME}.stderr"

tests/unit/xtriggers/test_workflow_state.py

@@ -42,7 +42,7 @@ def test_inferred_run(tmp_run_dir: Callable, monkeymock: MonkeyMock):
     assert results['workflow'] == expected_workflow_id
 
 
-def test_back_compat(tmp_run_dir):
+def test_back_compat(tmp_run_dir, caplog):
     """Test workflow_state xtrigger backwards compatibility with Cylc 7
     database."""
     id_ = 'celebrimbor'
@@ -80,7 +80,15 @@ def test_back_compat(tmp_run_dir):
     finally:
         conn.close()
 
+    # Test workflow_state function
     satisfied, _ = workflow_state(id_, task='mithril', point='2012')
     assert satisfied
     satisfied, _ = workflow_state(id_, task='arkenstone', point='2012')
     assert not satisfied
+
+    # Test back-compat (old suite_state function)
+    from cylc.flow.xtriggers.suite_state import suite_state
+    satisfied, _ = suite_state(suite=id_, task='mithril', point='2012')
+    assert satisfied
+    satisfied, _ = suite_state(suite=id_, task='arkenstone', point='2012')
+    assert not satisfied