Add config compose mode/action

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 requrements, 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
 """"""""""""""
 

docs/sections/user_guide/cli/tools/config.rst

@@ -87,6 +87,50 @@ 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-1.cmd
+   :language: text
+   :emphasize-lines: 1
+.. literalinclude:: config/compose-1.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:
+
+  * Configs in the ``ini``, ``nml``, and ``sh`` formats can be similarly composed.
+  * The ``--input-config`` and ``--output-config`` 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. The the formats are neither explicitly provided or deduced, ``yaml`` is assumed.
+  * The ``--output-file`` / ``-o`` option can be added to direct the output to a file.
+
 .. _cli_config_realize_examples:
 
 ``realize``

docs/sections/user_guide/cli/tools/config/compose-1.cmd

@@ -0,0 +1,2 @@
+uw config compose compose-base.yaml compose-update-1.yaml compose-update-2.yaml
+

docs/sections/user_guide/cli/tools/config/compose-1.out

@@ -0,0 +1,5 @@
+constants:
+  pi: 3.142
+  e: 2.718
+color: blue
+flower: rose

docs/sections/user_guide/cli/tools/config/compose-base.yaml

@@ -0,0 +1,3 @@
+constants:
+  pi: 3.142
+color: blue

docs/sections/user_guide/cli/tools/config/compose-help.cmd

@@ -0,0 +1 @@
+uw config compose --help

docs/sections/user_guide/cli/tools/config/compose-help.out

@@ -0,0 +1,25 @@
+usage: uw config compose [-h] [--version] [--input-format {ini,nml,sh,yaml}]
+                         [--output-format {ini,nml,sh,yaml}]
+                         [--output-file PATH] [--quiet] [--verbose]
+                         CONFIG [CONFIG ...]
+
+Compose configs
+
+positional arguments:
+  CONFIG
+
+Optional arguments:
+  -h, --help
+      Show help and exit
+  --version
+      Show version info and exit
+  --input-format {ini,nml,sh,yaml}
+      Input format (default: yaml)
+  --output-format {ini,nml,sh,yaml}
+      Output format (default: yaml)
+  --output-file PATH, -o PATH
+      Path to output file (default: write to stdout)
+  --quiet, -q
+      Print no logging messages
+  --verbose, -v
+      Print all logging messages

docs/sections/user_guide/cli/tools/config/compose-update-1.yaml

@@ -0,0 +1,2 @@
+constants:
+  e: 2.718

docs/sections/user_guide/cli/tools/config/compose-update-2.yaml

@@ -0,0 +1 @@
+flower: rose

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

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

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

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

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

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}

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

docs/static/custom.css

@@ -21,3 +21,13 @@ html.writer-html5 .rst-content table.docutils td>p {
 .wy-table-responsive table td, .wy-table-responsive table th {
   white-space: inherit;
 }
+
+/* Left align captions. */
+
+.rst-content .caption-number {
+  display: none;
+}
+
+.rst-content .code-block-caption {
+  text-align: left;
+}

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,28 @@
 
 
 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],
+    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)),
+        output_file=Path(output_file) if output_file else None,
+        input_format=input_format,
+        output_format=output_format,
     )
 
 
@@ -217,8 +227,24 @@ 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 baseed on file extension.
+Recognized file extensions are: {extensions}.
 
+:param configs: Paths to configs to compose.
+: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 +284,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 +294,7 @@ def validate(
     "SHConfig",
     "YAMLConfig",
     "compare",
+    "compose",
     "get_fieldtable_config",
     "get_ini_config",
     "get_nml_config",