uwtools.api.driver

API access to the uwtools driver base classes.

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

A driver.

Parameters:

• cycle (datetime | None) – The cycle.

• leadtime (timedelta | None) – The leadtime.

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

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

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

• controller (list[YAMLKey] | None) – Key(s) leading to 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.

static create_user_updated_config(config_class, config_values, path, schema=None)

Create a config from a base file, user-provided values, or a combination of the two.

Parameters:

• config_class (type[Config]) – The Config subclass matching the config type.

• config_values (dict) – The configuration object to update base values with.

• path (Path) – Path to dump file to.

• schema (dict | None) – Schema to validate final config against.

Return type:

None

abstract classmethod driver_name()

The name of this driver.

Return type:

str

namelist_schema(config_keys=None, schema_keys=None)

Return the (sub)schema for validating the driver’s namelist content.

Parameters:

• config_keys (list[YAMLKey] | None) – Keys leading to the namelist block in the driver config.

• schema_keys (list[str] | None) – Keys leading to the namelist-validating (sub)schema.

Return type:

dict

property rundir: Path

The path to the component’s run directory.

classmethod schema()

Return the driver’s internal schema.

Return type:

dict

taskname(suffix=None)

Return a common tag for task-related log messages.

Parameters:

suffix (str | None) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.AssetsCycleBased(cycle, config=None, 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).

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

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

• controller (list[YAMLKey] | None) – Key(s) leading to 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.

static create_user_updated_config(config_class, config_values, path, schema=None)

Create a config from a base file, user-provided values, or a combination of the two.

Parameters:

• config_class (type[Config]) – The Config subclass matching the config type.

• config_values (dict) – The configuration object to update base values with.

• path (Path) – Path to dump file to.

• schema (dict | None) – Schema to validate final config against.

Return type:

None

property cycle

The cycle.

abstract classmethod driver_name()

The name of this driver.

Return type:

str

namelist_schema(config_keys=None, schema_keys=None)

Return the (sub)schema for validating the driver’s namelist content.

Parameters:

• config_keys (list[YAMLKey] | None) – Keys leading to the namelist block in the driver config.

• schema_keys (list[str] | None) – Keys leading to the namelist-validating (sub)schema.

Return type:

dict

property rundir: Path

The path to the component’s run directory.

classmethod schema()

Return the driver’s internal schema.

Return type:

dict

taskname(suffix=None)

Return a common tag for task-related log messages.

Parameters:

suffix (str | None) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.AssetsCycleLeadtimeBased(cycle, leadtime, config=None, 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).

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

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

• controller (list[YAMLKey] | None) – Key(s) leading to 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.

static create_user_updated_config(config_class, config_values, path, schema=None)

Create a config from a base file, user-provided values, or a combination of the two.

Parameters:

• config_class (type[Config]) – The Config subclass matching the config type.

• config_values (dict) – The configuration object to update base values with.

• path (Path) – Path to dump file to.

• schema (dict | None) – Schema to validate final config against.

Return type:

None

property cycle

The cycle.

abstract classmethod driver_name()

The name of this driver.

Return type:

str

property leadtime

The leadtime.

namelist_schema(config_keys=None, schema_keys=None)

Return the (sub)schema for validating the driver’s namelist content.

Parameters:

• config_keys (list[YAMLKey] | None) – Keys leading to the namelist block in the driver config.

• schema_keys (list[str] | None) – Keys leading to the namelist-validating (sub)schema.

Return type:

dict

property rundir: Path

The path to the component’s run directory.

classmethod schema()

Return the driver’s internal schema.

Return type:

dict

taskname(suffix=None)

Return a common tag for task-related log messages.

Parameters:

suffix (str | None) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.AssetsTimeInvariant(config=None, 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).

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

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

• controller (list[YAMLKey] | None) – Key(s) leading to 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.

static create_user_updated_config(config_class, config_values, path, schema=None)

Create a config from a base file, user-provided values, or a combination of the two.

Parameters:

• config_class (type[Config]) – The Config subclass matching the config type.

• config_values (dict) – The configuration object to update base values with.

• path (Path) – Path to dump file to.

• schema (dict | None) – Schema to validate final config against.

Return type:

None

abstract classmethod driver_name()

The name of this driver.

Return type:

str

namelist_schema(config_keys=None, schema_keys=None)

Return the (sub)schema for validating the driver’s namelist content.

Parameters:

• config_keys (list[YAMLKey] | None) – Keys leading to the namelist block in the driver config.

• schema_keys (list[str] | None) – Keys leading to the namelist-validating (sub)schema.

Return type:

dict

property rundir: Path

The path to the component’s run directory.

classmethod schema()

Return the driver’s internal schema.

Return type:

dict

taskname(suffix=None)

Return a common tag for task-related log messages.

Parameters:

suffix (str | None) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.Driver(cycle=None, leadtime=None, config=None, 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).

• key_path (list[YAMLKey] | None) – Keys of keys to driver config 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 (list[YAMLKey] | None) – Key(s) leading to 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.

static create_user_updated_config(config_class, config_values, path, schema=None)

Create a config from a base file, user-provided values, or a combination of the two.

Parameters:

• config_class (type[Config]) – The Config subclass matching the config type.

