Clients¶

`ImagesClient`¶

class puddle.client.ImagesClient(cloud, server_address=None, authorizer=None, api_key_id=None, api_secret_key=None, verify=True)¶

Bases: puddle.client.base_client.BaseCloudClient

Client used to query images in Puddle.

POLL_INTERVAL_S = 30¶: Polling interval in seconds.

POLL_TIMEOUT_MINUTES = 60¶: Timeout in minutes to wait till operation (such as report creation) is completed.

__init__(cloud, server_address=None, authorizer=None, api_key_id=None, api_secret_key=None, verify=True)¶

Creates new instance of this client tied to specified cloud provider.

Parameters

server_address (Optional[str]) – Address of the backend.
cloud (CloudProvider) – cloud which should be used by this client.
authorizer (Optional[BaseAuthorizer]) – optional, Authorizer to use, if not set, then the default Authorizer which reads credentials from env is used.
api_key_id (Optional[str]) – Optional, API Key ID to use, ignored if authorizer is set. If authorizer is not set, then it is read from PUDDLE_api_key_id environment variable. If even this variable is not set, then a ValueError is risen.
api_secret_key (Optional[str]) – Optional, API Secret Key, ignored if authorizer is set. If authorizer is not set. then it is read from PUDDLE_api_secret_key environment variable. If even this variable is not set, then a ValueError is risen.
verify (Optional[bool]) – Optional, Enable (=True) / Disable (=False) SSL certificate verification. Defaults to True.

property authorizer¶

Return type: BaseAuthorizer
Returns: BaseAuthorizer used by this client

build(image_id)¶

Builds a new version of the specified image. ADMINISTRATOR role is required for this method. This function returns without waiting for the build operation to finish. To wait use the wait_for_image_available function.

Parameters: image_id (str) – Id of the image which should be built.

list()¶

Return type: List[Image]
Returns: List of all Images for authenticated user. For administrators this

returns also images with are not ready to use.

list_available()¶

Return type: List[Image]
Returns: List of images usable to create new systems.

property server_address¶

Returns: Backend address.

property verify¶

Return type: bool
Returns: SSL certificate verification enabled

wait_for_image_available(image_id)¶

Waits for the image with specified id to be available.

Parameters: image_id (str) – Id of the image to wait for.
Return type: bool
Returns: True when image status Available was reached in time (timeout

is ImagesClient.POLL_TIMEOUT_MINUTES minutes), otherwise return False. False is also returned when image enters another final status (other than Available) before time out.

`InstanceTypesClient`¶

class puddle.client.InstanceTypesClient(cloud, server_address=None, authorizer=None, api_key_id=None, api_secret_key=None, verify=True)¶

Bases: puddle.client.base_client.BaseCloudClient

Client used to query instance types in Puddle.

__init__(cloud, server_address=None, authorizer=None, api_key_id=None, api_secret_key=None, verify=True)¶

Creates new instance of this client tied to specified cloud provider.

Parameters

server_address (Optional[str]) – Address of the backend.
cloud (CloudProvider) – cloud which should be used by this client.
authorizer (Optional[BaseAuthorizer]) – optional, Authorizer to use, if not set, then the default Authorizer which reads credentials from env is used.
api_key_id (Optional[str]) – Optional, API Key ID to use, ignored if authorizer is set. If authorizer is not set, then it is read from PUDDLE_api_key_id environment variable. If even this variable is not set, then a ValueError is risen.
api_secret_key (Optional[str]) – Optional, API Secret Key, ignored if authorizer is set. If authorizer is not set. then it is read from PUDDLE_api_secret_key environment variable. If even this variable is not set, then a ValueError is risen.
verify (Optional[bool]) – Optional, Enable (=True) / Disable (=False) SSL certificate verification. Defaults to True.

property authorizer¶

Return type: BaseAuthorizer
Returns: BaseAuthorizer used by this client

list_available()¶

Return type: List[InstanceType]
Returns: List of all available InstanceTypes for authenticated user.

property server_address¶

Returns: Backend address.

property verify¶

Return type: bool
Returns: SSL certificate verification enabled

`ReportsClient`¶

class puddle.client.reports.ReportsClient(server_address=None, authorizer=None, api_key_id=None, api_secret_key=None, verify=True)¶

