Update fs mode to use --key-path CLI switch / key_path API argument (#…

…670)

docs/environment.yml

@@ -6,4 +6,4 @@ dependencies:
   - python >=3.9,<3.13 # keep in sync with meta.yaml run req
   - sphinx_rtd_theme 3.0.*
   - sphinxcontrib-bibtex 2.6.*
-  - tree
+  - tree 2.2.*

docs/sections/user_guide/cli/drivers/cdeps/run-help.out

@@ -20,8 +20,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/chgres_cube/run-help.out

@@ -25,8 +25,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/esg_grid/run-help.out

@@ -19,8 +19,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/filter_topo/run-help.out

@@ -19,8 +19,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/fv3/run-help.out

@@ -23,8 +23,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/global_equiv_resol/run-help.out

@@ -19,8 +19,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/ioda/run-help.out

@@ -23,8 +23,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/jedi/run-help.out

@@ -23,8 +23,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/make_hgrid/run-help.out

@@ -19,8 +19,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/make_solo_mosaic/run-help.out

@@ -19,8 +19,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/mpas/run-help.out

@@ -23,8 +23,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/mpas_init/run-help.out

@@ -23,8 +23,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/orog/run-help.out

@@ -18,8 +18,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/orog_gsl/run-help.out

@@ -19,8 +19,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/sfc_climo_gen/run-help.out

@@ -19,8 +19,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/shave/run-help.out

@@ -18,8 +18,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/ungrib/run-help.out

@@ -23,8 +23,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/drivers/upp/run-help.out

@@ -25,8 +25,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --schema-file PATH
       Path to schema file to use for validation
   --quiet, -q

docs/sections/user_guide/cli/tools/execute/help.out

@@ -34,8 +34,7 @@ Optional arguments:
   --graph-file PATH
       Path to Graphviz DOT output [experimental]
   --key-path KEY[.KEY...]
-      Dot-separated path of keys leading through the config to the driver's
-      configuration block
+      Dot-separated path of keys to driver config block
   --quiet, -q
       Print no logging messages
   --verbose, -v

docs/sections/user_guide/cli/tools/fs/copy-exec-no-target-dir-err.cmd

@@ -1 +1 @@
-uw fs copy --config-file copy-config.yaml config files
+uw fs copy --config-file copy-config.yaml --key-path config.files

docs/sections/user_guide/cli/tools/fs/copy-exec-timedep.cmd

@@ -1,4 +1,4 @@
 rm -rf copy-dst-timedep
-uw fs copy --target-dir copy-dst-timedep --config-file copy-config-timedep.yaml --cycle 2024-05-29T12 --leadtime 6 config files
+uw fs copy --target-dir copy-dst-timedep --config-file copy-config-timedep.yaml --cycle 2024-05-29T12 --leadtime 6 --key-path config.files
 echo
 tree copy-dst-timedep

docs/sections/user_guide/cli/tools/fs/copy-exec.cmd

@@ -1,4 +1,4 @@
 rm -rf copy-dst
-uw fs copy --target-dir copy-dst --config-file copy-config.yaml config files
+uw fs copy --target-dir copy-dst --config-file copy-config.yaml --key-path config.files
 echo
 tree copy-dst

docs/sections/user_guide/cli/tools/fs/copy-help.out

@@ -1,7 +1,6 @@
 usage: uw fs copy [-h] [--version] [--config-file PATH] [--target-dir PATH]
-                  [--cycle CYCLE] [--leadtime LEADTIME] [--dry-run] [--quiet]
-                  [--verbose]
-                  [KEY ...]
+                  [--cycle CYCLE] [--leadtime LEADTIME] [--dry-run]
+                  [--key-path KEY[.KEY...]] [--quiet] [--verbose]
 
 Copy files
 
@@ -20,9 +19,9 @@ Optional arguments:
       The leadtime as hours[:minutes[:seconds]]
   --dry-run
       Only log info, making no changes
+  --key-path KEY[.KEY...]
+      Dot-separated path of keys to config block to use
   --quiet, -q
       Print no logging messages
   --verbose, -v
       Print all logging messages
-  KEY
-      YAML key leading to file dst/src block

docs/sections/user_guide/cli/tools/fs/link-exec-no-target-dir-err.cmd

@@ -1 +1 @@
-uw fs link --config-file link-config.yaml config files
+uw fs link --config-file link-config.yaml --key-path config.files

docs/sections/user_guide/cli/tools/fs/link-exec-timedep.cmd

