verda 0.1.0__py3-none-any.whl → 1.17.0__py3-none-any.whl

verda/instances/instances.py

@@ -0,0 +1,260 @@
+import itertools
+import time
+from dataclasses import dataclass
+from typing import Literal
+
+from dataclasses_json import dataclass_json
+
+from verda.constants import InstanceStatus, Locations
+
+INSTANCES_ENDPOINT = '/instances'
+
+Contract = Literal['LONG_TERM', 'PAY_AS_YOU_GO', 'SPOT']
+Pricing = Literal['DYNAMIC_PRICE', 'FIXED_PRICE']
+
+
+@dataclass_json
+@dataclass
+class Instance:
+    """Represents a cloud instance with its configuration and state.
+
+    Attributes:
+        id: Unique identifier for the instance.
+        instance_type: Type of the instance (e.g., '8V100.48V').
+        price_per_hour: Cost per hour of running the instance.
+        hostname: Network hostname of the instance.
+        description: Human-readable description of the instance.
+        status: Current operational status of the instance.
+        created_at: Timestamp of instance creation.
+        ssh_key_ids: List of SSH key IDs associated with the instance.
+        cpu: CPU configuration details.
+        gpu: GPU configuration details.
+        memory: Memory configuration details.
+        storage: Storage configuration details.
+        gpu_memory: GPU memory configuration details.
+        ip: IP address assigned to the instance.
+        os_volume_id: ID of the operating system volume.
+        location: Datacenter location code (default: Locations.FIN_03).
+        image: Image ID or type used for the instance.
+        startup_script_id: ID of the startup script to run.
+        is_spot: Whether the instance is a spot instance.
+        contract: Contract type for the instance. (e.g. 'LONG_TERM', 'PAY_AS_YOU_GO', 'SPOT')
+        pricing: Pricing model for the instance. (e.g. 'DYNAMIC_PRICE', 'FIXED_PRICE')
+    """
+
+    id: str
+    instance_type: str
+    price_per_hour: float
+    hostname: str
+    description: str
+    status: str
+    created_at: str
+    ssh_key_ids: list[str]
+    cpu: dict
+    gpu: dict
+    memory: dict
+    storage: dict
+    gpu_memory: dict
+    # Can be None if instance is still not provisioned
+    ip: str | None = None
+    # Can be None if instance is still not provisioned
+    os_volume_id: str | None = None
+    location: str = Locations.FIN_03
+    image: str | None = None
+    startup_script_id: str | None = None
+    is_spot: bool = False
+    contract: Contract | None = None
+    pricing: Pricing | None = None
+
+
+class InstancesService:
+    """Service for managing cloud instances through the API.
+
+    This service provides methods to create, retrieve, and manage cloud instances.
+    """
+
+    def __init__(self, http_client) -> None:
+        """Initializes the InstancesService with an HTTP client.
+
+        Args:
+            http_client: HTTP client for making API requests.
+        """
+        self._http_client = http_client
+
+    def get(self, status: str | None = None) -> list[Instance]:
+        """Retrieves all non-deleted instances or instances with specific status.
+
+        Args:
+            status: Optional status filter for instances. If None, returns all
+                non-deleted instances.
+
+        Returns:
+            List of instance objects matching the criteria.
+        """
+        instances_dict = self._http_client.get(INSTANCES_ENDPOINT, params={'status': status}).json()
+        return [
+            Instance.from_dict(instance_dict, infer_missing=True)
+            for instance_dict in instances_dict
+        ]
+
+    def get_by_id(self, id: str) -> Instance:
+        """Retrieves a specific instance by its ID.
+
+        Args:
+            id: Unique identifier of the instance to retrieve.
+
+        Returns:
+            Instance object with the specified ID.
+
+        Raises:
+            HTTPError: If the instance is not found or other API error occurs.
+        """
+        instance_dict = self._http_client.get(INSTANCES_ENDPOINT + f'/{id}').json()
+        return Instance.from_dict(instance_dict, infer_missing=True)
+
+    def create(
+        self,
+        instance_type: str,
+        image: str,
+        hostname: str,
+        description: str,
+        ssh_key_ids: list = [],
+        location: str = Locations.FIN_03,
+        startup_script_id: str | None = None,
+        volumes: list[dict] | None = None,
+        existing_volumes: list[str] | None = None,
+        os_volume: dict | None = None,
+        is_spot: bool = False,
+        contract: Contract | None = None,
+        pricing: Pricing | None = None,
+        coupon: str | None = None,
+        *,
+        max_wait_time: float = 180,
+        initial_interval: float = 0.5,
+        max_interval: float = 5,
+        backoff_coefficient: float = 2.0,
+    ) -> Instance:
+        """Creates and deploys a new cloud instance.
+
+        Args:
+            instance_type: Type of instance to create (e.g., '8V100.48V').
+            image: Image type or existing OS volume ID for the instance.
+            hostname: Network hostname for the instance.
+            description: Human-readable description of the instance.
+            ssh_key_ids: List of SSH key IDs to associate with the instance.
+            location: Datacenter location code (default: Locations.FIN_03).
+            startup_script_id: Optional ID of startup script to run.
+            volumes: Optional list of volume configurations to create.
+            existing_volumes: Optional list of existing volume IDs to attach.
+            os_volume: Optional OS volume configuration details.
+            is_spot: Whether to create a spot instance.
+            contract: Optional contract type for the instance.
+            pricing: Optional pricing model for the instance.
+            coupon: Optional coupon code for discounts.
+            max_wait_time: Maximum total wait for the instance to start provisioning, in seconds (default: 180)
+            initial_interval: Initial interval, in seconds (default: 0.5)
+            max_interval: The longest single delay allowed between retries, in seconds (default: 5)
+            backoff_coefficient: Coefficient to calculate the next retry interval (default 2.0)
+
+        Returns:
+            The newly created instance object.
+
+        Raises:
+            HTTPError: If instance creation fails or other API error occurs.
+        """
+        payload = {
+            'instance_type': instance_type,
+            'image': image,
+            'ssh_key_ids': ssh_key_ids,
+            'startup_script_id': startup_script_id,
+            'hostname': hostname,
+            'description': description,
+            'location_code': location,
+            'os_volume': os_volume,
+            'volumes': volumes,
+            'existing_volumes': existing_volumes,
+            'is_spot': is_spot,
+            'coupon': coupon,
+        }
+        if contract:
+            payload['contract'] = contract
+        if pricing:
+            payload['pricing'] = pricing
+        id = self._http_client.post(INSTANCES_ENDPOINT, json=payload).text
+
+        # Wait for instance to enter provisioning state with timeout
+        deadline = time.monotonic() + max_wait_time
+        for i in itertools.count():
+            instance = self.get_by_id(id)
+            if instance.status != InstanceStatus.ORDERED:
+                return instance
+
+            now = time.monotonic()
+            if now >= deadline:
+                raise TimeoutError(
+                    f'Instance {id} did not enter provisioning state within {max_wait_time:.1f} seconds'
+                )
+
+            interval = min(initial_interval * backoff_coefficient**i, max_interval, deadline - now)
+            time.sleep(interval)
+
+    def action(
+        self,
+        id_list: list[str] | str,
+        action: str,
+        volume_ids: list[str] | None = None,
+    ) -> None:
+        """Performs an action on one or more instances.
+
+        Args:
+            id_list: Single instance ID or list of instance IDs to act upon.
+            action: Action to perform on the instances.
+            volume_ids: Optional list of volume IDs to delete.
+
+        Raises:
+            HTTPError: If the action fails or other API error occurs.
+        """
+        if type(id_list) is str:
+            id_list = [id_list]
+
+        payload = {'id': id_list, 'action': action, 'volume_ids': volume_ids}
+
+        self._http_client.put(INSTANCES_ENDPOINT, json=payload)
+        return
+
+    def is_available(
+        self,
+        instance_type: str,
+        is_spot: bool = False,
+        location_code: str | None = None,
+    ) -> bool:
+        """Checks if a specific instance type is available for deployment.
+
+        Args:
+            instance_type: Type of instance to check availability for.
+            is_spot: Whether to check spot instance availability.
+            location_code: Optional datacenter location code.
+
+        Returns:
+            True if the instance type is available, False otherwise.
+        """
+        is_spot = str(is_spot).lower()
+        query_params = {'isSpot': is_spot, 'location_code': location_code}
+        url = f'/instance-availability/{instance_type}'
+        return self._http_client.get(url, query_params).json()
+
+    def get_availabilities(
+        self, is_spot: bool | None = None, location_code: str | None = None
+    ) -> list[dict]:
+        """Retrieves a list of available instance types across locations.
+
+        Args:
+            is_spot: Optional flag to filter spot instance availability.
+            location_code: Optional datacenter location code to filter by.
+
+        Returns:
+            List of available instance types and their details.
+        """
+        is_spot = str(is_spot).lower() if is_spot is not None else None
+        query_params = {'isSpot': is_spot, 'locationCode': location_code}
+        return self._http_client.get('/instance-availability', params=query_params).json()