Bases: puddle.client.base_client.BasePuddleClient

Client used to manage Puddle reports. All functions of this client requires Administrator role.

POLL_INTERVAL_S = 5¶: Polling interval in seconds.

POLL_TIMEOUT_MINUTES = 5¶: Timeout in minutes to wait till operation (such as report creation) is completed.

__init__(server_address=None, authorizer=None, api_key_id=None, api_secret_key=None, verify=True)¶

Creates new instance of this client.

Parameters

server_address (Optional[str]) – Optional, address of the backend. If not set then it is read from PUDDLE_SERVER_ADDRESS environment variable. If even this variable is not set, then a ValueError is risen.
authorizer (Optional[BaseAuthorizer]) – optional, Authorizer to use, if not set, then the default Authorizer which reads credentials from env is used.
api_key_id (Optional[str]) – Optional, API Key ID to use, ignored if authorizer is set. If authorizer is not set, then it is read from PUDDLE_api_key_id environment variable. If even this variable is not set, then a ValueError is risen.
api_secret_key (Optional[str]) – Optional, API Secret Key, ignored if authorizer is set. If authorizer is not set. then it is read from PUDDLE_api_secret_key environment variable. If even this variable is not set, then a ValueError is risen.
verify (Optional[bool]) – Optional, Enable (=True) / Disable (=False) SSL certificate verification. Defaults to True.

property authorizer¶

Return type: BaseAuthorizer
Returns: BaseAuthorizer used by this client

create(title, from_date, to_date)¶: Creates a new report with specified parameters. This function waits for the report to be available. :type title: str :param title: report title. :type from_date: datetime :param from_date: start of the time frame for this report (inclusive). :type to_date: datetime :param to_date: end of the time frame for this report (inclusive). :rtype: Report :return: newly created report.

delete(report_id)¶: Deletes the report with specified report_id. This operation cannot be reverted. :type report_id: str :param report_id: id of the report to delete. :return:

download(report_id, download_to)¶

Downloads the report to specified file. The parent directory of the file must be writable. If the file already exists, it’s overwritten.

Parameters

report_id (str) – id of the report to download.
download_to (str) – target path where to download the report. Overwritten if already exists.

get(report_id)¶: Gets a report with specified report_id. Could be used to refresh a loaded report. :type report_id: str :param report_id: id of the report to get. :rtype: Optional[Report] :return: new report.

list()¶

Return type: List[Report]
Returns: list of all reports.

property server_address¶

Returns: Backend address.

property verify¶

Return type: bool
Returns: SSL certificate verification enabled

`SystemsClient`¶

class puddle.client.SystemsClient(cloud, server_address=None, authorizer=None, api_key_id=None, api_secret_key=None, verify=True)¶

Bases: puddle.client.base_client.BaseCloudClient

Client used to manage the systems in Puddle.

DEFAULT_DISK_SIZE = 256¶: Default disk size in GB.

DEFAULT_IDLE_TIMEOUT_MIN = 60¶: Default idle timeout in minutes.

POLL_INTERVAL_S = 5¶: Polling interval in seconds.

POLL_TIMEOUT_MINUTES = 20¶: Timeout in minutes to wait till operation (such as system start) is completed.

__init__(cloud, server_address=None, authorizer=None, api_key_id=None, api_secret_key=None, verify=True)¶

Creates new instance of this client tied to specified cloud provider.

Parameters

server_address (Optional[str]) – Address of the backend.
cloud (CloudProvider) – cloud which should be used by this client.
authorizer (Optional[BaseAuthorizer]) – optional, Authorizer to use, if not set, then the default Authorizer which reads credentials from env is used.
api_key_id (Optional[str]) – Optional, API Key ID to use, ignored if authorizer is set. If authorizer is not set, then it is read from PUDDLE_api_key_id environment variable. If even this variable is not set, then a ValueError is risen.
api_secret_key (Optional[str]) – Optional, API Secret Key, ignored if authorizer is set. If authorizer is not set. then it is read from PUDDLE_api_secret_key environment variable. If even this variable is not set, then a ValueError is risen.
verify (Optional[bool]) – Optional, Enable (=True) / Disable (=False) SSL certificate verification. Defaults to True.

property authorizer¶