@@ -1,4 +1,4 @@
 rm -rf link-dst-timedep
-uw fs link --target-dir link-dst-timedep --config-file link-config-timedep.yaml --cycle 2024-05-29T12 --leadtime 6 config files
+uw fs link --target-dir link-dst-timedep --config-file link-config-timedep.yaml --cycle 2024-05-29T12 --leadtime 6 --key-path config.files
 echo
 tree link-dst-timedep

docs/sections/user_guide/cli/tools/fs/link-exec.cmd

@@ -1,4 +1,4 @@
 rm -rf link-dst
-uw fs link --target-dir link-dst --config-file link-config.yaml config files
+uw fs link --target-dir link-dst --config-file link-config.yaml --key-path config.files
 echo
 tree link-dst

docs/sections/user_guide/cli/tools/fs/link-help.out

@@ -1,7 +1,6 @@
 usage: uw fs link [-h] [--version] [--config-file PATH] [--target-dir PATH]
-                  [--cycle CYCLE] [--leadtime LEADTIME] [--dry-run] [--quiet]
-                  [--verbose]
-                  [KEY ...]
+                  [--cycle CYCLE] [--leadtime LEADTIME] [--dry-run]
+                  [--key-path KEY[.KEY...]] [--quiet] [--verbose]
 
 Link files
 
@@ -20,9 +19,9 @@ Optional arguments:
       The leadtime as hours[:minutes[:seconds]]
   --dry-run
       Only log info, making no changes
+  --key-path KEY[.KEY...]
+      Dot-separated path of keys to config block to use
   --quiet, -q
       Print no logging messages
   --verbose, -v
       Print all logging messages
-  KEY
-      YAML key leading to file dst/src block

docs/sections/user_guide/cli/tools/fs/makedirs-exec-no-target-dir-err.cmd

@@ -1 +1 @@
-uw fs makedirs --config-file makedirs-config.yaml config
+uw fs makedirs --config-file makedirs-config.yaml --key-path config

docs/sections/user_guide/cli/tools/fs/makedirs-exec-timedep.cmd

@@ -1,4 +1,4 @@
 rm -rf makedirs-parent-timedep
-uw fs makedirs --target-dir makedirs-parent-timedep --config-file makedirs-config-timedep.yaml --cycle 2024-05-29T12 --leadtime 6 config
+uw fs makedirs --target-dir makedirs-parent-timedep --config-file makedirs-config-timedep.yaml --cycle 2024-05-29T12 --leadtime 6 --key-path config
 echo
 tree -F makedirs-parent-timedep

docs/sections/user_guide/cli/tools/fs/makedirs-exec.cmd

@@ -1,4 +1,4 @@
 rm -rf makedirs-parent
-uw fs makedirs --target-dir makedirs-parent --config-file makedirs-config.yaml config
+uw fs makedirs --target-dir makedirs-parent --config-file makedirs-config.yaml --key-path config
 echo
 tree -F makedirs-parent

docs/sections/user_guide/cli/tools/fs/makedirs-help.out

@@ -1,7 +1,7 @@
 usage: uw fs makedirs [-h] [--version] [--config-file PATH]
                       [--target-dir PATH] [--cycle CYCLE]
-                      [--leadtime LEADTIME] [--dry-run] [--quiet] [--verbose]
-                      [KEY ...]
+                      [--leadtime LEADTIME] [--dry-run]
+                      [--key-path KEY[.KEY...]] [--quiet] [--verbose]
 
 Make directories
 
@@ -20,9 +20,9 @@ Optional arguments:
       The leadtime as hours[:minutes[:seconds]]
   --dry-run
       Only log info, making no changes
+  --key-path KEY[.KEY...]
+      Dot-separated path of keys to config block to use
   --quiet, -q
       Print no logging messages
   --verbose, -v
       Print all logging messages
-  KEY
-      YAML key leading to file dst/src block

notebooks/config.ipynb

@@ -367,7 +367,7 @@
       "    :param update_format: Format of the update config (optional if file's extension is recognized).\n",
       "    :param output_file: Output config file (``None`` => write to ``stdout``).\n",
       "    :param output_format: Format of the output config (optional if file's extension is recognized).\n",
-      "    :param key_path: Path through keys to the desired output block.\n",
+      "    :param key_path: Path of keys to the desired output block.\n",
       "    :param values_needed: Report complete, missing, and template values.\n",
       "    :param total: Require rendering of all Jinja2 variables/expressions.\n",
       "    :param dry_run: Log output instead of writing to output.\n",