verda/locations/locations.py

@@ -0,0 +1,13 @@
+LOCATIONS_ENDPOINT = '/locations'
+
+
+class LocationsService:
+    """A service for interacting with the locations endpoint."""
+
+    def __init__(self, http_client) -> None:
+        self._http_client = http_client
+
+    def get(self) -> list[dict]:
+        """Get all locations."""
+        locations = self._http_client.get(LOCATIONS_ENDPOINT).json()
+        return locations

verda/ssh_keys/ssh_keys.py

@@ -0,0 +1,109 @@
+SSHKEYS_ENDPOINT = '/sshkeys'
+
+
+class SSHKey:
+    """An SSH key model class."""
+
+    def __init__(self, id: str, name: str, public_key: str) -> None:
+        """Initialize a new SSH key object.
+
+        :param id: SSH key id
+        :type id: str
+        :param name: SSH key name
+        :type name: str
+        :param public_key: SSH key public key
+        :type public_key: str
+        """
+        self._id = id
+        self._name = name
+        self._public_key = public_key
+
+    @property
+    def id(self) -> str:
+        """Get the SSH key id.
+
+        :return: SSH key id
+        :rtype: str
+        """
+        return self._id
+
+    @property
+    def name(self) -> str:
+        """Get the SSH key name.
+
+        :return: SSH key name
+        :rtype: str
+        """
+        return self._name
+
+    @property
+    def public_key(self) -> str:
+        """Get the SSH key public key value.
+
+        :return: public SSH key
+        :rtype: str
+        """
+        return self._public_key
+
+
+class SSHKeysService:
+    """A service for interacting with the SSH keys endpoint."""
+
+    def __init__(self, http_client) -> None:
+        self._http_client = http_client
+
+    def get(self) -> list[SSHKey]:
+        """Get all of the client's SSH keys.
+
+        :return: list of SSH keys objects
+        :rtype: list[SSHKey]
+        """
+        keys = self._http_client.get(SSHKEYS_ENDPOINT).json()
+        keys_object_list = [SSHKey(key['id'], key['name'], key['key']) for key in keys]
+
+        return keys_object_list
+
+    def get_by_id(self, id: str) -> SSHKey:
+        """Get a specific SSH key by id.
+
+        :param id: SSH key id
+        :type id: str
+        :return: SSHKey object
+        :rtype: SSHKey
+        """
+        key_dict = self._http_client.get(SSHKEYS_ENDPOINT + f'/{id}').json()[0]
+        key_object = SSHKey(key_dict['id'], key_dict['name'], key_dict['key'])
+        return key_object
+
+    def delete(self, id_list: list[str]) -> None:
+        """Delete multiple SSH keys by id.
+
+        :param id_list: list of SSH keys ids
+        :type id_list: list[str]
+        """
+        payload = {'keys': id_list}
+        self._http_client.delete(SSHKEYS_ENDPOINT, json=payload)
+        return
+
+    def delete_by_id(self, id: str) -> None:
+        """Delete a single SSH key by id.
+
+        :param id: SSH key id
+        :type id: str
+        """
+        self._http_client.delete(SSHKEYS_ENDPOINT + f'/{id}')
+        return
+
+    def create(self, name: str, key: str) -> SSHKey:
+        """Create a new SSH key.
+
+        :param name: SSH key name
+        :type name: str
+        :param key: public SSH key value
+        :type key: str
+        :return: new SSH key object
+        :rtype: SSHKey
+        """
+        payload = {'name': name, 'key': key}
+        id = self._http_client.post(SSHKEYS_ENDPOINT, json=payload).text
+        return SSHKey(id, name, key)