Return type: BaseAuthorizer
Returns: BaseAuthorizer used by this client

create(name, disk_size_gb=256, image=None, product=None, version=None, instance_type=None, instance_type_name=None, idle_interval=60, tags=None)¶

Creates new system with specified parameters. This function returns without waiting for the cloud operation to finish. To wait use the wait_for_system_started function.

Parameters

name (str) – Name of the system. Must be unique, must contain only lowercase alphanumeric characters, numbers and hyphens and cannot be longer than 64 chars.
disk_size_gb (int) – Size of disk in GB. Defaults to SystemsClient.DEFAULT_DISK_SIZE. Must be between 256 and 1024.
image (Optional[Image]) – Image to be used by this system. If not set, then product and version must be set.
product (Optional[Product]) – Product id to be used by this system. If not set, then image must be set.
version (Optional[str]) – Version of product to be used by this system. If not set then image must be set.
instance_type (Optional[InstanceType]) – Instance type to be used by this system. If not set then instance_type_name must be set.
instance_type_name (Optional[str]) – instance type name to be used by this system. If not set then instance_type must be set.
idle_interval (int) – Idle timeout interval. System will be stopped if idle for this number of minutes. Defaults to SystemsClient.DEFAULT_IDLE_TIMEOUT_MIN. Must be <= than 240 (4 * 60) minutes.
tags (Optional[List[TagData]]) – List of TagData.

Return type

System

Returns

Newly created System.

Raise

ValidationFailedError if any of the validations fails.

delete_snapshot(snapshot_id)¶

Deletes the specified snapshot. This function does not wait for the cloud: operation to finish.

Parameters: snapshot_id (str) – Id of the snapshot which should be deleted.
Raise: PreconditionFailedError if the snapshot cannot be created, for example, because the system is not stopped.

edit_idle_timeout(system_id, idle_timeout_interval)¶

Edits the idle timeout interval for this system. Unlike the extend_idle_timeout method, this will edit the setting of the system for this and all following sessions.

Parameters

system_id (str) – Id of the system to edit.
idle_timeout_interval (int) – new idle_timeout_interval value.

Raise

PreconditionFailedError if the idle timeout interval cannot be changed, for example because the system is not started.

extend_idle_timeout(system_id, hours)¶

Extends the idle timeout for this system for this session by the number of hours specified.

Parameters

system_id (str) – Id of the system which timeout should be modified.
hours (int) – How many hours should be added to the idle timeout of the system.

Raise

PreconditionFailedError if the idle timeout cannot be extended, for example because the system is not started.

fail(system_id)¶

Marks the system with specified system id as failed. This function does not wait for the operation to finish. To wait use the wait_for_system_failed function.

Parameters: system_id (str) – Id of the system which should be marked as failed.
Raise: PreconditionFailedError if system cannot be marked as failed, for example because the option to manually mark the system as failed is not available at this moment. To check if it is possible to manually mark this system as failed use the can_fail property of the relevant System instance.

find_by_name(name)¶

Returns system with specified name or None if no such system exists.

Parameters: name (str) – Name of the required system.
Return type: Optional[System]
Returns: System with specified name or None if no such system exists.

get(system_id)¶

Gets a system with specified system_id. Could be used to refresh a loaded system.

Parameters: system_id – Id of the required system.
Return type: Optional[System]
Returns: New System created from data returned by backend.

get_cu_consumption_info()¶

Return type: CUConsumptionInfo
Returns: current cu consumption info. Useful to check how much CU is currently available and what is the current CU consumption of your systems.

list()¶

Return type: List[System]
Returns: List of all non-terminated systems for current user.

list_all()¶

Return type: List[System]
Returns: List of all non-terminated systems for all users. ADMINISTRATOR role is required for this call.
Raise: TwirpException if the user does not have Administrator role.

refresh_idle_timeout(system_id)¶

Refreshes idle timeout for the system with specified id.

Parameters: system_id (str) – Id of the system which should refresh its idle timeout.
Raise: PreconditionFailedError if the idle timeout cannot be refreshed, for example because the system is not started.

replicate(system_id, new_system_name, disk_size_gb=256, source_snapshot_id=None, version=None, instance_type=None, instance_type_name=None, idle_interval=60, tags=None)¶

