cosmotech.coal.cosmotech_api

cosmotech.coal.cosmotech_api.apis.DatasetApi

Bases: DatasetApi, Connection

              flowchart TD
              cosmotech.coal.cosmotech_api.apis.DatasetApi[DatasetApi]
              cosmotech.coal.cosmotech_api.objects.connection.Connection[Connection]

                              cosmotech.coal.cosmotech_api.objects.connection.Connection --> cosmotech.coal.cosmotech_api.apis.DatasetApi
                


              click cosmotech.coal.cosmotech_api.apis.DatasetApi href "" "cosmotech.coal.cosmotech_api.apis.DatasetApi"
              click cosmotech.coal.cosmotech_api.objects.connection.Connection href "" "cosmotech.coal.cosmotech_api.objects.connection.Connection"
            

Methods:

Name	Description
download_dataset	Download all parts of a dataset to the configured dataset folder.
download_parameter	Download all parts of a dataset to the configured parameters folder.
path_to_parts	Turn a file or directory path into a list of dataset part descriptors.
upload_dataset	Upload a new dataset with optional tags and additional data.
upload_dataset_parts	Upload parts to an existing dataset.

download_dataset(dataset_id)

Download all parts of a dataset to the configured dataset folder.

Parameters:

Name	Type	Description	Default
dataset_id		The ID of the dataset to download	required

Returns:

Type	Description
Dataset	The Dataset object as returned by the API

download_parameter(dataset_id)

Download all parts of a dataset to the configured parameters folder.

Parameters:

Name	Type	Description	Default
dataset_id		The ID of the dataset to download	required

Returns:

Type	Description
Dataset	The Dataset object as returned by the API

path_to_parts(_path, part_type) staticmethod

Turn a file or directory path into a list of dataset part descriptors.

Parameters:

Name	Type	Description	Default
_path		Path to a file, or to a directory whose files are each turned into a part	required
part_type		The DatasetPartTypeEnum to assign to every resulting part	required

Returns:

Type	Description
list[tuple[str, Path, DatasetPartTypeEnum]]	A list of tuples of (relative part name, absolute file path, part type)

upload_dataset(dataset_name, as_files=(), as_db=(), tags=None, additional_data=None)

Upload a new dataset with optional tags and additional data.

Parameters:

Name	Type	Description	Default
dataset_name	str	The name of the dataset to create	required
as_files	Optional[list[Union[Path, str]]]	List of file paths to upload as FILE type parts	()
as_db	Optional[list[Union[Path, str]]]	List of file paths to upload as DB type parts	()
tags	Optional[list[str]]	Optional list of tags to associate with the dataset	None
additional_data	Optional[dict]	Optional dictionary of additional metadata	None

Returns:

Type	Description
Dataset	The created Dataset object

upload_dataset_parts(dataset_id, as_files=(), as_db=(), replace_existing=False)

Upload parts to an existing dataset.

Parameters:

Name	Type	Description	Default
dataset_id	str	The ID of the existing dataset	required
as_files	Optional[list[Union[Path, str]]]	List of file paths to upload as FILE type parts	()
as_db	Optional[list[Union[Path, str]]]	List of file paths to upload as DB type parts	()
replace_existing	bool	If True, replace existing parts with same name	False

Returns:

Type	Description
Dataset	The updated Dataset object

cosmotech.coal.cosmotech_api.apis.RunApi

Bases: RunApi, Connection

              flowchart TD
              cosmotech.coal.cosmotech_api.apis.RunApi[RunApi]
              cosmotech.coal.cosmotech_api.objects.connection.Connection[Connection]

                              cosmotech.coal.cosmotech_api.objects.connection.Connection --> cosmotech.coal.cosmotech_api.apis.RunApi
                


              click cosmotech.coal.cosmotech_api.apis.RunApi href "" "cosmotech.coal.cosmotech_api.apis.RunApi"
              click cosmotech.coal.cosmotech_api.objects.connection.Connection href "" "cosmotech.coal.cosmotech_api.objects.connection.Connection"
            

Methods:

Name	Description
get_run_metadata	Fetch a run and serialize it to a JSON-compatible dictionary.

get_run_metadata(organization_id, workspace_id, runner_id, run_id, include=None, exclude=None)

Fetch a run and serialize it to a JSON-compatible dictionary.

Parameters:

Name	Type	Description	Default
organization_id	str	The ID of the organization	required
workspace_id	str	The ID of the workspace	required
runner_id	str	The ID of the runner	required
run_id	str	The ID of the run	required
include	Optional[list[str]]	Optional list of field names to include in the result	None
exclude	Optional[list[str]]	Optional list of field names to exclude from the result	None

Returns:

Type	Description
dict[str, Any]	A dictionary representation of the run's metadata

cosmotech.coal.cosmotech_api.apis.RunnerApi

Bases: RunnerApi, Connection

              flowchart TD
              cosmotech.coal.cosmotech_api.apis.RunnerApi[RunnerApi]
              cosmotech.coal.cosmotech_api.objects.connection.Connection[Connection]

                              cosmotech.coal.cosmotech_api.objects.connection.Connection --> cosmotech.coal.cosmotech_api.apis.RunnerApi
                


              click cosmotech.coal.cosmotech_api.apis.RunnerApi href "" "cosmotech.coal.cosmotech_api.apis.RunnerApi"
              click cosmotech.coal.cosmotech_api.objects.connection.Connection href "" "cosmotech.coal.cosmotech_api.objects.connection.Connection"
            

Methods:

Name	Description
get_runner_metadata	Fetch a runner and serialize it to a JSON-compatible dictionary.
download_runner_data	Download a runner's parameters and, optionally, its associated datasets.

get_runner_metadata(runner_id=None, include=None, exclude=None)

Fetch a runner and serialize it to a JSON-compatible dictionary.

Parameters:

Name	Type	Description	Default
runner_id	Optional[str]	The ID of the runner, defaults to the configured runner ID	None
include	Optional[list[str]]	Optional list of field names to include in the result	None
exclude	Optional[list[str]]	Optional list of field names to exclude from the result	None

Returns:

Type	Description
dict[str, Any]	A dictionary representation of the runner's metadata

download_runner_data(download_datasets=None)

Download a runner's parameters and, optionally, its associated datasets.

Parameters:

Name	Type	Description	Default
download_datasets	Optional[str]	If set, also download the runner's base datasets	None

cosmotech.coal.cosmotech_api.apis.WorkspaceApi

Bases: WorkspaceApi, Connection

              flowchart TD
              cosmotech.coal.cosmotech_api.apis.WorkspaceApi[WorkspaceApi]
              cosmotech.coal.cosmotech_api.objects.connection.Connection[Connection]

                              cosmotech.coal.cosmotech_api.objects.connection.Connection --> cosmotech.coal.cosmotech_api.apis.WorkspaceApi
                


              click cosmotech.coal.cosmotech_api.apis.WorkspaceApi href "" "cosmotech.coal.cosmotech_api.apis.WorkspaceApi"
              click cosmotech.coal.cosmotech_api.objects.connection.Connection href "" "cosmotech.coal.cosmotech_api.objects.connection.Connection"
            

Methods:

Name	Description
list_filtered_workspace_files	List workspace files whose name starts with the given prefix.
download_workspace_file	Download a single workspace file to a local directory.
upload_workspace_file	Upload a local file to a workspace.

list_filtered_workspace_files(organization_id, workspace_id, file_prefix)

List workspace files whose name starts with the given prefix.

Parameters:

Name	Type	Description	Default
organization_id	str	The ID of the organization	required
workspace_id	str	The ID of the workspace	required
file_prefix	str	The prefix to filter workspace file names by	required

Returns:

Type	Description
list[str]	List of matching workspace file names

Raises:

Type	Description
ValueError	If no workspace file matches the given prefix

download_workspace_file(organization_id, workspace_id, file_name, target_dir)

Download a single workspace file to a local directory.

Parameters:

Name	Type	Description	Default
organization_id	str	The ID of the organization	required
workspace_id	str	The ID of the workspace	required
file_name	str	The name of the workspace file to download	required
target_dir	Path	The local directory to download the file into	required

Returns:

Type	Description
Path	The local path of the downloaded file

Raises:

Type	Description
ValueError	If target_dir is not a directory

upload_workspace_file(organization_id, workspace_id, file_path, workspace_path, overwrite=True)

Upload a local file to a workspace.

Parameters:

Name	Type	Description	Default
organization_id	str	The ID of the organization	required
workspace_id	str	The ID of the workspace	required
file_path	str	Local path of the file to upload	required
workspace_path	str	Destination path (or directory ending with '/') in the workspace	required
overwrite	bool	If True, overwrite an existing file at the destination	True

Returns:

Type	Description
str	The name of the uploaded workspace file

Raises:

Type	Description
ValueError	If file_path does not exist or is not a single file
ApiException	If the API call fails, e.g. because the file already exists

cosmotech.coal.cosmotech_api.objects.Connection

Methods:

Name	Description
get_api_client	Build an authenticated API client from available environment variables.

get_api_client()

Build an authenticated API client from available environment variables.

Detects Keycloak, Cosmo Tech API key, or Azure Entra credentials from the environment and builds the corresponding API client.

Returns:

Type	Description
(ApiClient, str)	A tuple of the configured ApiClient and a label describing the connection type used

Raises:

Type	Description
EnvironmentError	If no complete set of required environment variables is found

cosmotech.coal.cosmotech_api.objects.Parameters

Methods:

Name	Description
format_parameters_list	Format parameters from runner data as a list of dictionaries.
write_parameters_to_json	Write the parameters list to a parameters.json file.
write_parameters_to_csv	Write the parameters list to a parameters.csv file.
write_parameters	Write the parameters list to CSV and/or JSON files.

format_parameters_list(runner_data) staticmethod

Format parameters from runner data as a list of dictionaries.

Parameters:

Name	Type	Description	Default
runner_data	Any	Runner data object	required

Returns:

Type	Description
List[Dict[str, Any]]	List of parameter dictionaries

write_parameters_to_json(parameter_folder)

Write the parameters list to a parameters.json file.

Parameters:

Name	Type	Description	Default
parameter_folder	str	Directory in which to create the JSON file	required

Returns:

Type	Description
str	The path of the written JSON file

write_parameters_to_csv(parameter_folder)

Write the parameters list to a parameters.csv file.

Parameters:

Name	Type	Description	Default
parameter_folder	str	Directory in which to create the CSV file	required

Returns:

Type	Description
str	The path of the written CSV file

write_parameters(parameter_folder, write_csv=True, write_json=False)

Write the parameters list to CSV and/or JSON files.

Parameters:

Name	Type	Description	Default
parameter_folder	str	Directory in which to create the files	required
write_csv	bool	If True, write a parameters.csv file	True
write_json	bool	If True, write a parameters.json file	False

Returns:

Type	Description
Dict[str, str]	Dictionary mapping format name ("csv", "json") to the written file path