uwtools.api.ecflow

API access to uwtools ecFlow support.

uwtools.api.ecflow.realize(config, output_path=None, scripts_path=None, stdin_ok=False)

Realize the ecFlow workflow defined in the given YAML as a Suite Definition and ecf scripts.

If no input file is specified, stdin is read. A YAMLConfig object may also be provided as input. If no output file is specified, the Suite Definition is written to stdout. The ecf scripts are not produced if scripts_path is not provided.

Parameters:

  • config (_YAMLConfig | Path | str | None) – YAML input file or YAMLConfig object (None => read stdin).

  • output_path (Path | str | None) – Suite Definition output path (None => write to stdout).

  • scripts_path (Path | str | None) – ecf scripts top-level path (None => no scripts are generated).

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

Raises:

UWConfigError if validation fails.

Returns:

True.

Return type:

bool

uwtools.api.ecflow.server(config, port=None, insecure=False, report=False, stdin_ok=False)

Start an ecFlow server on an available TCP port, optionally with SSL security enabled.

If no port is specified, a random port in the registered range (1024-49151) is chosen, retrying if the port is unavailable. SSL certificates are read from or written to $HOME/.ecflowrc/ssl. Use insecure to skip SSL. Use report to emit a JSON report of the server details (e.g. hostname, port) to stdout.

Parameters:

  • config (_YAMLConfig | dict | Path | str | None) – A dict, a YAMLConfig, or a path to a YAML config file (None => read stdin).

  • port (int | None) – TCP port to use; overrides config value (None => pick a random available port from 1024-49151).

  • insecure (bool) – Start the server without SSL security.

  • report (bool) – Output server details (e.g. hostname, port) as JSON to stdout.

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

Returns:

True.

Return type:

bool

uwtools.api.ecflow.validate(config=None, stdin_ok=False)

Validate an ecFlow config against its schema.

Parameters:

  • config (_YAMLConfig | dict | Path | str | None) – YAML input file or YAMLConfig object to validate (None => read stdin).

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

Returns:

True if the config conforms to the schema.

Raises:

UWConfigError if validation fails.

Return type:

bool