uwtools.api.driver

API access to the uwtools driver base classes.

class uwtools.api.driver.Assets(cycle=None, leadtime=None, config=None, dry_run=False, key_path=None, schema_file=None, controller=None)

A driver.

Parameters:

• cycle (datetime | None) – The cycle.

• leadtime (timedelta | None) – The leadtime.

• config (dict | str | YAMLConfig | Path | None) – Path to config file (read stdin if missing or None).

• dry_run (bool) – Run in dry-run mode?

• key_path (list[str] | None) – Keys leading through the config to the driver’s configuration block.

• schema_file (Path | None) – Path to schema file to use to validate an external driver.

• controller (str | None) – Name of block in config controlling run-time values.

property config: dict

A copy of the driver-specific config.

property config_full: dict

A copy of the original input config, dereferenced.

abstract property driver_name: str

Returns the name of this driver.

property rundir: Path

The path to the component’s run directory.

taskname(suffix)

Returns a common tag for graph-task log messages.

Parameters:

suffix (str) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.AssetsCycleBased(cycle, config=None, dry_run=False, key_path=None, schema_file=None, controller=None)

A driver.

Parameters:

• cycle (datetime) – The cycle.

• config (dict | str | YAMLConfig | Path | None) – Path to config file (read stdin if missing or None).

• dry_run (bool) – Run in dry-run mode?

• key_path (list[str] | None) – Keys leading through the config to the driver’s configuration block.

• schema_file (Path | None) – Path to schema file to use to validate an external driver.

• controller (str | None) – Name of block in config controlling run-time values.

property config: dict

A copy of the driver-specific config.

property config_full: dict

A copy of the original input config, dereferenced.

property cycle

The cycle.

abstract property driver_name: str

Returns the name of this driver.

property rundir: Path

The path to the component’s run directory.

taskname(suffix)

Returns a common tag for graph-task log messages.

Parameters:

suffix (str) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.AssetsCycleLeadtimeBased(cycle, leadtime, config=None, dry_run=False, key_path=None, schema_file=None, controller=None)

A driver.

Parameters:

• cycle (datetime) – The cycle.

• leadtime (timedelta) – The leadtime.

• config (dict | str | YAMLConfig | Path | None) – Path to config file (read stdin if missing or None).

• dry_run (bool) – Run in dry-run mode?

• key_path (list[str] | None) – Keys leading through the config to the driver’s configuration block.

• schema_file (Path | None) – Path to schema file to use to validate an external driver.

• controller (str | None) – Name of block in config controlling run-time values.

property config: dict

A copy of the driver-specific config.

property config_full: dict

A copy of the original input config, dereferenced.

property cycle

The cycle.

abstract property driver_name: str

Returns the name of this driver.

property leadtime

The leadtime.

property rundir: Path

The path to the component’s run directory.

taskname(suffix)

Returns a common tag for graph-task log messages.

Parameters:

suffix (str) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.AssetsTimeInvariant(config=None, dry_run=False, key_path=None, schema_file=None, controller=None)

A driver.

Parameters:

• config (dict | str | YAMLConfig | Path | None) – Path to config file (read stdin if missing or None).

• dry_run (bool) – Run in dry-run mode?

• key_path (list[str] | None) – Keys leading through the config to the driver’s configuration block.

• schema_file (Path | None) – Path to schema file to use to validate an external driver.

• controller (str | None) – Name of block in config controlling run-time values.

property config: dict

A copy of the driver-specific config.

property config_full: dict

A copy of the original input config, dereferenced.

abstract property driver_name: str

Returns the name of this driver.

property rundir: Path

The path to the component’s run directory.

taskname(suffix)

Returns a common tag for graph-task log messages.

Parameters:

suffix (str) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.Driver(cycle=None, leadtime=None, config=None, dry_run=False, key_path=None, batch=False, schema_file=None, controller=None)

A driver.

Parameters:

• cycle (datetime | None) – The cycle.

• leadtime (timedelta | None) – The leadtime.

• config (dict | str | YAMLConfig | Path | None) – Path to config file (read stdin if missing or None).

• dry_run (bool) – Run in dry-run mode?

• key_path (list[str] | None) – Keys leading through the config to the driver’s configuration block.

• batch (bool) – Run component via the batch system?

• schema_file (Path | None) – Path to schema file to use to validate an external driver.

• controller (str | None) – Name of block in config controlling run-time values.

property config: dict

A copy of the driver-specific config.

property config_full: dict

A copy of the original input config, dereferenced.

abstract property driver_name: str

Returns the name of this driver.

provisioned_rundir()

Run directory provisioned with all required content.

run()

A run.

property rundir: Path

The path to the component’s run directory.

runscript()

The runscript.