Creates new system with specified parameters. If source_snapshot_id is specified then this snapshot is used to provision new system otherwise a new snapshot is created. This function returns without waiting for the cloud operation to finish. To wait use the wait_for_system_started function.

Parameters

new_system_name (str) – Name of the system. Must be unique, must contain only lowercase alphanumeric characters, numbers and hyphens and cannot be longer than 64 chars.
disk_size_gb (int) – Size of disk in GB. Defaults to SystemsClient.DEFAULT_DISK_SIZE. Must be between 256 and 1024.
system_id (str) – Id of the system, which should be replicated.
source_snapshot_id (Optional[str]) – Optional id of the snapshot, which should be used as source for the newly created system. If not set then a new snapshot is created.
version (Optional[str]) – version of the product to use in new replica. Only the version as on the source system or newer can be used. If not set, then the same version as in the source system is used.
instance_type (Optional[InstanceType]) – Instance type to be used by this system. If not set then instance_type_name must be set.
instance_type_name (Optional[str]) – instance type name to be used by this system. If not set then instance_type must be set.
idle_interval (int) – Idle timeout interval. System will be stopped if idle for this number of minutes. Defaults to SystemsClient.DEFAULT_IDLE_TIMEOUT_MIN. Must be <= than 240 (4 * 60) minutes.
tags (Optional[List[TagData]]) – List of TagData.

Return type

System

Returns

Newly created System.

Raise

ValidationFailedError if any of the validations fails.

restart(system_id)¶

Restarts the system with specified system id. This function does not wait for the cloud operation to finish. To wait use the wait_for_system_started function.

Parameters: system_id (str) – Id of the system which should be restarted.
Raise: PreconditionFailedError if system cannot be restarted, for example because it’s not in started state.

restart_dai(system_id)¶

Restarts Driverless AI on the system with the specified system ID. This function does not wait for the operation to finish. To wait, use the wait_for_system_started function. Raises error if used on a system running a product other than Driverless AI.

Parameters: system_id (str) – Id of the system where Driverless AI should be restarted.
Raise: PreconditionFailedError if Driverless AI cannot be restarted, for example because the system is not in started state.

restart_product(system_id)¶

Restarts H2O.ai product on the system with the specified system ID. This function does not wait for the operation to finish. To wait, use the wait_for_system_started function. Raises error if used on a system running a product other than Driverless AI.

Parameters: system_id (str) – Id of the system where product should be restarted.
Raise: PreconditionFailedError if product cannot be restarted, for example because the system is not in started state.

scale(system_id, instance_type=None, instance_type_name=None)¶

Changes the instance type of the specified system. It is possible to scale only stopped systems. This function does not wait for the cloud operation to finish. Use the wait_for_system_stopped function to wait for the cloud operation to finish.

Parameters

system_id (str) – Id of the system that should be scaled.
instance_type (Optional[InstanceType]) – New InstanceType that this system should use. If not set, then instance_type_name must be set.
instance_type_name (Optional[str]) – Name of the new instance type that this system should use. If not set, then the instance_type must be set.

Raise

PreconditionFailedError if the system cannot be scaled, for example, because the system is not stopped.

property server_address¶

Returns: Backend address.

snapshot(system_id, description=None)¶

Creates a snapshot of the system. Only stopped systems can be used to create snapshots. This function does not wait for the cloud operation to finish. Use the wait_for_system_stopped function to wait for the cloud operation to finish.

Parameters

system_id (str) – Id of the system of which the snapshot should be created.
description (Optional[str]) – Optional description of the snapshot.

Raise

PreconditionFailedError if the snapshot cannot be created, for example, because the system is not stopped.

start(system_id)¶

Starts the system with specified system id. This function does not wait for the cloud operation to finish. To wait use the wait_for_system_started function.

Parameters: system_id (str) – Id of the system which should be started.
Raise: PreconditionFailedError if system cannot be started, for example because it’s not in stopped state.

stop(system_id)¶

Stops the system with specified system id. This function does not wait for the cloud operation to finish. To wait use the wait_for_system_stopped function.

Parameters: system_id (str) – Id of the system which should be stopped.
Raise: PreconditionFailedError if system cannot be stopped, for example because it’s not in started nor in failed state.