verda/startup_scripts/startup_scripts.py

@@ -0,0 +1,110 @@
+STARTUP_SCRIPTS_ENDPOINT = '/scripts'
+
+
+class StartupScript:
+    """A startup script model class."""
+
+    def __init__(self, id: str, name: str, script: str) -> None:
+        """Initialize a new startup script object.
+
+        :param id: startup script id
+        :type id: str
+        :param name: startup script name
+        :type name: str
+        :param script: the actual script
+        :type script: str
+        """
+        self._id = id
+        self._name = name
+        self._script = script
+
+    @property
+    def id(self) -> str:
+        """Get the startup script id.
+
+        :return: startup script id
+        :rtype: str
+        """
+        return self._id
+
+    @property
+    def name(self) -> str:
+        """Get the startup script name.
+
+        :return: startup script name
+        :rtype: str
+        """
+        return self._name
+
+    @property
+    def script(self) -> str:
+        """Get the actual startup script code.
+
+        :return: startup script text
+        :rtype: str
+        """
+        return self._script
+
+
+class StartupScriptsService:
+    """A service for interacting with the startup scripts endpoint."""
+
+    def __init__(self, http_client) -> None:
+        self._http_client = http_client
+
+    def get(self) -> list[StartupScript]:
+        """Get all of the client's startup scripts.
+
+        :return: list of startup script objects
+        :rtype: list[StartupScript]
+        """
+        scripts = self._http_client.get(STARTUP_SCRIPTS_ENDPOINT).json()
+        scripts_objects = [
+            StartupScript(script['id'], script['name'], script['script']) for script in scripts
+        ]
+        return scripts_objects
+
+    def get_by_id(self, id) -> StartupScript:
+        """Get a specific startup script by id.
+
+        :param id: startup script id
+        :type id: str
+        :return: startup script object
+        :rtype: StartupScript
+        """
+        script = self._http_client.get(STARTUP_SCRIPTS_ENDPOINT + f'/{id}').json()[0]
+
+        return StartupScript(script['id'], script['name'], script['script'])
+
+    def delete(self, id_list: list[str]) -> None:
+        """Delete multiple startup scripts by id.
+
+        :param id_list: list of startup scripts ids
+        :type id_list: list[str]
+        """
+        payload = {'scripts': id_list}
+        self._http_client.delete(STARTUP_SCRIPTS_ENDPOINT, json=payload)
+        return
+
+    def delete_by_id(self, id: str) -> None:
+        """Delete a single startup script by id.
+
+        :param id: startup script id
+        :type id: str
+        """
+        self._http_client.delete(STARTUP_SCRIPTS_ENDPOINT + f'/{id}')
+        return
+
+    def create(self, name: str, script: str) -> StartupScript:
+        """Create a new startup script.
+
+        :param name: startup script name
+        :type name: str
+        :param script: startup script value
+        :type script: str
+        :return: the new startup script's id
+        :rtype: str
+        """
+        payload = {'name': name, 'script': script}
+        id = self._http_client.post(STARTUP_SCRIPTS_ENDPOINT, json=payload).text
+        return StartupScript(id, name, script)

