lightning-sdk 2025.11.13.post0__py3-none-any.whl

lightning_sdk/user.py

@@ -0,0 +1,60 @@
+from typing import Dict, Optional
+
+from lightning_sdk.api import UserApi
+from lightning_sdk.owner import Owner
+from lightning_sdk.utils.resolve import _resolve_user_name
+
+
+class User(Owner):
+    """Represents a user owner of teamspaces and studios.
+
+    Args:
+        name: the name of the user
+
+    Note:
+        Arguments will be automatically inferred from environment variables if possible,
+        unless explicitly specified
+
+    """
+
+    def __init__(self, name: Optional[str] = None) -> None:
+        super().__init__()
+        self._user_api = UserApi()
+
+        name = _resolve_user_name(name)
+        if name is None:
+            raise ValueError("Neither name is provided nor can the user be inferred from the environment variable!")
+
+        self._user = self._user_api.get_user(name=name)
+
+    @property
+    def name(self) -> str:
+        """The user's name."""
+        return self._user.username
+
+    @property
+    def id(self) -> str:
+        """The user's ID."""
+        return self._user.id
+
+    @property
+    def secrets(self) -> Dict[str, str]:
+        """All (encrypted) secrets for the user.
+
+        Note:
+            Once created, the secret values are encrypted and cannot be viewed here anymore.
+        """
+        return self._user_api.get_secrets()
+
+    def set_secret(self, key: str, value: str) -> None:
+        """Set a (encrypted) secret for the user."""
+        if not self._user_api.verify_secret_name(key):
+            raise ValueError(
+                "Secret keys must only contain alphanumeric characters and underscores and not begin with a number."
+            )
+
+        self._user_api.set_secret(key, value)
+
+    def __repr__(self) -> str:
+        """Returns reader friendly representation."""
+        return f"User(name={self.name})"

lightning_sdk/utils/config.py

