Add config compose mode/action (#804)

maddenp-cu · web-flow · commit e6326c44425e · 2025-09-17T14:53:45.000-06:00
diff --git a/docs/index.rst b/docs/index.rst
@@ -37,6 +37,13 @@ When the Linux diff tool just doesn't work for comparing unordered namelists wit
 
 | :any:`CLI documentation with examples<cli_config_compare_examples>`
 
+Compose Action
+""""""""""""""
+
+To compose configs is to start with a base config and to update its values, structurally, from the contents of one or more other configs of the same type (YAML, Fortran namelist, etc.). Composition supports building up complex experiment configurations by, for example, combining default values appropriate to the overall application with values needed on a particular machine, and then with specific user requirements, each stored in their own config files. Such a hierarchical approach to configuration management provides flexibility and avoids repetition of common values across files.
+
+| :any:`CLI documentation with examples<cli_config_compose_examples>`
+
 Realize Action
 """"""""""""""
 
diff --git a/docs/sections/user_guide/cli/tools/config.rst b/docs/sections/user_guide/cli/tools/config.rst
@@ -87,6 +87,75 @@ The examples that follow use identical namelist files ``a.nml`` and ``b.nml`` wi
   .. literalinclude:: config/compare-format-mismatch.out
      :language: text
 
+.. _cli_config_compose_examples:
+
+``compose``
+-----------
+
+The ``compose`` action builds up a final config by repeatedly updating a base config with the contents of other configs of the same format.
+
+.. literalinclude:: config/compose-help.cmd
+   :language: text
+   :emphasize-lines: 1
+.. literalinclude:: config/compose-help.out
+   :language: text
+
+Examples
+^^^^^^^^
+
+* Consider three YAML configs:
+
+  .. literalinclude:: config/compose-base.yaml
+     :caption: compose-base.yaml
+     :language: yaml
+  .. literalinclude:: config/compose-update-1.yaml
+     :caption: compose-update-1.yaml
+     :language: yaml
+  .. literalinclude:: config/compose-update-2.yaml
+     :caption: compose-update-2.yaml
+     :language: yaml
+
+  Compose the three together, writing to ``stdout``:
+
+  .. literalinclude:: config/compose-basic.cmd
+     :language: text
+     :emphasize-lines: 1
+  .. literalinclude:: config/compose-basic.out
+     :language: yaml
+
+  Values provided by update configs override or augment values provided in the base config, while unaffected values survive to the final config. Priority of values increases from left to right.
+
+  Additionally:
+
+    * Sets of configs in the ``ini``, ``nml``, and ``sh`` formats can be similarly composed.
+    * The ``--input-format`` and ``--output-format`` options can be used to specify the format of the input and output configs, respectively, for cases when ``uwtools`` cannot deduce the format of configs from their filename extensions. When the formats are neither explicitly specified or deduced, ``yaml`` is assumed.
+    * The ``--output-file`` / ``-o`` option can be added to write the final config to a file instead of to ``stdout``.
+
+* The optional ``--realize`` switch can be used to render as many Jinja2 template expressions as possible in the final config, using the config itself as a source of values. For example:
+
+  .. literalinclude:: config/compose-template.yaml
+     :caption: compose-template.yaml
+     :language: yaml
+  .. literalinclude:: config/compose-values.yaml
+     :caption: compose-values.yaml
+     :language: yaml
+
+  Without the ``--realize`` switch:
+
+  .. literalinclude:: config/compose-realize-no.cmd
+     :language: text
+     :emphasize-lines: 1
+  .. literalinclude:: config/compose-realize-no.out
+     :language: yaml
+
+  And with ``--realize``:
+
+  .. literalinclude:: config/compose-realize-yes.cmd
+     :language: text
+     :emphasize-lines: 1
+  .. literalinclude:: config/compose-realize-yes.out
+     :language: yaml
+
 .. _cli_config_realize_examples:
 
 ``realize``
diff --git a/docs/sections/user_guide/cli/tools/config/compose-base.yaml b/docs/sections/user_guide/cli/tools/config/compose-base.yaml
@@ -0,0 +1,4 @@
+constants:
+  pi: 3.142
+color: blue
+flower: violet
diff --git a/docs/sections/user_guide/cli/tools/config/compose-basic.cmd b/docs/sections/user_guide/cli/tools/config/compose-basic.cmd
@@ -0,0 +1,2 @@
+uw config compose compose-base.yaml compose-update-1.yaml compose-update-2.yaml
+
diff --git a/docs/sections/user_guide/cli/tools/config/compose-basic.out b/docs/sections/user_guide/cli/tools/config/compose-basic.out
@@ -0,0 +1,5 @@
+constants:
+  pi: 3.142
+  e: 2.718
+color: blue
+flower: rose
diff --git a/docs/sections/user_guide/cli/tools/config/compose-help.cmd b/docs/sections/user_guide/cli/tools/config/compose-help.cmd
@@ -0,0 +1 @@
+uw config compose --help
diff --git a/docs/sections/user_guide/cli/tools/config/compose-help.out b/docs/sections/user_guide/cli/tools/config/compose-help.out
@@ -0,0 +1,28 @@
+usage: uw config compose [-h] [--version] [--realize] [--output-file PATH]
+                         [--input-format {ini,nml,sh,yaml}]
+                         [--output-format {ini,nml,sh,yaml}] [--quiet]
+                         [--verbose]
+                         CONFIG [CONFIG ...]
+
+Compose configs
+
+positional arguments:
+  CONFIG
+
+Optional arguments:
+  -h, --help
+      Show help and exit
+  --version
+      Show version info and exit
+  --realize
+      Render template expressions where possible
+  --output-file PATH, -o PATH
+      Path to output file (default: write to stdout)
+  --input-format {ini,nml,sh,yaml}
+      Input format (default: yaml)
+  --output-format {ini,nml,sh,yaml}
+      Output format (default: yaml)
+  --quiet, -q
+      Print no logging messages
+  --verbose, -v
+      Print all logging messages
diff --git a/docs/sections/user_guide/cli/tools/config/compose-realize-no.cmd b/docs/sections/user_guide/cli/tools/config/compose-realize-no.cmd
@@ -0,0 +1 @@
+uw config compose compose-template.yaml compose-values.yaml
diff --git a/docs/sections/user_guide/cli/tools/config/compose-realize-no.out b/docs/sections/user_guide/cli/tools/config/compose-realize-no.out
@@ -0,0 +1,3 @@
+radius: !float '{{ 2.0 * pi * r }}'
+pi: 3.142
+r: 1.0
diff --git a/docs/sections/user_guide/cli/tools/config/compose-realize-yes.cmd b/docs/sections/user_guide/cli/tools/config/compose-realize-yes.cmd
@@ -0,0 +1 @@
+uw config compose compose-template.yaml compose-values.yaml --realize
diff --git a/docs/sections/user_guide/cli/tools/config/compose-realize-yes.out b/docs/sections/user_guide/cli/tools/config/compose-realize-yes.out
@@ -0,0 +1,3 @@
+radius: 6.284
+pi: 3.142
+r: 1.0
diff --git a/docs/sections/user_guide/cli/tools/config/compose-template.yaml b/docs/sections/user_guide/cli/tools/config/compose-template.yaml
@@ -0,0 +1 @@
+radius: !float '{{ 2.0 * pi * r }}'
diff --git a/docs/sections/user_guide/cli/tools/config/compose-update-1.yaml b/docs/sections/user_guide/cli/tools/config/compose-update-1.yaml
@@ -0,0 +1,2 @@
+constants:
+  e: 2.718
diff --git a/docs/sections/user_guide/cli/tools/config/compose-update-2.yaml b/docs/sections/user_guide/cli/tools/config/compose-update-2.yaml
@@ -0,0 +1 @@
+flower: rose
diff --git a/docs/sections/user_guide/cli/tools/config/compose-values.yaml b/docs/sections/user_guide/cli/tools/config/compose-values.yaml
@@ -0,0 +1,2 @@
+pi: 3.142
+r: 1.0
diff --git a/docs/sections/user_guide/cli/tools/config/help.out b/docs/sections/user_guide/cli/tools/config/help.out
@@ -12,6 +12,8 @@ Positional arguments:
   ACTION
     compare
       Compare configs
+    compose
+      Compose configs
     realize
       Realize config
     validate
diff --git a/docs/sections/user_guide/cli/tools/config/realize-help.out b/docs/sections/user_guide/cli/tools/config/realize-help.out
@@ -15,17 +15,17 @@ Optional arguments:
   --version
       Show version info and exit
   --input-file PATH, -i PATH
-      Path to input file (defaults to stdin)
+      Path to input file (default: read from stdin)
   --input-format {ini,nml,sh,yaml}
-      Input format
+      Input format (default: yaml)
   --update-file PATH, -u PATH
-      Path to update file (defaults to stdin)
+      Path to update file (default: read from stdin)
   --update-format {ini,nml,sh,yaml}
       Update format
   --output-file PATH, -o PATH
-      Path to output file (defaults to stdout)
+      Path to output file (default: write to stdout)
   --output-format {ini,nml,sh,yaml}
-      Output format
+      Output format (default: yaml)
   --key-path KEY[.KEY...]
       Dot-separated path of keys to the block to be output
   --values-needed
diff --git a/docs/sections/user_guide/cli/tools/config/validate-help.out b/docs/sections/user_guide/cli/tools/config/validate-help.out
@@ -13,7 +13,7 @@ Optional arguments:
   --version
       Show version info and exit
   --input-file PATH, -i PATH
-      Path to input file (defaults to stdin)
+      Path to input file (default: read from stdin)
   --quiet, -q
       Print no logging messages
   --verbose, -v
diff --git a/docs/sections/user_guide/cli/tools/rocoto/realize-help.out b/docs/sections/user_guide/cli/tools/rocoto/realize-help.out
@@ -11,7 +11,7 @@ Optional arguments:
   --config-file PATH, -c PATH
       Path to UW YAML config file (default: read from stdin)
   --output-file PATH, -o PATH
-      Path to output file (defaults to stdout)
+      Path to output file (default: write to stdout)
   --quiet, -q
       Print no logging messages
   --verbose, -v
diff --git a/docs/sections/user_guide/cli/tools/rocoto/validate-help.out b/docs/sections/user_guide/cli/tools/rocoto/validate-help.out
@@ -9,7 +9,7 @@ Optional arguments:
   --version
       Show version info and exit
   --input-file PATH, -i PATH
-      Path to input file (defaults to stdin)
+      Path to input file (default: read from stdin)
   --quiet, -q
       Print no logging messages
   --verbose, -v
diff --git a/docs/sections/user_guide/cli/tools/template/render-help.out b/docs/sections/user_guide/cli/tools/template/render-help.out
@@ -13,9 +13,9 @@ Optional arguments:
   --version
       Show version info and exit
   --input-file PATH, -i PATH
-      Path to input file (defaults to stdin)
+      Path to input file (default: read from stdin)
   --output-file PATH, -o PATH
-      Path to output file (defaults to stdout)
+      Path to output file (default: write to stdout)
   --values-file PATH
       Path to file providing override or interpolation values
   --values-format {ini,nml,sh,yaml}
diff --git a/docs/sections/user_guide/cli/tools/template/translate-help.out b/docs/sections/user_guide/cli/tools/template/translate-help.out
@@ -10,9 +10,9 @@ Optional arguments:
   --version
       Show version info and exit
   --input-file PATH, -i PATH
-      Path to input file (defaults to stdin)
+      Path to input file (default: read from stdin)
   --output-file PATH, -o PATH
-      Path to output file (defaults to stdout)
+      Path to output file (default: write to stdout)
   --dry-run
       Only log info, making no changes
   --quiet, -q
diff --git a/docs/static/custom.css b/docs/static/custom.css
@@ -21,3 +21,15 @@ html.writer-html5 .rst-content table.docutils td>p {
 .wy-table-responsive table td, .wy-table-responsive table th {
   white-space: inherit;
 }
+
+/* Hide "Listing ..." text in captions */
+
+.rst-content .caption-number {
+  display: none;
+}
+
+/* Left align captions. */
+
+.rst-content .code-block-caption {
+  text-align: left;
+}
diff --git a/src/uwtools/api/config.py b/src/uwtools/api/config.py
@@ -14,8 +14,9 @@
 from uwtools.config.formats.nml import NMLConfig
 from uwtools.config.formats.sh import SHConfig
 from uwtools.config.formats.yaml import YAMLConfig
-from uwtools.config.tools import compare_configs as _compare
-from uwtools.config.tools import realize_config as _realize
+from uwtools.config.tools import compare as _compare
+from uwtools.config.tools import compose as _compose
+from uwtools.config.tools import realize as _realize
 from uwtools.config.validator import ConfigDataT, ConfigPathT
 from uwtools.config.validator import validate_check_config as _validate_check_config
 from uwtools.config.validator import validate_external as _validate_external
@@ -31,19 +32,30 @@
 
 
 def compare(
-    path1: Path | str,
-    path2: Path | str,
-    format1: str | None = None,
-    format2: str | None = None,
+    path1: Path | str, path2: Path | str, format1: str | None = None, format2: str | None = None
 ) -> bool:
     """
     NB: This docstring is dynamically replaced: See compare.__doc__ definition below.
     """
-    return _compare(
-        path1=Path(path1),
-        path2=Path(path2),
-        format1=format1,
-        format2=format2,
+    return _compare(path1=Path(path1), path2=Path(path2), format1=format1, format2=format2)
+
+
+def compose(
+    configs: list[str | Path],
+    realize: bool = False,
+    output_file: Path | str | None = None,
+    input_format: str | None = None,
+    output_format: str | None = None,
+) -> bool:
+    """
+    NB: This docstring is dynamically replaced: See compose.__doc__ definition below.
+    """
+    return _compose(
+        configs=list(map(Path, configs)),
+        realize=realize,
+        output_file=Path(output_file) if output_file else None,
+        input_format=input_format,
+        output_format=output_format,
     )
 
 
@@ -217,8 +229,25 @@ def validate(
 :param format1: Format of 1st config file (optional if file's extension is recognized).
 :param format2: Format of 2nd config file (optional if file's extension is recognized).
 :return: ``False`` if config files had differences, otherwise ``True``.
-""".format(extensions=", ".join(_FORMAT.extensions())).strip()
-
+""".format(extensions=", ".join([f"``{x}``" for x in _FORMAT.extensions()])).strip()
+
+compose.__doc__ = """
+Compose config files.
+
+Specify explicit input or output formats to override default treatment based on file extension.
+Recognized file extensions are: {extensions}.
+
+:param configs: Paths to configs to compose.
+:param realize: Render template expressions where possible.
+:param output_file: Output config destination (default: write to ``stdout``).
+:param input_format: Format of configs to compose (choices: {choices}, default: ``{default}``)
+:param output_format: Format of output config (choices: {choices}, default: ``{default}``)
+:return: ``True`` if no errors were encountered.
+""".format(
+    default=_FORMAT.yaml,
+    extensions=", ".join([f"``{x}``" for x in _FORMAT.extensions()]),
+    choices=", ".join([f"``{x}``" for x in (_FORMAT.ini, _FORMAT.nml, _FORMAT.sh, _FORMAT.yaml)]),
+).strip()
 
 realize.__doc__ = """
 Realize a config based on a base input config and an optional update config.
@@ -258,7 +287,7 @@ def validate(
 :param stdin_ok: OK to read from ``stdin``?
 :return: The ``dict`` representation of the realized config.
 :raises: ``UWConfigRealizeError`` if ``total`` is ``True`` and any Jinja2 syntax was not rendered.
-""".format(extensions=", ".join(_FORMAT.extensions())).strip()  # noqa: E501
+""".format(extensions=", ".join([f"``{x}``" for x in _FORMAT.extensions()])).strip()  # noqa: E501
 
 __all__ = [
     "Config",
@@ -268,6 +297,7 @@ def validate(
     "SHConfig",
     "YAMLConfig",
     "compare",
+    "compose",
     "get_fieldtable_config",
     "get_ini_config",
     "get_nml_config",
diff --git a/src/uwtools/cli.py b/src/uwtools/cli.py
diff --git a/src/uwtools/config/tools.py b/src/uwtools/config/tools.py
diff --git a/src/uwtools/strings.py b/src/uwtools/strings.py
diff --git a/src/uwtools/tests/api/test_config.py b/src/uwtools/tests/api/test_config.py
diff --git a/src/uwtools/tests/config/test_tools.py b/src/uwtools/tests/config/test_tools.py
diff --git a/src/uwtools/tests/test_cli.py b/src/uwtools/tests/test_cli.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+uw config compose compose-base.yaml compose-update-1.yaml compose-update-2.yaml`
	`2`	`+`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+uw config compose compose-template.yaml compose-values.yaml`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+radius: !float '{{ 2.0 * pi * r }}'`
	`2`	`+pi: 3.142`
	`3`	`+r: 1.0`