verda/verda.py

@@ -0,0 +1,83 @@
+from verda._version import __version__
+from verda.authentication.authentication import AuthenticationService
+from verda.balance.balance import BalanceService
+from verda.constants import Constants
+from verda.containers.containers import ContainersService
+from verda.http_client.http_client import HTTPClient
+from verda.images.images import ImagesService
+from verda.instance_types.instance_types import InstanceTypesService
+from verda.instances.instances import InstancesService
+from verda.locations.locations import LocationsService
+from verda.ssh_keys.ssh_keys import SSHKeysService
+from verda.startup_scripts.startup_scripts import StartupScriptsService
+from verda.volume_types.volume_types import VolumeTypesService
+from verda.volumes.volumes import VolumesService
+
+
+class VerdaClient:
+    """Client for interacting with Verda public API."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        base_url: str = 'https://api.verda.com/v1',
+        inference_key: str | None = None,
+    ) -> None:
+        """Verda client.
+
+        :param client_id: client id
+        :type client_id: str
+        :param client_secret: client secret
+        :type client_secret: str
+        :param base_url: base url for all the endpoints, optional, defaults to "https://api.verda.com/v1"
+        :type base_url: str, optional
+        :param inference_key: inference key, optional
+        :type inference_key: str, optional
+        """
+        # Validate that client_id and client_secret are not empty
+        if not client_id or not client_secret:
+            raise ValueError('client_id and client_secret must be provided')
+
+        # Constants
+        self.constants: Constants = Constants(base_url, __version__)
+        """Constants"""
+
+        # Services
+        self._authentication: AuthenticationService = AuthenticationService(
+            client_id, client_secret, self.constants.base_url
+        )
+        self._http_client: HTTPClient = HTTPClient(self._authentication, self.constants.base_url)
+
+        self.balance: BalanceService = BalanceService(self._http_client)
+        """Balance service. Get client balance"""
+
+        self.images: ImagesService = ImagesService(self._http_client)
+        """Image service"""
+
+        self.instance_types: InstanceTypesService = InstanceTypesService(self._http_client)
+        """Instance type service"""
+
+        self.instances: InstancesService = InstancesService(self._http_client)
+        """Instances service. Deploy, delete, hibernate (etc) instances"""
+
+        self.ssh_keys: SSHKeysService = SSHKeysService(self._http_client)
+        """SSH keys service"""
+
+        self.startup_scripts: StartupScriptsService = StartupScriptsService(self._http_client)
+        """Startup Scripts service"""
+
+        self.volume_types: VolumeTypesService = VolumeTypesService(self._http_client)
+        """Volume type service"""
+
+        self.volumes: VolumesService = VolumesService(self._http_client)
+        """Volume service. Create, attach, detach, get, rename, delete volumes"""
+
+        self.locations: LocationsService = LocationsService(self._http_client)
+        """Locations service. Get locations"""
+
+        self.containers: ContainersService = ContainersService(self._http_client, inference_key)
+        """Containers service. Deploy, manage, and monitor container deployments"""
+
+
+__all__ = ['VerdaClient']

verda/volume_types/volume_types.py

@@ -0,0 +1,66 @@
+VOLUME_TYPES_ENDPOINT = '/volume-types'
+
+
+class VolumeType:
+    """Volume type."""
+
+    def __init__(self, type: str, price_per_month_per_gb: float) -> None:
+        """Initialize a volume type object.
+
+        :param type: volume type name
+        :type type: str
+        :param price_per_month_per_gb: price per month per gb of storage
+        :type price_per_month_per_gb: float
+        """
+        self._type = type
+        self._price_per_month_per_gb = price_per_month_per_gb
+
+    @property
+    def type(self) -> str:
+        """Get the volume type.
+
+        :return: volume type
+        :rtype: str
+        """
+        return self._type
+
+    @property
+    def price_per_month_per_gb(self) -> str:
+        """Get the volume price_per_month_per_gb.
+
+        :return: volume price_per_month_per_gb
+        :rtype: str
+        """
+        return self._price_per_month_per_gb
+
+    def __str__(self) -> str:
+        """Prints the volume type.
+
+        :return: volume type string representation
+        :rtype: str
+        """
+        return f'type: {self._type}\nprice_per_month_per_gb: ${self._price_per_month_per_gb}'
+
+
+class VolumeTypesService:
+    """A service for interacting with the volume-types endpoint."""
+
+    def __init__(self, http_client) -> None:
+        self._http_client = http_client
+
+    def get(self) -> list[VolumeType]:
+        """Get all volume types.
+
+        :return: list of volume type objects
+        :rtype: list[VolumesType]
+        """
+        volume_types = self._http_client.get(VOLUME_TYPES_ENDPOINT).json()
+        volume_type_objects = [
+            VolumeType(
+                type=volume_type['type'],
+                price_per_month_per_gb=volume_type['price']['price_per_month_per_gb'],
+            )
+            for volume_type in volume_types
+        ]
+
+        return volume_type_objects