terminate(system_id)¶

Terminates the system with specified system id. This function does not wait for the cloud operation to finish. To wait use the wait_for_system_terminated function. This operation cannot be reverted.

Parameters: system_id (str) – Id of the system which should be terminated.
Raise: PreconditionFailedError if system cannot be terminated, for example because it’s not in started nor in failed nor in stopped state.

update_config(system_id, config, product)¶

Updates product config on the system with specified id. System has to be restarted in order for this new config to be applied.

Parameters

system_id (str) – Id of the system which config should be updated.
config (str) – str containing the new config content.
product (Product) – Product of which the config should be updated.

Raise

PreconditionFailedError if the config cannot be updated, for example because the system is not started.

update_config_toml(system_id, config_toml)¶

property verify¶

Return type: bool
Returns: SSL certificate verification enabled

wait_for_config_toml_uploaded(_)¶: Deprecated function, present only for backward compatibility. It is no longer required to wait for the config.toml to be uploaded.

wait_for_system_failed(system_id)¶

Waits for the system with specified id to be failed. This times out after SystemsClient.POLL_TIMEOUT_MINUTES minutes.

Parameters: system_id (str) – Id of the system to wait for.

wait_for_system_started(system_id)¶

Waits for the system with specified id to be started. This times out after SystemsClient.POLL_TIMEOUT_MINUTES minutes. This operation will also fail if the system enters failed state while waiting.

Parameters: system_id (str) – Id of the system to wait for.

wait_for_system_stopped(system_id)¶

Waits for the system with specified id to be stopped. This times out after SystemsClient.POLL_TIMEOUT_MINUTES minutes. This operation will also fail if the system enters failed state while waiting.

Parameters: system_id (str) – Id of the system to wait for.

wait_for_system_terminated(system_id)¶

Waits for the system with specified id to be terminated. This times out after SystemsClient.POLL_TIMEOUT_MINUTES minutes. This operation will also fail if the system enters failed state while waiting.

Parameters: system_id (str) – Id of the system to wait for.

`TagsClient`¶

class puddle.client.TagsClient(server_address=None, authorizer=None, api_key_id=None, api_secret_key=None, verify=True)¶

Bases: puddle.client.base_client.BasePuddleClient

Client used to query the tags in Puddle.

__init__(server_address=None, authorizer=None, api_key_id=None, api_secret_key=None, verify=True)¶

Creates new instance of this client.

Parameters

server_address (Optional[str]) – Optional, address of the backend. If not set then it is read from PUDDLE_SERVER_ADDRESS environment variable. If even this variable is not set, then a ValueError is risen.
authorizer (Optional[BaseAuthorizer]) – optional, Authorizer to use, if not set, then the default Authorizer which reads credentials from env is used.
api_key_id (Optional[str]) – Optional, API Key ID to use, ignored if authorizer is set. If authorizer is not set, then it is read from PUDDLE_api_key_id environment variable. If even this variable is not set, then a ValueError is risen.
api_secret_key (Optional[str]) – Optional, API Secret Key, ignored if authorizer is set. If authorizer is not set. then it is read from PUDDLE_api_secret_key environment variable. If even this variable is not set, then a ValueError is risen.
verify (Optional[bool]) – Optional, Enable (=True) / Disable (=False) SSL certificate verification. Defaults to True.

property authorizer¶

Return type: BaseAuthorizer
Returns: BaseAuthorizer used by this client

list()¶

Returns: List of all Tag object.

property server_address¶

Returns: Backend address.

tag_data_to_pb_tag_data(tags)¶

Translation method between puddle.client.models.tag_data.TagData and puddle.client.proto.v2.system_service_pb2.TagData.

Parameters: tags (List[TagData]) – Source list of puddle.client.models.tag_data.TagData
Return type: Optional[List[TagData]]
Returns: List of puddle.client.proto.v2.system_service_pb2.TagData created from the tags.

property verify¶

Return type: bool
Returns: SSL certificate verification enabled

Clients¶

ImagesClient¶

InstanceTypesClient¶

ReportsClient¶

SystemsClient¶

TagsClient¶

`ImagesClient`¶

`InstanceTypesClient`¶

`ReportsClient`¶

`SystemsClient`¶

`TagsClient`¶