@@ -0,0 +1,179 @@
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional, Sequence
+
+import yaml
+
+_DEFAULT_CONFIG_FILE_PATH = "~/.lightning/config.yaml"
+
+
+@dataclass(frozen=True)
+class DefaultConfigKeys:
+    """Default configuration keys for the Lightning SDK."""
+
+    organization: str = "organization.name"
+    user: str = "user.name"
+
+    teamspace_name: str = "teamspace.name"
+    teamspace_owner: str = "teamspace.owner"
+    teamspace_owner_type: str = "teamspace.owner_type"
+
+    machine: str = "machine.name"
+
+    studio: str = "studio.name"
+
+    cloud_account: str = "cloud_account.name"
+    cloud_provider: str = "cloud_provider.name"
+
+    license: str = "license"
+
+
+class ConfigProxy:
+    def __init__(self, root: "Config", *path: str) -> None:
+        self._root = root
+        self._path = path  # list of keys from root
+
+    def __getattr__(self, name: str) -> "ConfigProxy":
+        """Returns a reference to a nested ConfigProxy object a level deeper in the config hierarchy.
+
+        Args:
+            name: the name of the attribute to access, which corresponds to a key in the config.
+
+        Returns:
+            ConfigProxy: the next ConfigProxy object for the attribute.
+        """
+        # Build a deeper path and return a new proxy
+        return ConfigProxy(self._root, *self._path, name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Sets the name attribute to value at the current hierarchy level.
+
+        Args:
+            name: the attribute name to set, which corresponds to a key in the config.
+            value: the value to set for the given attribute name in the config.
+        """
+        if name in ("_root", "_path"):  # internal attributes
+            super().__setattr__(name, value)
+        else:
+            # Assign a nested value in the root config
+            self._root._set_nested([*self._path, name], value)
+
+
+class Config:
+    def __init__(self, config_file: Optional[str] = None) -> None:
+        """Config class to manage configuration settings for the lightning SDK and CLI.
+
+        Args:
+            config_file: the file path where the configuration is stored.
+            If None, defaults to "~/.lightning/config.yaml".
+        """
+        if config_file is None:
+            config_file = _DEFAULT_CONFIG_FILE_PATH
+        self._config_file = os.path.expanduser(config_file)
+
+    def _load_config(self) -> Dict[str, Any]:
+        if not os.path.exists(self._config_file):
+            return {}  # Return empty dict if config doesn't exist
+        with open(self._config_file) as f:
+            return yaml.safe_load(f) or {}
+
+    def _save_config(self, config: Dict[str, Any]) -> None:
+        os.makedirs(os.path.dirname(self._config_file), exist_ok=True)
+        config = _unflatten_dict(config)
+        with open(self._config_file, "w") as f:
+            yaml.safe_dump(config, f, default_flow_style=False, sort_keys=True)
+
+    def _set_nested(self, keys: Sequence[str], value: str) -> None:
+        config = self._load_config()
+        curr = config
+        for k in keys[:-1]:
+            if k not in curr or not isinstance(curr[k], Dict):
+                curr[k] = {}
+            curr = curr[k]
+        curr[keys[-1]] = value
+        self._save_config(config)
+
+    def get_value(self, key_path: str) -> Optional[str]:
+        """Gets a value from the config using dot notation.
+
+        Args:
+            key_path: the dot-separated path to the config value (e.g. "teamspace.name")
+
+        Returns:
+            The config value if found, None otherwise
+        """
+        return self._get_value_type(key_path, str)
+
+    def get_sub_config(self, key_path: str) -> Optional[Mapping[str, Any]]:
+        """Gets a subconfig from the config using dot notation.
+
+        Args:
+            key_path: the dot-separated path to the subconfig (e.g. "license")
+
+        Returns:
+            The subconfig if found, None otherwise
+        """
+        return self._get_value_type(key_path, Mapping)
+
+    def _get_value_type(self, key_path: str, subtype: type) -> Optional[Any]:
+        config = self._load_config()
+        if not isinstance(config, Mapping):
+            return None
+
+        keys = key_path.split(".")
+        curr = config
+        for k in keys:
+            if not isinstance(curr, dict) or k not in curr:
+                return None
+            curr = curr[k]
+        return curr if isinstance(curr, subtype) else None
+
+    def __getattr__(self, name: str) -> ConfigProxy:
+        """Returns a proxy to the actual values to allow for nested access.
+
+        Args:
+            name: the name of the value to retrieve.
+
+        Returns:
+            ConfigProxy: a proxy object that allows nested access to the configuration.
+        """
+        return ConfigProxy(self, name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Sets the name attribute to value at the root level."""
+        if name in ("_config_file",):  # internal attributes
+            super().__setattr__(name, value)
+        else:
+            # Assign a value at the root level
+            self._set_nested([name], value)
+
+    def __repr__(self) -> str:
+        """Returns a string representation of the config."""
+        return str(self)
+
+    def __str__(self) -> str:
+        """Returns a string representation of the config."""
+        return yaml.dump(
+            {"Config": {"config_file": self._config_file, **self._load_config()}},
+            indent=4,
+            sort_keys=True,
+        )
+
+    def get(self, key: str) -> Optional[str]:
+        return self.get_value(key)
+
+    def set(self, key: str, value: str) -> None:
+        self._set_nested([key], value)
+
+
+def _unflatten_dict(flat_dict: Dict[str, Any]) -> Dict[str, Any]:
+    unflattened_dict = {}
+    for key, value in flat_dict.items():
+        keys = key.split(".")
+        curr = unflattened_dict
+        for k in keys[:-1]:
+            if k not in curr:
+                curr[k] = {}
+            curr = curr[k]
+        curr[keys[-1]] = value
+    return unflattened_dict

lightning_sdk/utils/dynamic.py

@@ -0,0 +1,61 @@
+from abc import ABCMeta
+from typing import Any, Callable, Tuple, Type
+
+
+class ConditionBaseMeta(ABCMeta):
+    """Metaclass that allows for conditional inheritance.
+
+    This metaclass is used to conditionally inherit from two base classes
+    based on the result of a given condition function.
+
+    Example usage:
+    ```
+    def my_condition():
+        return some_condition  # Define your condition here
+
+    class A:
+        pass
+
+    class B:
+        pass
+
+    class MyNewClass(metaclass=ConditionBaseMeta, condition_func=my_condition, base_true=A, base_false=B):
+        pass
+    ```
+
+    Args:
+        cls: The metaclass itself.
+        name: The name of the class being created.
+        bases: The base classes of the class being created.
+        attrs: The attributes of the class being created.
+        condition_func: The function that determines which base class to inherit from.
+        base_true: The base class to inherit from if the condition function returns True.
+        base_false: The base class to inherit from if the condition function returns False.
+
+    Returns:
+        type: The new class with the appropriate base class.
+    """
+
+    def __new__(
+        cls,
+        name: str,
+        bases: Tuple[type, ...],
+        attrs: dict,
+        condition_func: Callable[[], bool],
+        base_true: Type,
+        base_false: Type,
+    ) -> Type:
+        # Helper function to determine the base class
+        def get_base() -> type:
+            return base_true if condition_func() else base_false
+
+        base = get_base()
+        attrs["_base"] = base
+
+        # Create the final class, inheriting from both the intermediate base and the original bases
+        return super().__new__(cls, name, (base, *bases), attrs)
+
+    def __getattr__(cls, name: str) -> Any:
+        """Get an attribute from the appropriate base class."""
+        # Delegate attribute lookup to the appropriate base class
+        return getattr(cls._base, name)

lightning_sdk/utils/enum.py

@@ -0,0 +1,116 @@
+from enum import Enum, EnumMeta, unique
+from types import MappingProxyType
+from typing import Any, Dict, Iterator, Union
+
+
+# We silence annotation errors as the function signatures are exactly the same in python core enum.py
+# modified from https://stackoverflow.com/a/62309159
+class OnAccess(EnumMeta):
+    """Runs a user-specified function whenever member is accessed."""
+
+    def __getattribute__(cls, name: str) -> Any:  # noqa: N805
+        """Called when an attribute is accessed."""
+        obj = super().__getattribute__(name)
+        if isinstance(obj, Enum) and obj._on_access:
+            obj._on_access()
+        return _resolve_deprecated_enum_fields(obj)
+
+    def __getitem__(cls, name: str) -> Any:  # noqa: N805
+        """Called when an item is accessed."""
+        member = super().__getitem__(name)
+        if isinstance(member, Enum) and member._on_access:
+            member._on_access()
+
+        return _resolve_deprecated_enum_fields(member)
+
+    def __call__(
+        cls,  # noqa: N805
+        value,  # noqa: ANN001
+        names=None,  # noqa: ANN001
+        *,
+        module=None,  # noqa: ANN001
+        qualname=None,  # noqa: ANN001
+        type=None,  # noqa: A002, ANN001
+        start=1,  # noqa: ANN001
+    ) -> Any:
+        obj = super().__call__(value, names, module=module, qualname=qualname, type=type, start=start)
+        if isinstance(obj, Enum) and obj._on_access:
+            obj._on_access()
+        return _resolve_deprecated_enum_fields(obj)
+
+    @staticmethod
+    def _filter_func(member: "DeprecationEnum") -> bool:
+        return not member.deprecated
+
+    def __iter__(cls) -> Iterator["DeprecationEnum"]:  # noqa: N805
+        """Returns members in definition order.
+
+        Excludes deprecated members
+
+        """
+        return filter(cls._filter_func, (cls._member_map_[name] for name in cls._member_names_))
+
+    def __len__(cls) -> int:  # noqa: N805
+        """Length of the enum excluding deprecated members."""
+        return len(cls.__members__)
+
+    @property
+    def __members__(cls) -> Dict[str, "DeprecationEnum"]:  # noqa: N805
+        """Returns a mapping of member name->value.
+
+        This mapping lists all enum members, including aliases. Note that this is a read-only view of the internal
+        mapping.
+
+        Excludes deprecated members.
+
+        """
+        return MappingProxyType(
+            {name: member for name, member in cls._member_map_.items() if not cls._filter_func(member)}
+        )
+
+    def __reversed__(cls) -> Iterator["DeprecationEnum"]:  # noqa: N805
+        """Returns members in reverse definition order.
+
+        Excludes deprecated members
+
+        """
+        return filter(cls._filter_func, (cls._member_map_[name] for name in reversed(cls._member_names_)))
+
+
+def _resolve_deprecated_enum_fields(value: Union[Any, "DeprecationEnum"]) -> Union[Any, "DeprecationEnum"]:
+    """Resolves deprecated enum fields to their preferred values."""
+    if getattr(value, "deprecated", False):
+        return value.__class__[value.preferred_way]
+    return value
+
+
+# NOTE: even deprecated enums need to have unique values.
+# otherwise the deprecation warning will not be triggered
+# as duplicated values are handled as aliases towards the original value
+# and the original value is not accessed. However, _resolve_deprecated_enum_fields
+# will handle this case and return the preferred value
+@unique
+class DeprecationEnum(Enum, metaclass=OnAccess):
+    def __new__(cls, value, *args) -> Any:  # noqa: ANN001, ANN002
+        member = object.__new__(cls)
+        member._value_ = value
+        member.deprecated = False
+        member._on_access = None
+
+        if args:
+            member.preferred_way = args[0]
+            member._on_access = member.deprecate
+            member.deprecated = True
+
+        return member
+
+    def deprecate(self) -> None:
+        import warnings
+
+        clsname = self.__class__.__name__
+
+        warnings.warn(
+            f"{clsname}.{self.name} is deprecated. Use {clsname}.{self.preferred_way} instead!",
+            DeprecationWarning,
+            stacklevel=3,
+        )

lightning_sdk/utils/license.py

@@ -0,0 +1,13 @@
+from functools import lru_cache
+
+from lightning_sdk.api.license_api import LicenseApi
+
+
+class License:
+    def __init__(self, license_key: str, product_name: str) -> None:
+        self.license_key = license_key
+        self.product_name = product_name
+
+    @lru_cache(maxsize=1)  # noqa: B019
+    def validate(self) -> bool:
+        return LicenseApi(self.license_key).validate_license(self.license_key, self.product_name)

lightning_sdk/utils/logging.py

@@ -0,0 +1,79 @@
+import functools
+import inspect
+import time
+import traceback
+from abc import ABCMeta
+from contextlib import suppress
+from typing import Callable, Dict, Tuple
+
+from lightning_sdk.__version__ import __version__
+from lightning_sdk.lightning_cloud.openapi import V1CreateSDKCommandHistoryRequest, V1SDKCommandHistorySeverity
+from lightning_sdk.lightning_cloud.openapi.models.v1_sdk_command_history_type import V1SDKCommandHistoryType
+from lightning_sdk.lightning_cloud.rest_client import LightningClient
+
+
+def track_calls() -> Callable[..., any]:
+    def decorator(func: Callable[..., any]) -> Callable[..., any]:
+        @functools.wraps(func)
+        def wrapper(*args: Tuple[any, ...], **kwargs: Dict[str, any]) -> any:
+            start_time = time.time()
+            sig = inspect.signature(func)
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+
+            args_str = ", ".join(f"{k}: {v}" for k, v in bound_args.arguments.items() if k != "self")
+            message = f"VERSION: {__version__} | ARGS: {args_str} "
+
+            body = V1CreateSDKCommandHistoryRequest(
+                command=func.__qualname__,
+                message=message,
+                project_id=None,
+                severity=V1SDKCommandHistorySeverity.INFO,
+                type=V1SDKCommandHistoryType.SDK,
+            )
+
+            try:
+                return func(*args, **kwargs)
+
+            except Exception as e:
+                body.severity = V1SDKCommandHistorySeverity.ERROR
+                body.message += f" | Error: {type(e).__name__}: {e!s} | Traceback: {traceback.format_exc(limit=3)}"
+                body.duration = int(time.time() - start_time)
+                with suppress(Exception):
+                    client = LightningClient(retry=False, max_tries=0)
+                    client.s_dk_command_history_service_create_sdk_command_history(body=body)
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+class TrackCallsMeta(type):
+    def __new__(cls, name: any, bases: any, attrs: any) -> type.__new__:
+        for attr_name, attr_value in attrs.items():
+            if attr_name.startswith("__") and attr_name not in ("__init__", "__call__"):
+                attrs[attr_name] = attr_value
+                continue
+
+            # Noisy
+            if attr_name in ("_cls_name"):
+                attrs[attr_name] = attr_value
+                continue
+
+            if callable(attr_value):
+                attrs[attr_name] = track_calls()(attr_value)
+
+            elif isinstance(attr_value, property):
+                fget = track_calls()(attr_value.fget) if attr_value.fget else None
+                fset = track_calls()(attr_value.fset) if attr_value.fset else None
+                fdel = track_calls()(attr_value.fdel) if attr_value.fdel else None
+                attrs[attr_name] = property(fget, fset, fdel)
+
+            else:
+                attrs[attr_name] = attr_value
+        return super().__new__(cls, name, bases, attrs)
+
+
+class TrackCallsABCMeta(ABCMeta, TrackCallsMeta):
+    """Combined metaclass for classes that need both ABC and TrackCalls functionality."""