uwtools.api.fs

API access to uwtools file and directory management tools.

class uwtools.api.fs.Copier(config=None, target_dir=None, cycle=None, leadtime=None, key_path=None)

Stage files by copying.

Parameters:

• config (dict | str | Path | None) – YAML-file path, or dict (read stdin if missing or None).

• target_dir (str | Path | None) – Path to target directory.

• cycle (dt.datetime | None) – A datetime object to make available for use in the config.

• leadtime (dt.timedelta | None) – A timedelta object to make available for use in the config.

• key_path (list[YAMLKey] | None) – Path of keys to config block to use.

Raises:

UWConfigError if config fails validation.

go(name='')

Copy files.

Parameters:

name (str) – A string identifier to disambiguate the task from others like it.

class uwtools.api.fs.Linker(config=None, target_dir=None, cycle=None, hardlink=False, leadtime=None, key_path=None, fallback=None)

Stage files by linking.

Parameters:

• config (dict | str | Path | None) – YAML-file path, or dict (read stdin if missing or None).

• target_dir (str | Path | None) – Path to target directory.

• cycle (dt.datetime | None) – A datetime object to make available for use in the config.

• hardlink (bool | None) – Create hardlinks instead of symlinks?

• leadtime (dt.timedelta | None) – A timedelta object to make available for use in the config.

• key_path (list[YAMLKey] | None) – Path of keys to config block to use.

• fallback (str | None) – Choice of copy or symlink if hardlink fails when hardlink=True?

Raises:

UWConfigError if config fails validation.

go(name='')

Create links to filesystem items.

When hardlink is False (the default), links may target files, hardlinks, symlinks, and directories; when True, links may not be made across filesystems, or to directories. When fallback is set, a copy or symlink will be created, if possible, if a hardlink cannot be created.

Parameters:

name (str) – A string identifier to disambiguate the task from others like it.

class uwtools.api.fs.MakeDirs(config=None, target_dir=None, cycle=None, leadtime=None, key_path=None)

Make directories.

Parameters:

• config (dict | str | Path | None) – YAML-file path, or dict (read stdin if missing or None).

• target_dir (str | Path | None) – Path to target directory.

• cycle (dt.datetime | None) – A datetime object to make available for use in the config.

• leadtime (dt.timedelta | None) – A timedelta object to make available for use in the config.

• key_path (list[YAMLKey] | None) – Path of keys to config block to use.

Raises:

UWConfigError if config fails validation.

go()

Make directories.

uwtools.api.fs.copy(config=None, target_dir=None, cycle=None, leadtime=None, key_path=None, dry_run=False, threads=1, stdin_ok=False)

Copy files.

Parameters:

• config (Path | dict | str | None) – YAML-file path, or dict (read stdin if missing or None).

• target_dir (Path | str | None) – Path to target directory.

• cycle (dt.datetime | None) – A datetime object to make available for use in the config.

• leadtime (dt.timedelta | None) – A timedelta object to make available for use in the config.

• key_path (list[YAMLKey] | None) – Path of keys to config block to use.

• dry_run (bool) – Do not copy files.

• threads (int) – Number of concurrent threads to use.

• stdin_ok (bool) – OK to read from stdin?

Returns:

A report on files copied / not copied.

Return type:

dict[str, list[str]]

uwtools.api.fs.link(config=None, target_dir=None, cycle=None, hardlink=False, leadtime=None, key_path=None, dry_run=False, threads=1, stdin_ok=False, fallback=None)

Create links to filesystem items.

When hardlink is False (the default), links may target files, hardlinks, symlinks, and directories; when True, links may not be made across filesystems, or to directories. Alternative if hardlink fails (choices: copy, symlink).

Parameters:

• config (Path | dict | str | None) – YAML-file path, or dict (read stdin if missing or None).

• target_dir (Path | str | None) – Path to target directory.

• cycle (dt.datetime | None) – A datetime object to make available for use in the config.

• hardlink (bool | None) – Create hardlinks instead of symlinks?

• leadtime (dt.timedelta | None) – A timedelta object to make available for use in the config.

• key_path (list[YAMLKey] | None) – Path of keys to config block to use.

• dry_run (bool) – Do not link files.

• threads (int) – Number of concurrent threads to use.

• stdin_ok (bool) – OK to read from stdin?

• fallback (str | None) – Alternative if hardlink fails (choices: copy, symlink).

Returns:

A report on files linked / not linked.

Return type:

dict[str, list[str]]

uwtools.api.fs.makedirs(config=None, target_dir=None, cycle=None, leadtime=None, key_path=None, dry_run=False, threads=1, stdin_ok=False)

Make directories.

Parameters:

• config (Path | dict | str | None) – YAML-file path, or dict (read stdin if missing or None).

• target_dir (Path | str | None) – Path to target directory.

• cycle (dt.datetime | None) – A datetime object to make available for use in the config.

• leadtime (dt.timedelta | None) – A timedelta object to make available for use in the config.

• key_path (list[YAMLKey] | None) – Path of keys to config block to use.

• dry_run (bool) – Do not create directories.

• threads (int) – Number of concurrent threads to use.

• stdin_ok (bool) – OK to read from stdin?

Returns:

A report on directories created / not created.

Return type:

dict[str, list[str]]