lightning-sdk 0.1.49__py3-none-any.whl → 2025.11.5__py3-none-any.whl

lightning_sdk/deployment/deployment.py

@@ -1,10 +1,12 @@
 import os
+from datetime import datetime
 from typing import Any, Dict, List, Optional, Union
 
 import requests
 
 from lightning_sdk.api import UserApi
 from lightning_sdk.api.deployment_api import (
+    ApiKeyAuth,
     Auth,
     AutoScaleConfig,
     BasicAuth,
@@ -15,6 +17,7 @@ from lightning_sdk.api.deployment_api import (
     ReleaseStrategy,
     Secret,
     TokenAuth,
+    compose_commands,
     restore_auth,
     restore_autoscale,
     restore_env,
@@ -30,19 +33,21 @@ from lightning_sdk.lightning_cloud.openapi import V1Deployment
 from lightning_sdk.machine import Machine
 from lightning_sdk.organization import Organization
 from lightning_sdk.services.utilities import _get_cluster
+from lightning_sdk.studio import Studio
 from lightning_sdk.teamspace import Teamspace
 from lightning_sdk.user import User
+from lightning_sdk.utils.logging import TrackCallsMeta
 from lightning_sdk.utils.resolve import _resolve_deprecated_cluster, _resolve_org, _resolve_teamspace, _resolve_user
 
 
-class Deployment:
+class Deployment(metaclass=TrackCallsMeta):
     """The Lightning AI Deployment.
 
     Allows to fully control a deployment, including retrieving the status, making new release
     and switching machine types, etc..
 
     Args:
-        name: The name of the deployment.
+        name: The name or the id of the deployment.
         teamspace: The teamspace in which you want to deploy.
         org: The name of the organization owning the :param`teamspace` in case it is owned by an org
         user: The name of the user owning the :param`teamspace` in case it is owned directly by a user instead of an org
@@ -55,7 +60,7 @@ class Deployment:
 
     def __init__(
         self,
-        name: str,  # Only the name is required in case a deployment already exist.
+        name: Optional[str] = None,
         teamspace: Optional[Union[str, Teamspace]] = None,
         org: Optional[Union[str, Organization]] = None,
         user: Optional[Union[str, User]] = None,
@@ -63,6 +68,7 @@ class Deployment:
         self._request_session = None
 
         self._auth = login.Auth()
+        self._user = None
 
         try:
             self._auth.authenticate()
@@ -71,11 +77,17 @@ class Deployment:
         except ConnectionError as e:
             raise e
 
+        if name is None:
+            name = "dep_" + datetime.now().strftime("%m-%d_%H:%M:%S")
+
         self._name = name
+        self._user = _resolve_user(self._user or user)
         self._org = _resolve_org(org)
-        self._user = _resolve_user(user)
+
         self._teamspace = _resolve_teamspace(
-            teamspace=teamspace, org=self._org, user=self._user if self._org is None else None
+            teamspace=teamspace,
+            org=org,
+            user=user,
         )
         if self._teamspace is None:
             raise ValueError("You need to pass a teamspace or an org for your deployment.")
@@ -83,28 +95,45 @@ class Deployment:
         self._deployment_api = DeploymentApi()
         self._cloud_account = _get_cluster(client=self._deployment_api._client, project_id=self._teamspace.id)
         self._is_created = False
-        deployment = self._deployment_api.get_deployment_by_name(name, self._teamspace.id)
+
+        if name.startswith("dep_"):
+            deployment = self._deployment_api.get_deployment_by_id(name, self._teamspace.id)
+        else:
+            deployment = self._deployment_api.get_deployment_by_name(name, self._teamspace.id)
+
         if deployment:
+            self._name = deployment.name
             self._is_created = True
             self._deployment = deployment
+        else:
+            self._deployment = None
 
     def start(
         self,
+        studio: Optional[Union[str, Studio]] = None,
         machine: Optional[Machine] = None,
-        environment: Optional[str] = None,
+        image: Optional[str] = None,
         autoscale: Optional[AutoScaleConfig] = None,
-        ports: Optional[List[float]] = None,
+        ports: Optional[Union[float, List[float]]] = None,
         release_strategy: Optional[ReleaseStrategy] = None,
         entrypoint: Optional[str] = None,
         command: Optional[str] = None,
-        env: Optional[List[Union[Env, Secret]]] = None,
+        commands: Optional[List[str]] = None,
+        env: Union[List[Union[Secret, Env]], Dict[str, str], None] = None,
         spot: Optional[bool] = None,
         replicas: Optional[int] = None,
         health_check: Optional[Union[HttpHealthCheck, ExecHealthCheck]] = None,
-        auth: Optional[Union[BasicAuth, TokenAuth]] = None,
+        auth: Optional[Union[BasicAuth, TokenAuth, ApiKeyAuth]] = None,
         cloud_account: Optional[str] = None,
         custom_domain: Optional[str] = None,
         cluster: Optional[str] = None,  # deprecated in favor of cloud_account
+        cloudspace_id: Optional[str] = None,
+        quantity: Optional[int] = None,
+        include_credentials: Optional[bool] = None,
+        from_onboarding: Optional[bool] = None,
+        from_litserve: Optional[bool] = None,
+        max_runtime: Optional[int] = None,
+        path_mappings: Optional[Dict[str, str]] = None,
     ) -> None:
         """The Lightning AI Deployment.
 
@@ -116,7 +145,7 @@ class Deployment:
             machine: The machine used by the deployment replicas.
             autoscale: The list of the metrics to autoscale on.
             ports: The ports to reach your replica services.
-            environment: The environement used by the deployment. Currentely, only docker images.
+            image: The environement used by the deployment. Currentely, only docker images.
             release_strategy: The release strategy to use when changing core deployment specs.
             entrypoint: The docker container entrypoint.
             command: The docker container command.
@@ -127,7 +156,24 @@ class Deployment:
             auth: The auth config to protect your services. Only Basic and Token supported.
             cloud_account: The name of the cloud account, the studio should be created on.
                 Doesn't matter when the studio already exists.
-            custom_domain: Whether your service would be referenced under a custom doamin.
+            custom_domain: Whether your service would be referenced under a custom domain.
+            cloudspace_id: Connect deployment to a Studio.
+            quantity: The number of machines per replica to deploy.
+            include_credentials: Whether to include the environment variables for the SDK to authenticate
+            from_onboarding: Whether the deployment is from onboarding.
+            max_runtime: the duration (in seconds) for which to allocate the machine.
+                Irrelevant for most machines, required for some of the top-end machines on GCP.
+                If in doubt, set it. Won't have an effect on machines not requiring it.
+                Defaults to 3h
+            path_mappings: Dictionary of path mappings. The keys are the path inside the container whereas the value
+                represents the data-connection name and the path inside that connection.
+                Should be of form
+                    {
+                        "<CONTAINER_PATH_1>": "<CONNECTION_NAME_1>:<PATH_WITHIN_CONNECTION_1>",
+                        "<CONTAINER_PATH_2>": "<CONNECTION_NAME_2>"
+                    }
+                If the path inside the connection is omitted it's assumed to be the root path of that connection.
+                Only applicable when deploying docker containers.
 
         Note:
             Since a teamspace can either be owned by an org or by a user directly,
@@ -137,12 +183,51 @@ class Deployment:
         if self._is_created:
             raise RuntimeError("This deployment has already been started.")
 
-        cloud_account = _resolve_deprecated_cluster(cloud_account, cluster)
+        machine_image_version = None
+
+        if isinstance(studio, Studio):
+            cloudspace_id = studio._studio.id
+            cloud_account = studio._studio.cluster_id
+            machine_image_version = studio._studio.machine_image_version
+
+        if isinstance(studio, str):
+            studio = Studio(studio)
+            cloudspace_id = studio._studio.id
+            cloud_account = studio._studio.cluster_id
+            machine_image_version = studio._studio.machine_image_version
+
+        if cloud_account is None:
+            cloud_account = _resolve_deprecated_cluster(cloud_account, cluster)
 
         if cloud_account is None and self._cloud_account is not None:
             print(f"No cloud account was provided, defaulting to {self._cloud_account.cluster_id}")
             cloud_account = os.getenv("LIGHTNING_CLUSTER_ID") or self._cloud_account.cluster_id
 
+        if isinstance(ports, float):
+            ports = [ports]
+
+        if replicas is None and autoscale is None:
+            replicas = 1
+
+        if machine is None:
+            machine = Machine.CPU
+
+        if commands is not None and command is not None:
+            raise ValueError("Commands and command are mutually exclusive")
+
+        if commands is not None:
+            command = compose_commands(commands)
+
+        autoscaling_metric_name = ("CPU" if machine.is_cpu() else "GPU") if isinstance(machine, Machine) else "CPU"
+
+        if autoscale is None:
+            autoscale = AutoScaleConfig(
+                min_replicas=0,
+                max_replicas=1,
+                metric=autoscaling_metric_name,
+                threshold=90,
+            )
+
         self._deployment = self._deployment_api.create_deployment(
             V1Deployment(
                 autoscaling=to_autoscaling(autoscale, replicas),
@@ -150,28 +235,41 @@ class Deployment:
                 name=self._name,
                 project_id=self._teamspace.id,
                 replicas=replicas,
+                cloudspace_id=cloudspace_id,
                 spec=to_spec(
                     cloud_account=cloud_account,
                     command=command,
                     entrypoint=entrypoint,
                     env=env,
-                    environment=environment,
+                    image=image,
                     spot=spot,
                     machine=machine,
                     health_check=health_check,
+                    quantity=quantity,
+                    include_credentials=include_credentials if include_credentials is not None else True,
+                    cloudspace_id=cloudspace_id,
+                    max_runtime=max_runtime,
+                    machine_image_version=machine_image_version,
+                    path_mappings=path_mappings,
                 ),
                 strategy=to_strategy(release_strategy),
-            )
+            ),
+            from_onboarding=from_onboarding,
+            from_litserve=from_litserve,
         )
+
+        # Overrides the name
+        self._name = self._deployment._name
         self._is_created = True
 
     def update(
         self,
         # Changing those arguments create a new release
         machine: Optional[Machine] = None,
-        environment: Optional[str] = None,
+        image: Optional[str] = None,
         entrypoint: Optional[str] = None,
         command: Optional[str] = None,
+        commands: Optional[List[str]] = None,
         env: Optional[List[Union[Env, Secret]]] = None,
         spot: Optional[bool] = None,
         cloud_account: Optional[str] = None,
@@ -186,9 +284,16 @@ class Deployment:
         auth: Optional[Union[BasicAuth, TokenAuth]] = None,
         custom_domain: Optional[str] = None,
         cluster: Optional[str] = None,  # deprecated in favor of cloud_account
+        quantity: Optional[int] = None,
+        include_credentials: Optional[bool] = None,
+        max_runtime: Optional[int] = None,
+        path_mappings: Optional[Dict[str, str]] = None,
     ) -> None:
         cloud_account = _resolve_deprecated_cluster(cloud_account, cluster)
 
+        if command is None and commands is not None:
+            command = compose_commands(commands)
+
         self._deployment = self._deployment_api.update_deployment(
             self._deployment,
             name=name or self._name,
@@ -198,7 +303,7 @@ class Deployment:
             max_replicas=max_replicas,
             cloud_account=cloud_account,
             machine=machine,
-            environment=environment,
+            image=image,
             entrypoint=entrypoint,
             command=command,
             ports=ports,
@@ -207,12 +312,23 @@ class Deployment:
             env=env,
             health_check=health_check,
             release_strategy=release_strategy,
+            quantity=quantity,
+            include_credentials=include_credentials,
+            max_runtime=max_runtime,
+            path_mappings=path_mappings,
         )
 
     def stop(self) -> None:
         """All the deployment replicas will be stopped and all their traffic blocked."""
         self._deployment = self._deployment_api.stop(self._deployment)
 
+    @property
+    def name(self) -> Optional[str]:
+        if self._deployment:
+            self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
+            self._name = self._deployment.name
+        return self._name
+
     @property
     def replicas(self) -> Optional[int]:
         """The default number of replicas the release starts with."""
@@ -226,7 +342,7 @@ class Deployment:
         """The minimum number of replicas."""
         if self._deployment:
             self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
-            return self._deployment.autoscaling.min_replicas
+            return int(self._deployment.autoscaling.min_replicas)
         return None
 
     @property
@@ -234,7 +350,7 @@ class Deployment:
         """The maximum number of replicas."""
         if self._deployment:
             self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
-            return self._deployment.autoscaling.max_replicas
+            return int(self._deployment.autoscaling.max_replicas)
         return None
 
     @property
@@ -254,7 +370,7 @@ class Deployment:
         return None
 
     @property
-    def readiness_probe(self) -> Optional[Union[HttpHealthCheck, ExecHealthCheck]]:
+    def health_check(self) -> Optional[Union[HttpHealthCheck, ExecHealthCheck]]:
         """The health check to validate the replicas are ready to receive traffic."""
         if self._deployment:
             self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
@@ -278,7 +394,7 @@ class Deployment:
         return None
 
     @property
-    def env(self) -> Optional[AutoScaleConfig]:
+    def env(self) -> Optional[List[Union[Secret, Env]]]:
         """The env configuration of the deployment."""
         if self._deployment:
             self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
@@ -294,27 +410,35 @@ class Deployment:
         return None
 
     @property
-    def pending_replicas(self) -> Optional[List[str]]:
+    def pending_replicas(self) -> Optional[int]:
         """The number of pending replicas."""
         if self._deployment:
             self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
-            return self._deployment.status.pending_replicas
+            return int(self._deployment.status.pending_replicas)
         return None
 
     @property
-    def failing_replicas(self) -> Optional[List[str]]:
+    def running_replicas(self) -> Optional[int]:
         """The number of failing replicas."""
         if self._deployment:
             self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
-            return self._deployment.status.failing_replicas
+            return int(self._deployment.status.ready_replicas)
         return None
 
     @property
-    def deleting_replicas(self) -> Optional[List[str]]:
+    def failing_replicas(self) -> Optional[int]:
+        """The number of failing replicas."""
+        if self._deployment:
+            self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
+            return int(self._deployment.status.failing_replicas)
+        return None
+
+    @property
+    def deleting_replicas(self) -> Optional[int]:
         """The number of deleting replicas."""
         if self._deployment:
             self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
-            return self._deployment.status.deleting_replicas
+            return int(self._deployment.status.deleting_replicas)
         return None
 
     @property
@@ -325,9 +449,37 @@ class Deployment:
             return self._deployment.spec.cluster_id
         return None
 
+    @property
+    def release_id(self) -> Optional[str]:
+        """The release id of the deployment."""
+        if self._deployment:
+            self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
+            return self._deployment.release_id
+        return None
+
+    @property
+    def quantity(self) -> Optional[str]:
+        """The number of machines per replica."""
+        if self._deployment:
+            self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
+            return self._deployment.spec.quantity
+        return None
+
+    @property
+    def include_credentials(self) -> Optional[bool]:
+        """The number of machines per replica."""
+        if self._deployment:
+            self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
+            return self._deployment.spec.include_credentials
+        return None
+
+    @property
+    def org(self) -> Optional[Organization]:
+        return self._org
+
     @property
     def user(self) -> Optional[User]:
-        """The teamspace of the deployment."""
+        """The user of the deployment."""
         return self._user
 
     @property
@@ -339,6 +491,34 @@ class Deployment:
     def is_started(self) -> bool:
         return self._is_created
 
+    @property
+    def is_stopped(self) -> Optional[bool]:
+        if self._deployment:
+            self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
+            return self._deployment.autoscaling.max_replicas == 0
+        return None
+
+    @property
+    def image(self) -> Optional[str]:
+        if self._deployment:
+            self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
+            return self._deployment.spec.image
+        return None
+
+    @property
+    def entrypoint(self) -> Optional[str]:
+        if self._deployment:
+            self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
+            return self._deployment.spec.entrypoint
+        return None
+
+    @property
+    def command(self) -> Optional[str]:
+        if self._deployment:
+            self._deployment = self._deployment_api.get_deployment_by_name(self._name, self._teamspace.id)
+            return self._deployment.spec.command
+        return None
+
     @property
     def _session(self) -> Any:
         if self._request_session is None:

lightning_sdk/helpers.py

@@ -1,49 +1,88 @@
-import functools
+import importlib
+import os
+import sys
 import warnings
 from typing import Optional
 
 import requests
+import tqdm
+import tqdm.std
 from packaging import version as packaging_version
 
-__package_name__ = "lightning-sdk"
+from lightning_sdk.constants import _LIGHTNING_DISABLE_VERSION_CHECK
 
 
-@functools.lru_cache(maxsize=1)
-def _get_newer_version(curr_version: str) -> Optional[str]:
-    """Check PyPI for newer versions of ``lightning-sdk``.
-
-    Returning the newest version if different from the current or ``None`` otherwise.
+class VersionChecker:
+    """Handles version checking and upgrade prompts for lightning-sdk.
 
+    This class ensures that version check warnings are only shown once per session,
+    preventing duplicate warnings in multithreaded scenarios.
     """
-    if packaging_version.parse(curr_version).is_prerelease:
-        return None
-    try:
-        response = requests.get(f"https://pypi.org/pypi/{__package_name__}/json")
-        response_json = response.json()
-        releases = response_json["releases"]
-        if curr_version not in releases:
-            # Always return None if not installed from PyPI (e.g. dev versions)
+
+    def __init__(self, package_name: str = "lightning-sdk") -> None:
+        self.package_name = package_name
+        self._warning_shown = False
+        self._cached_version: Optional[str] = None
+
+    def _get_newer_version(self, curr_version: str) -> Optional[str]:
+        """Check PyPI for newer versions of ``lightning-sdk``.
+
+        Returning the newest version if different from the current or ``None`` otherwise.
+        """
+        if self._cached_version is not None:
+            return self._cached_version
+
+        if _LIGHTNING_DISABLE_VERSION_CHECK == 1 or packaging_version.parse(curr_version).is_prerelease:
+            self._cached_version = None
             return None
-        latest_version = response_json["info"]["version"]
-        parsed_version = packaging_version.parse(latest_version)
-        is_invalid = response_json["info"]["yanked"] or parsed_version.is_devrelease or parsed_version.is_prerelease
-        return None if curr_version == latest_version or is_invalid else latest_version
-    except requests.exceptions.RequestException:
-        return None
 
+        try:
+            response = requests.get(f"https://pypi.org/pypi/{self.package_name}/json")
+            response_json = response.json()
+            releases = response_json["releases"]
+            if curr_version not in releases:
+                # Always return None if not installed from PyPI (e.g. dev versions)
+                self._cached_version = None
+                return None
+            latest_version = response_json["info"]["version"]
+            parsed_version = packaging_version.parse(latest_version)
+            is_invalid = response_json["info"]["yanked"] or parsed_version.is_devrelease or parsed_version.is_prerelease
+            self._cached_version = None if curr_version == latest_version or is_invalid else latest_version
+            return self._cached_version
+        except requests.exceptions.RequestException:
+            self._cached_version = None
+            return None
 
-def _check_version_and_prompt_upgrade(curr_version: str) -> None:
-    """Checks that the current version of ``lightning-sdk`` is the latest on PyPI.
+    def check_and_prompt_upgrade(self, curr_version: str) -> None:
+        """Checks that the current version of ``lightning-sdk`` is the latest on PyPI.
 
-    If not, warn the user to upgrade ``lightning-sdk``.
+        If not, warn the user to upgrade ``lightning-sdk``.
+        Tracks if the warning has already been shown in this session to avoid duplicate warnings.
+        """
+        if self._warning_shown:
+            return
 
-    """
-    new_version = _get_newer_version(curr_version)
-    if new_version:
-        warnings.warn(
-            f"A newer version of {__package_name__} is available ({new_version}). "
-            f"Please consider upgrading with `pip install -U {__package_name__}`. "
-            "Not all functionalities of the platform can be guaranteed to work with the current version.",
-            UserWarning,
-        )
-    return
+        new_version = self._get_newer_version(curr_version)
+        if new_version:
+            warnings.warn(
+                f"A newer version of {self.package_name} is available ({new_version}). "
+                f"Please consider upgrading with `pip install -U {self.package_name}`. "
+                "Not all platform functionality can be guaranteed to work with the current version.",
+                UserWarning,
+            )
+            self._warning_shown = True
+
+
+def set_tqdm_envvars_noninteractive() -> None:
+    # note: stderr is the default stream tqdm writes progressbars to
+    # so we check that one.
+    if os.isatty(sys.stderr.fileno()):
+        os.unsetenv("TQDM_POSITION")
+        os.unsetenv("TQDM_MININTERVAL")
+    else:
+        # makes use of https://github.com/tqdm/tqdm/blob/master/tqdm/utils.py#L34 to set defaults
+        os.environ.update({"TQDM_POSITION": "-1", "TQDM_MININTERVAL": "1"})
+
+    # reload to make sure env vars are parsed again
+    importlib.reload(tqdm.std)
+    importlib.reload(tqdm)