Allow CLI use without ecFlow installed (#965)

* first pass

* dev version bump and test

* remove .dev from version

* tidy

* remove extra line

* add installation note

* Apply suggestions from code review

Co-authored-by: Paul Madden <136389411+maddenp-cu@users.noreply.github.com>

* WIP

* remove lazy imports

* typo

* update import

---------

Co-authored-by: Paul Madden <136389411+maddenp-cu@users.noreply.github.com>

Author: elcarpenterNOAA

docs/sections/user_guide/installation.rst

@@ -97,3 +97,7 @@ If you are using an app that has its own environment requirements that do not wo
 
       cd src/
       pip install .
+
+ .. note::
+   
+   Since ecFlow is not currently published to PyPI, it cannot be installed as a pip dependency. Thus, the ``ecflow`` mode is available only when ecFlow is separately available.

src/uwtools/cli.py

@@ -22,7 +22,6 @@
 import uwtools.api
 import uwtools.api.config
 import uwtools.api.driver
-import uwtools.api.ecflow
 import uwtools.api.execute
 import uwtools.api.fs
 import uwtools.api.rocoto
@@ -42,6 +41,13 @@
 if TYPE_CHECKING:
     from iotaa import Node
 
+_ECFLOW_AVAILABLE = True
+try:
+    import uwtools.api.ecflow
+except ImportError:
+    _ECFLOW_AVAILABLE = False
+
+
 DRIVERS = [
     STR.cdeps,
     STR.chgres_cube,
@@ -111,8 +117,9 @@ def main() -> None:
             STR.fs: _dispatch_fs,
             STR.rocoto: _dispatch_rocoto,
             STR.template: _dispatch_template,
-            STR.ecflow: _dispatch_ecflow,
         }
+        if _ECFLOW_AVAILABLE:
+            tools[STR.ecflow] = _dispatch_ecflow
         drivers: dict[str, Callable[..., bool]] = {
             x: partial(_dispatch_to_driver, x) for x in DRIVERS
         }
@@ -1565,12 +1572,13 @@ def _parse_args(raw_args: list[str]) -> tuple[Args, Checks]:
     subparsers = _add_subparsers(parser, STR.mode, STR.mode.upper())
     tools = {
         STR.config: partial(_add_subparser_config, subparsers),
-        STR.ecflow: partial(_add_subparser_ecflow, subparsers),
         STR.execute: partial(_add_subparser_execute, subparsers),
         STR.fs: partial(_add_subparser_fs, subparsers),
         STR.rocoto: partial(_add_subparser_rocoto, subparsers),
         STR.template: partial(_add_subparser_template, subparsers),
     }
+    if _ECFLOW_AVAILABLE:
+        tools[STR.ecflow] = partial(_add_subparser_ecflow, subparsers)
     no_components: list[str] = []
     assets = {
         component: partial(_add_subparser_for_driver, component, subparsers)

src/uwtools/ecflow.py

@@ -16,21 +16,29 @@
 from time import sleep
 from typing import TYPE_CHECKING, cast
 
-from ecflow import (  # type: ignore[import-untyped]
-    Client,
-    Defs,
-    DState,
-    Family,
-    Late,
-    Node,
-    RepeatDate,
-    RepeatDateTime,
-    RepeatDay,
-    RepeatEnumerated,
-    RepeatInteger,
-    Suite,
-    Task,
-)
+try:
+    from ecflow import (  # type: ignore[import-untyped]
+        Client,
+        Defs,
+        DState,
+        Family,
+        Late,
+        Node,
+        RepeatDate,
+        RepeatDateTime,
+        RepeatDay,
+        RepeatEnumerated,
+        RepeatInteger,
+        Suite,
+        Task,
+    )
+except ImportError as e:
+    msg = (
+        "The ecFlow Python library could not be imported. To use ecFlow functionality, ensure "
+        "that the ecFlow executables are on PATH and the ecFlow Python libraries are on "
+        "PYTHONPATH. "
+    )
+    raise ImportError(msg) from e
 
 from uwtools.config.formats.yaml import YAMLConfig
 from uwtools.config.validator import validate_internal

src/uwtools/tests/test_cli.py

@@ -3,6 +3,7 @@
 from argparse import ArgumentParser as Parser
 from argparse import _SubParsersAction
 from datetime import timedelta
+from importlib import reload
 from pathlib import Path
 from textwrap import dedent
 from unittest.mock import Mock, patch
@@ -928,6 +929,29 @@ def test_cli__dispatch_to_driver_show_schema(capsys):
     assert capsys.readouterr().out == dedent(expected).lstrip()
 
 
+def test_cli__ecflow_importable():
+    reload(cli)
+    assert cli._ECFLOW_AVAILABLE is True
+
+
+def test_cli__ecflow_importable_fail():
+    with patch.dict(sys.modules, {"uwtools.api.ecflow": None}):
+        reload(cli)
+        assert cli._ECFLOW_AVAILABLE is False
+    reload(cli)
+
+
+def test_cli_main_ecflow_unavailable():
+    with (
+        patch.object(cli, "_ECFLOW_AVAILABLE", False),
+        patch.object(cli, "_dispatch_template", return_value=True),
+        patch.object(sys, "argv", ["uw", "template", "render"]),
+        raises(SystemExit) as e,
+    ):
+        cli.main()
+    assert e.value.code == 0
+
+
 @mark.parametrize("quiet", [False, True])
 @mark.parametrize("verbose", [False, True])
 def test_cli_main_fail_checks(capsys, quiet, verbose):

src/uwtools/tests/test_ecflow.py

@@ -7,6 +7,7 @@
 import socket
 import sys
 from copy import deepcopy
+from importlib import reload
 from io import StringIO
 from pathlib import Path
 from textwrap import dedent
@@ -1208,3 +1209,11 @@ def fake_run(cmd, **_kwargs):
     assert (ssl_dir / "server.crt").is_file()
     assert (ssl_dir / "dh2048.pem").is_file()
     assert logged("SSL certificate files written to %s" % ssl_dir)
+
+
+def test_ecflow_import_error():
+    with (
+        patch.dict(sys.modules, {"ecflow": None}),
+        raises(ImportError, match="ecFlow Python library could not be imported"),
+    ):
+        reload(ecflow)