taskname(suffix)

Returns a common tag for graph-task log messages.

Parameters:

suffix (str) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.DriverCycleBased(cycle, config=None, dry_run=False, key_path=None, batch=False, schema_file=None, controller=None)

A driver.

Parameters:

• cycle (datetime) – The cycle.

• config (dict | str | YAMLConfig | Path | None) – Path to config file (read stdin if missing or None).

• dry_run (bool) – Run in dry-run mode?

• key_path (list[str] | None) – Keys leading through the config to the driver’s configuration block.

• batch (bool) – Run component via the batch system?

• schema_file (Path | None) – Path to schema file to use to validate an external driver.

• controller (str | None) – Name of block in config controlling run-time values.

property config: dict

A copy of the driver-specific config.

property config_full: dict

A copy of the original input config, dereferenced.

property cycle

The cycle.

abstract property driver_name: str

Returns the name of this driver.

abstract provisioned_rundir()

Run directory provisioned with all required content.

run()

A run.

property rundir: Path

The path to the component’s run directory.

runscript()

The runscript.

taskname(suffix)

Returns a common tag for graph-task log messages.

Parameters:

suffix (str) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.DriverCycleLeadtimeBased(cycle, leadtime, config=None, dry_run=False, key_path=None, batch=False, schema_file=None, controller=None)

A driver.

Parameters:

• cycle (datetime) – The cycle.

• leadtime (timedelta) – The leadtime.

• config (dict | str | YAMLConfig | Path | None) – Path to config file (read stdin if missing or None).

• dry_run (bool) – Run in dry-run mode?

• key_path (list[str] | None) – Keys leading through the config to the driver’s configuration block.

• batch (bool) – Run component via the batch system?

• schema_file (Path | None) – Path to schema file to use to validate an external driver.

• controller (str | None) – Name of block in config controlling run-time values.

property config: dict

A copy of the driver-specific config.

property config_full: dict

A copy of the original input config, dereferenced.

property cycle

The cycle.

abstract property driver_name: str

Returns the name of this driver.

property leadtime

The leadtime.

abstract provisioned_rundir()

Run directory provisioned with all required content.

run()

A run.

property rundir: Path

The path to the component’s run directory.

runscript()

The runscript.

taskname(suffix)

Returns a common tag for graph-task log messages.

Parameters:

suffix (str) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.DriverTimeInvariant(config=None, dry_run=False, key_path=None, batch=False, schema_file=None, controller=None)

A driver.

Parameters:

• config (dict | str | YAMLConfig | Path | None) – Path to config file (read stdin if missing or None).

• dry_run (bool) – Run in dry-run mode?

• key_path (list[str] | None) – Keys leading through the config to the driver’s configuration block.

• batch (bool) – Run component via the batch system?

• schema_file (Path | None) – Path to schema file to use to validate an external driver.

• controller (str | None) – Name of block in config controlling run-time values.

property config: dict

A copy of the driver-specific config.

property config_full: dict

A copy of the original input config, dereferenced.

abstract property driver_name: str

Returns the name of this driver.

abstract provisioned_rundir()

Run directory provisioned with all required content.

run()

A run.

property rundir: Path

The path to the component’s run directory.

runscript()

The runscript.

taskname(suffix)

Returns a common tag for graph-task log messages.

Parameters:

suffix (str) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

uwtools.api.driver.execute(module, classname, task, schema_file=None, config=None, cycle=None, leadtime=None, batch=False, dry_run=False, graph_file=None, key_path=None, stdin_ok=False)

Execute a task.

If batch is specified, a runscript will be written and submitted to the batch system. Otherwise, the executable will be run directly on the current system.

Parameters:

• module (Path | str) – Path to driver module or name of module on sys.path.

• classname (str) – Name of driver class to instantiate.

• task (str) – Name of driver task to execute.

• schema_file (str | None) – Path to schema file.

• config (str | Path | None) – Path to config file (read stdin if missing or None).

• cycle (datetime | None) – The cycle.

• leadtime (timedelta | None) – The leadtime.

• batch (bool | None) – Submit run to the batch system?

• dry_run (bool | None) – Do not run the executable, just report what would have been done.

• graph_file (str | Path | None) – Write Graphviz DOT output here.

• key_path (list[str] | None) – Path of keys to subsection of config file.

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

Returns:

True if task completes without raising an exception.

Return type:

bool

uwtools.api.driver.graph()

Returns Graphviz DOT code for the most recently executed task.

Return type:

str

uwtools.api.driver.tasks(module, classname)

Returns a mapping from task names to their one-line descriptions.

Parameters:

• module (Path | str) – Name of driver module.

• classname (str) – Name of driver class to instantiate.

Return type:

dict[str, str]