UW-657 fs makedirs (#572)

docs/index.rst

@@ -71,22 +71,23 @@ This tool helps transform legacy configuration files templated with the atparse
 
 | :any:`CLI documentation with examples<cli_template_translate_examples>`
 
-File Provisioning
-^^^^^^^^^^^^^^^^^
+File/Directory Provisioning
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This tool helps users define the source and destination of files to be copied or linked, in the same UW YAML language used by UW drivers.
+| **CLI**: ``uw fs -h``
+| **API**: ``import uwtools.api.fs``
 
-| :any:`CLI documentation with examples<cli_file_copy_examples>`
 
+This tool helps users define the source and destination of files to be copied or linked, or directories to be created, in the same UW YAML language used by UW drivers.
 
-There is a video demonstration of the use of the ``uw file`` tool available via YouTube.
+| :any:`CLI documentation with examples<cli_fs_mode>`
+
+There is a video demonstration of the use of the ``uw fs`` tool (formerly ``uw file``) available via YouTube.
 
 .. raw:: html
 
    <iframe width="560" height="315" src="https://www.youtube.com/embed/b2HXOlt-Ulw?si=rLWatBFu4mvNR65S" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-|
-
 Rocoto Configurability
 ^^^^^^^^^^^^^^^^^^^^^^
 

docs/sections/user_guide/api/fs.rst

@@ -0,0 +1,5 @@
+``uwtools.api.fs``
+==================
+
+.. automodule:: uwtools.api.fs
+   :members:

docs/sections/user_guide/api/index.rst

@@ -8,8 +8,8 @@ API
    driver
    esg_grid
    execute
-   file
    filter_topo
+   fs
    fv3
    global_equiv_resol
    ioda

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

@@ -0,0 +1,135 @@
+``fs``
+======
+
+.. _cli_fs_mode:
+
+The ``uw`` mode for handling filesystem items (files and directories).
+
+.. literalinclude:: fs/help.cmd
+   :emphasize-lines: 1
+.. literalinclude:: fs/help.out
+   :language: text
+
+``copy``
+--------
+
+The ``copy`` action stages files in a target directory by copying files. Any ``KEY`` positional arguments are used to navigate, in the order given, from the top of the config to the :ref:`file block <files_yaml>`.
+
+.. literalinclude:: fs/copy-help.cmd
+   :emphasize-lines: 1
+.. literalinclude:: fs/copy-help.out
+   :language: text
+
+Examples
+^^^^^^^^
+
+Given ``copy-config.yaml`` containing
+
+.. literalinclude:: fs/copy-config.yaml
+   :language: yaml
+.. literalinclude:: fs/copy-exec.cmd
+   :emphasize-lines: 2
+.. literalinclude:: fs/copy-exec.out
+   :language: text
+
+Here, ``foo`` and ``bar`` are copies of their respective source files.
+
+The ``--cycle`` and ``--leadtime`` options can be used to make Python ``datetime`` and ``timedelta`` objects, respectively, available for use in Jinja2 expression in the config. For example:
+
+.. literalinclude:: fs/copy-config-timedep.yaml
+   :language: yaml
+.. literalinclude:: fs/copy-exec-timedep.cmd
+   :emphasize-lines: 2
+.. literalinclude:: fs/copy-exec-timedep.out
+   :language: text
+
+The ``--target-dir`` option need not be specified when all destination paths are absolute, and will never be applied to absolute destination paths. If any destination paths are relative, however, it is an error not to provide a target directory:
+
+.. literalinclude:: fs/copy-config.yaml
+   :language: yaml
+.. literalinclude:: fs/copy-exec-no-target-dir-err.cmd
+   :emphasize-lines: 1
+.. literalinclude:: fs/copy-exec-no-target-dir-err.out
+   :language: text
+
+``link``
+--------
+
+The ``link`` action stages files in a target directory by linking files, directories, or other symbolic links. Any ``KEY`` positional arguments are used to navigate, in the order given, from the top of the config to the :ref:`file block <files_yaml>`.
+
+.. literalinclude:: fs/link-help.cmd
+   :emphasize-lines: 1
+.. literalinclude:: fs/link-help.out
+   :language: text
+
+Examples
+^^^^^^^^
+
+Given ``link-config.yaml`` containing
+
+.. literalinclude:: fs/link-config.yaml
+   :language: yaml
+.. literalinclude:: fs/link-exec.cmd
+   :emphasize-lines: 2
+.. literalinclude:: fs/link-exec.out
+   :language: text
+
+Here, ``foo`` and ``bar`` are symbolic links.
+
+The ``--cycle`` and ``--leadtime`` options can be used to make Python ``datetime`` and ``timedelta`` objects, respectively, available for use in Jinja2 expression in the config. For example:
+
+.. literalinclude:: fs/link-config-timedep.yaml
+   :language: yaml
+.. literalinclude:: fs/link-exec-timedep.cmd
+   :emphasize-lines: 2
+.. literalinclude:: fs/link-exec-timedep.out
+   :language: text
+
+The ``--target-dir`` option need not be specified when all linkname paths are absolute, and will never be applied to absolute linkname paths. If any linkname paths are relative, however, it is an error not to provide a target directory:
+
+.. literalinclude:: fs/link-config.yaml
+   :language: yaml
+.. literalinclude:: fs/link-exec-no-target-dir-err.cmd
+   :emphasize-lines: 1
+.. literalinclude:: fs/link-exec-no-target-dir-err.out
+   :language: text
+
+``makedirs``
+------------
+
+The ``makedirs`` action creates directories. Any ``KEY`` positional arguments are used to navigate, in the order given, from the top of the config to the :ref:`makedirs block <makedirs_yaml>`.
+
+.. literalinclude:: fs/makedirs-help.cmd
+   :emphasize-lines: 1
+.. literalinclude:: fs/makedirs-help.out
+   :language: text
+
+Examples
+^^^^^^^^
+
+Given ``makedirs-config.yaml`` containing
+
+.. literalinclude:: fs/makedirs-config.yaml
+   :language: yaml
+.. literalinclude:: fs/makedirs-exec.cmd
+   :emphasize-lines: 2
+.. literalinclude:: fs/makedirs-exec.out
+   :language: text
+
+The ``--cycle`` and ``--leadtime`` options can be used to make Python ``datetime`` and ``timedelta`` objects, respectively, available for use in Jinja2 expression in the config. For example:
+
+.. literalinclude:: fs/makedirs-config-timedep.yaml
+   :language: yaml
+.. literalinclude:: fs/makedirs-exec-timedep.cmd
+   :emphasize-lines: 2
+.. literalinclude:: fs/makedirs-exec-timedep.out
+   :language: text
+
+The ``--target-dir`` option need not be specified when all directory paths are absolute, and will never be applied to absolute paths. If any paths are relative, however, it is an error not to provide a target directory:
+
+.. literalinclude:: fs/makedirs-config.yaml
+   :language: yaml
+.. literalinclude:: fs/makedirs-exec-no-target-dir-err.cmd
+   :emphasize-lines: 1
+.. literalinclude:: fs/makedirs-exec-no-target-dir-err.out
+   :language: text

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

@@ -0,0 +1 @@
+uw fs copy --config-file copy-config.yaml config files

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

@@ -0,0 +1,3 @@
+[2024-08-14T15:19:59]     INFO Validating config against internal schema: files-to-stage
+[2024-08-14T15:19:59]     INFO 0 UW schema-validation errors found
+[2024-08-14T15:19:59]    ERROR Relative path 'foo' requires the target directory to be specified

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

@@ -0,0 +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
+echo
+tree copy-dst-timedep

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

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

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

@@ -0,0 +1 @@
+uw fs copy --help

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

@@ -1,7 +1,7 @@
-usage: uw file copy [-h] [--version] [--config-file PATH] [--target-dir PATH]
-                    [--cycle CYCLE] [--leadtime LEADTIME] [--dry-run]
-                    [--quiet] [--verbose]
-                    [KEY ...]
+usage: uw fs copy [-h] [--version] [--config-file PATH] [--target-dir PATH]
+                  [--cycle CYCLE] [--leadtime LEADTIME] [--dry-run] [--quiet]
+                  [--verbose]
+                  [KEY ...]
 
 Copy files
 

docs/sections/user_guide/cli/tools/fs/help.cmd

@@ -0,0 +1 @@
+uw fs --help

docs/sections/user_guide/cli/tools/file/help.out → docs/sections/user_guide/cli/tools/fs/help.out

@@ -1,6 +1,6 @@
-usage: uw file [-h] [--version] ACTION ...
+usage: uw fs [-h] [--version] ACTION ...
 
-Handle files
+Handle filesystem items (files and directories)
 
 Optional arguments:
   -h, --help
@@ -14,3 +14,5 @@ Positional arguments:
       Copy files
     link
       Link files
+    makedirs
+      Make directories

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

@@ -0,0 +1 @@
+uw fs link --config-file link-config.yaml config files

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

@@ -0,0 +1,3 @@
+[2024-08-14T15:19:57]     INFO Validating config against internal schema: files-to-stage
+[2024-08-14T15:19:57]     INFO 0 UW schema-validation errors found
+[2024-08-14T15:19:57]    ERROR Relative path 'foo' requires the target directory to be specified

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

@@ -0,0 +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
+echo
+tree link-dst-timedep

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

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

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

@@ -0,0 +1 @@
+uw fs link --help

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

@@ -1,7 +1,7 @@
-usage: uw file link [-h] [--version] [--config-file PATH] [--target-dir PATH]
-                    [--cycle CYCLE] [--leadtime LEADTIME] [--dry-run]
-                    [--quiet] [--verbose]
-                    [KEY ...]
+usage: uw fs link [-h] [--version] [--config-file PATH] [--target-dir PATH]
+                  [--cycle CYCLE] [--leadtime LEADTIME] [--dry-run] [--quiet]
+                  [--verbose]
+                  [KEY ...]
 
 Link files