• config_values (dict) – The configuration object to update base values with.

• path (Path) – Path to dump file to.

• schema (dict | None) – Schema to validate final config against.

Return type:

None

abstract classmethod driver_name()

The name of this driver.

Return type:

str

namelist_schema(config_keys=None, schema_keys=None)

Return the (sub)schema for validating the driver’s namelist content.

Parameters:

• config_keys (list[YAMLKey] | None) – Keys leading to the namelist block in the driver config.

• schema_keys (list[str] | None) – Keys leading to the namelist-validating (sub)schema.

Return type:

dict

property output: dict[str, Path] | dict[str, list[Path]]

Returns a description of the file(s) created when this component runs.

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.

classmethod schema()

Return the driver’s internal schema.

Return type:

dict

show_output()

Show the output to be created by this component.

taskname(suffix=None)

Return a common tag for task-related log messages.

Parameters:

suffix (str | None) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.DriverCycleBased(cycle, config=None, 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).

• key_path (list[YAMLKey] | None) – Keys of keys to driver config 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 (list[YAMLKey] | None) – Key(s) leading to 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.

static create_user_updated_config(config_class, config_values, path, schema=None)

Create a config from a base file, user-provided values, or a combination of the two.

Parameters:

• config_class (type[Config]) – The Config subclass matching the config type.

• config_values (dict) – The configuration object to update base values with.

• path (Path) – Path to dump file to.

• schema (dict | None) – Schema to validate final config against.

Return type:

None

property cycle

The cycle.

abstract classmethod driver_name()

The name of this driver.

Return type:

str

namelist_schema(config_keys=None, schema_keys=None)

Return the (sub)schema for validating the driver’s namelist content.

Parameters:

• config_keys (list[YAMLKey] | None) – Keys leading to the namelist block in the driver config.

• schema_keys (list[str] | None) – Keys leading to the namelist-validating (sub)schema.

Return type:

dict

property output: dict[str, Path] | dict[str, list[Path]]

Returns a description of the file(s) created when this component runs.

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.

classmethod schema()

Return the driver’s internal schema.

Return type:

dict

show_output()

Show the output to be created by this component.

taskname(suffix=None)

Return a common tag for task-related log messages.

Parameters:

suffix (str | None) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.DriverCycleLeadtimeBased(cycle, leadtime, config=None, 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).

• key_path (list[YAMLKey] | None) – Keys of keys to driver config 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 (list[YAMLKey] | None) – Key(s) leading to 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.

static create_user_updated_config(config_class, config_values, path, schema=None)

Create a config from a base file, user-provided values, or a combination of the two.

Parameters:

• config_class (type[Config]) – The Config subclass matching the config type.

• config_values (dict) – The configuration object to update base values with.

• path (Path) – Path to dump file to.

• schema (dict | None) – Schema to validate final config against.

Return type:

None

property cycle

The cycle.

abstract classmethod driver_name()

The name of this driver.

Return type:

str

property leadtime

The leadtime.

namelist_schema(config_keys=None, schema_keys=None)

Return the (sub)schema for validating the driver’s namelist content.

Parameters:

• config_keys (list[YAMLKey] | None) – Keys leading to the namelist block in the driver config.

• schema_keys (list[str] | None) – Keys leading to the namelist-validating (sub)schema.

Return type:

dict

property output: dict[str, Path] | dict[str, list[Path]]

Returns a description of the file(s) created when this component runs.

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.

classmethod schema()

Return the driver’s internal schema.

Return type:

dict

show_output()

Show the output to be created by this component.

taskname(suffix=None)

Return a common tag for task-related log messages.

Parameters:

suffix (str | None) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

class uwtools.api.driver.DriverTimeInvariant(config=None, 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).

• key_path (list[YAMLKey] | None) – Keys of keys to driver config 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 (list[YAMLKey] | None) – Key(s) leading to 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.

static create_user_updated_config(config_class, config_values, path, schema=None)

Create a config from a base file, user-provided values, or a combination of the two.

Parameters:

• config_class (type[Config]) – The Config subclass matching the config type.

• config_values (dict) – The configuration object to update base values with.

• path (Path) – Path to dump file to.

• schema (dict | None) – Schema to validate final config against.

Return type:

None

abstract classmethod driver_name()

The name of this driver.

Return type:

str

namelist_schema(config_keys=None, schema_keys=None)

Return the (sub)schema for validating the driver’s namelist content.

Parameters:

• config_keys (list[YAMLKey] | None) – Keys leading to the namelist block in the driver config.

• schema_keys (list[str] | None) – Keys leading to the namelist-validating (sub)schema.

Return type:

dict

property output: dict[str, Path] | dict[str, list[Path]]

Returns a description of the file(s) created when this component runs.

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.

classmethod schema()

Return the driver’s internal schema.

Return type:

dict

show_output()

Show the output to be created by this component.

taskname(suffix=None)

Return a common tag for task-related log messages.

Parameters:

suffix (str | None) – Log-string suffix.

Return type:

str

validate()

Validate the UW driver config.

uwtools.api.driver.yaml_keys_to_classes()

Returns a mapping from UW YAML driver-block keys to their associated driver classes.

Return type:

dict[str, type]