lightning-sdk 2026.1.22__py3-none-any.whl → 2026.1.30__py3-none-any.whl

lightning_sdk/cli/cp/teamspace_uploads.py

@@ -0,0 +1,95 @@
+import os
+from pathlib import Path
+
+from rich.console import Console
+
+from lightning_sdk.api.utils import _get_cloud_url
+from lightning_sdk.cli.utils.filesystem import parse_teamspace_uploads_path, path_join, resolve_teamspace
+
+
+def cp_upload(
+    local_file_path: str,
+    teamspace_path: str,
+    options: dict[str, any],
+) -> None:
+    console = Console()
+    recursive = options.get("recursive", False)
+    cloud_account = options.get("cloud_account", None)
+    if not Path(local_file_path).exists():
+        raise FileNotFoundError(f"The provided path does not exist: {local_file_path}")
+
+    teamspace_path_result = parse_teamspace_uploads_path(teamspace_path)
+
+    teamspace_path_result["destination"] = path_join("Uploads", teamspace_path_result["destination"])
+
+    selected_teamspace = resolve_teamspace(teamspace_path_result["teamspace"], teamspace_path_result["owner"])
+    console.print(f"Uploading to {selected_teamspace.owner.name}/{selected_teamspace.name}")
+
+    if Path(local_file_path).is_dir():
+        if not recursive:
+            raise ValueError(f"'{local_file_path}' is a directory. Use -r flag to copy directories recursively.")
+        selected_teamspace.upload_folder(
+            local_file_path, teamspace_path_result["destination"], cloud_account=cloud_account
+        )
+    else:
+        if teamspace_path.endswith(("/", "\\")):
+            # if destination ends with / or \, treat it as a directory
+            file_name = os.path.basename(local_file_path)
+            teamspace_path_result["destination"] = path_join(teamspace_path_result["destination"], file_name)
+        selected_teamspace.upload_file(
+            local_file_path, teamspace_path_result["destination"], cloud_account=cloud_account
+        )
+
+    studio_url = (
+        _get_cloud_url().replace(":443", "") + "/" + selected_teamspace.owner.name + "/" + selected_teamspace.name
+    )
+    console.print(f"See your file at {studio_url}")
+
+
+def cp_download(
+    teamspace_path: str,
+    local_path: str,
+    options: dict[str, any],
+) -> None:
+    console = Console()
+    teamspace_path_result = parse_teamspace_uploads_path(teamspace_path)
+    recursive = options.get("recursive", False)
+
+    selected_teamspace = resolve_teamspace(teamspace_path_result["teamspace"], teamspace_path_result["owner"])
+
+    # check if file/folder exists
+    path_info = selected_teamspace._teamspace_api.get_path_info(
+        selected_teamspace._teamspace.id, path=teamspace_path_result["destination"]
+    )
+    if not path_info["exists"]:
+        raise FileNotFoundError(
+            f"The provided path does not exist in the teamspace drive: {teamspace_path_result['destination']} "
+            "Note that empty folders may not be detected as existing."
+        )
+
+    console.print(f"Downloading from {selected_teamspace.owner.name}/{selected_teamspace.name}")
+    if path_info["type"] == "directory":
+        if not recursive:
+            raise ValueError(
+                f"'{teamspace_path_result['destination']}' is a directory. Use -r flag to copy directories recursively."
+            )
+        folder_name = os.path.basename(teamspace_path_result["destination"].rstrip("/"))
+        if local_path in ("./", "."):
+            if folder_name == "":
+                folder_name = f"{selected_teamspace.name}_downloads"
+            target_path = os.path.join(local_path, folder_name)
+        else:
+            target_path = local_path
+
+        selected_teamspace.download_folder(teamspace_path_result["destination"], target_path)
+        console.print(f"See your folder at {target_path}")
+    else:
+        if os.path.isdir(local_path) or local_path.endswith(("/", "\\")):
+            # if local_path ends with / or \ or is a directory, treat it as a directory
+            file_name = os.path.basename(teamspace_path_result["destination"])
+            target_path = os.path.join(local_path, file_name)
+        else:
+            target_path = local_path
+        os.makedirs(os.path.dirname(target_path), exist_ok=True)
+        selected_teamspace.download_file(teamspace_path_result["destination"], target_path)
+        console.print(f"See your file at {target_path}")

lightning_sdk/cli/legacy/download.py

@@ -12,6 +12,7 @@ from lightning_sdk.api.lit_container_api import LitContainerApi
 from lightning_sdk.cli.legacy.exceptions import StudioCliError
 from lightning_sdk.cli.legacy.studios_menu import _StudiosMenu
 from lightning_sdk.cli.utils.teamspace_selection import TeamspacesMenu
+from lightning_sdk.exceptions import DeprecatedCommand, DeprecatedError
 from lightning_sdk.models import download_model
 from lightning_sdk.studio import Studio
 from lightning_sdk.utils.resolve import _get_authed_user
@@ -63,134 +64,64 @@ def model(name: str, download_dir: str = ".") -> None:
     )
 
 
-@download.command(name="folder")
-@click.argument("path")
+@download.command(
+    name="folder",
+    cls=DeprecatedCommand,
+    message="Studio downloads via 'lightning download folder' are deprecated. Use 'lightning studio cp -r' instead.",
+)
+@click.argument("path", required=False, nargs=-1)
 @click.option(
     "--studio",
     default=None,
-    help=(
-        "The name of the studio to download from. "
-        "Will show a menu with user's owned studios for selection if not specified. "
-        "If provided, should be in the form of <TEAMSPACE-NAME>/<STUDIO-NAME> where the names are case-sensitive. "
-        "The teamspace and studio names can be regular expressions to match, "
-        "a menu filtered studios will be shown for final selection."
-    ),
+    hidden=True,
 )
 @click.option(
     "--teamspace",
     default=None,
-    help="The teamspace the drive folder is part of. Should be of format <OWNER>/<TEAMSPACE_NAME>.",
+    hidden=True,
 )
 @click.option(
     "--local-path",
     "--local_path",
-    default=".",
-    type=click.Path(file_okay=False, dir_okay=True),
-    help="The path to the directory you want to download the folder to.",
+    default=None,
+    hidden=True,
 )
 def folder(
     path: str = "", studio: Optional[str] = None, teamspace: Optional[str] = None, local_path: str = "."
 ) -> None:
-    """Download a folder from a Studio or a Teamspace drive folder.
-
-    Example:
-      lightning download folder PATH
-
-    PATH: The relative path within the Studio or drive folder you want to download.
-    Defaults to the entire Studio or drive folder.
-    """
-    local_path = Path(local_path)
-    if not local_path.is_dir():
-        raise NotADirectoryError(f"'{local_path}' is not a directory")
-
-    if studio and teamspace:
-        raise ValueError("Either --studio or --teamspace must be provided, not both")
-
-    if studio:
-        path = _expand_remote_path(path)
-        resolved_downloader = _resolve_studio(studio)
-    elif teamspace:
-        menu = TeamspacesMenu()
-        resolved_downloader = menu(teamspace)
-    else:
-        raise ValueError("Either --studio or --teamspace must be provided")
-
-    if not path:
-        local_path /= resolved_downloader.name
-        path = ""
-
-    try:
-        if not path and teamspace:
-            raise FileNotFoundError()
-        resolved_downloader.download_folder(remote_path=path, target_path=str(local_path))
-    except Exception as e:
-        raise StudioCliError(
-            f"Could not download the folder from the given Studio {studio} or Teamspace {teamspace}. "
-            "Please contact Lightning AI directly to resolve this issue."
-        ) from e
+    """[DEPRECATED] Use 'lightning studio cp -r' instead."""
+    raise DeprecatedError(
+        "Studio downloads via 'lightning download folder' are deprecated. Use 'lightning studio cp -r' instead."
+    )
 
 
-@download.command(name="file")
-@click.argument("path")
+@download.command(
+    name="file",
+    cls=DeprecatedCommand,
+    message="Studio downloads via 'lightning download file' are deprecated. Use 'lightning studio cp' instead.",
+)
+@click.argument("path", required=False, nargs=-1)
 @click.option(
     "--studio",
     default=None,
-    help=(
-        "The name of the studio to download from. "
-        "Will show a menu with user's owned studios for selection if not specified. "
-        "If provided, should be in the form of <TEAMSPACE-NAME>/<STUDIO-NAME> where the names are case-sensitive. "
-        "The teamspace and studio names can be regular expressions to match, "
-        "a menu filtered studios will be shown for final selection."
-    ),
+    hidden=True,
 )
 @click.option(
     "--teamspace",
     default=None,
-    help="The teamspace the file is part of. Should be of format <OWNER>/<TEAMSPACE_NAME>.",
+    hidden=True,
 )
 @click.option(
     "--local-path",
     "--local_path",
-    default=".",
-    type=click.Path(file_okay=False, dir_okay=True),
-    help="The path to the directory you want to download the file to.",
+    default=None,
+    hidden=True,
 )
 def file(path: str = "", studio: Optional[str] = None, teamspace: Optional[str] = None, local_path: str = ".") -> None:
-    """Download a file from a Studio or Teamspace drive file.
-
-    Example:
-      lightning download file PATH
-
-    PATH: The relative path to the file within the Studio or Teamspace drive file you want to download.
-    """
-    local_path = Path(local_path)
-    if not local_path.is_dir():
-        raise NotADirectoryError(f"'{local_path}' is not a directory")
-
-    if studio and teamspace:
-        raise ValueError("Either --studio or --teamspace must be provided, not both")
-
-    if studio:
-        resolved_downloader = _resolve_studio(studio)
-    elif teamspace:
-        menu = TeamspacesMenu()
-        resolved_downloader = menu(teamspace)
-    else:
-        raise ValueError("Either --studio or --teamspace must be provided")
-
-    if not path:
-        local_path /= resolved_downloader.name
-        path = ""
-
-    try:
-        if not path:
-            raise FileNotFoundError()
-        resolved_downloader.download_file(remote_path=path, file_path=str(local_path / os.path.basename(path)))
-    except Exception as e:
-        raise StudioCliError(
-            f"Could not download the file from the given Studio {studio} or Teamspace {teamspace}. "
-            "Please contact Lightning AI directly to resolve this issue."
-        ) from e
+    """[DEPRECATED] Use 'lightning studio cp' instead."""
+    raise DeprecatedError(
+        "Studio downloads via 'lightning download file' are deprecated. Use 'lightning studio cp' instead."
+    )
 
 
 @download.command(name="container")

lightning_sdk/cli/legacy/upload.py

@@ -18,6 +18,7 @@ from lightning_sdk.cli.legacy.exceptions import StudioCliError
 from lightning_sdk.cli.legacy.studios_menu import _StudiosMenu
 from lightning_sdk.cli.utils.teamspace_selection import TeamspacesMenu
 from lightning_sdk.constants import _LIGHTNING_DEBUG
+from lightning_sdk.exceptions import DeprecatedCommand, DeprecatedError
 from lightning_sdk.models import upload_model as _upload_model
 from lightning_sdk.studio import Studio
 from lightning_sdk.utils.resolve import _get_authed_user
@@ -54,56 +55,48 @@ def model(name: str, path: str = ".", cloud_account: Optional[str] = None) -> No
     _upload_model(name, path, cloud_account=cloud_account)
 
 
-@upload.command("folder")
-@click.argument("path", type=click.Path(exists=True))
-@click.option(
-    "--studio",
-    default=None,
-    help=(
-        "The name of the studio to upload to. "
-        "Will show a menu for selection if not specified. "
-        "If provided, should be in the form of <TEAMSPACE-NAME>/<STUDIO-NAME>"
-    ),
+@upload.command(
+    name="folder",
+    cls=DeprecatedCommand,
+    message="Studio uploads via 'lightning upload folder' are deprecated. Use 'lightning studio cp -r' instead.",
 )
+@click.argument("path", type=click.Path(), required=False, nargs=-1)
+@click.option("--studio", default=None, hidden=True)
 @click.option(
     "--remote-path",
     "--remote_path",
     default=None,
-    help=(
-        "The path where the uploaded file should appear on your Studio. "
-        "Has to be within your Studio's home directory and will be relative to that. "
-        "If not specified, will use the name of the folder you want to upload and place it in your home directory."
-    ),
+    hidden=True,
 )
 def folder(path: str, studio: Optional[str], remote_path: Optional[str]) -> None:
-    """Upload a folder to a Studio."""
-    _folder(path=path, studio=studio, remote_path=remote_path)
+    """[DEPRECATED] Use 'lightning studio cp -r' instead."""
+    raise DeprecatedError(
+        "Studio uploads via 'lightning upload folder' are deprecated. Use 'lightning studio cp -r' instead."
+    )
 
 
-@upload.command("file")
-@click.argument("path", type=click.Path(exists=True))
+@upload.command(
+    name="file",
+    cls=DeprecatedCommand,
+    message="Studio uploads via 'lightning upload file' are deprecated. Use 'lightning studio cp' instead.",
+)
+@click.argument("path", type=click.Path(), required=False, nargs=-1)
 @click.option(
     "--studio",
     default=None,
-    help=(
-        "The name of the studio to upload to. "
-        "Will show a menu for selection if not specified. "
-        "If provided, should be in the form of <TEAMSPACE-NAME>/<STUDIO-NAME>"
-    ),
+    hidden=True,
 )
 @click.option(
     "--remote-path",
     "--remote_path",
     default=None,
-    help=(
-        "The path where the uploaded file should appear on your Studio. "
-        "Has to be within your Studio's home directory and will be relative to that. "
-        "If not specified, will use the name of the file you want to upload and place it in your home directory."
-    ),
+    hidden=True,
 )
 def file(path: str, studio: Optional[str] = None, remote_path: Optional[str] = None) -> None:
-    """Upload a file to a Studio."""
-    _file(path=path, studio=studio, remote_path=remote_path)
+    """[DEPRECATED] Use 'lightning studio cp' instead."""
+    raise DeprecatedError(
+        "Studio uploads via 'lightning upload file' are deprecated. Use 'lightning studio cp' instead."
+    )
 
 
 @upload.command("container")

lightning_sdk/cli/studio/cp.py

@@ -8,7 +8,7 @@ import click
 from rich.console import Console
 
 from lightning_sdk.api.utils import _get_cloud_url
-from lightning_sdk.cli.utils.studio_filesystem import parse_studio_path, resolve_studio
+from lightning_sdk.cli.utils.filesystem import parse_studio_path, resolve_studio
 
 
 @click.command("cp")
@@ -111,10 +111,13 @@ def cp_download(
                 f"'{studio_path_result['destination']}' is a directory. Use -r flag to copy directories recursively."
             )
         folder_name = os.path.basename(studio_path_result["destination"].rstrip("/"))
-        if folder_name == "" and local_path in ("./", "."):
-            # handle root directory case (e.g. lit://lightning-ai/gpt-oss/studios/manual-lime-ylu2/)
-            folder_name = selected_studio.name
-        target_path = os.path.join(local_path, folder_name)
+        if local_path in ("./", "."):
+            if folder_name == "":
+                # handle root directory case (e.g. lit://lightning-ai/gpt-oss/studios/manual-lime-ylu2/)
+                folder_name = selected_studio.name
+            target_path = os.path.join(local_path, folder_name)
+        else:
+            target_path = local_path
 
         selected_studio.download_folder(studio_path_result["destination"], target_path)
         console.print(f"See your folder at {target_path}")

lightning_sdk/cli/studio/ls.py

@@ -2,7 +2,7 @@
 
 import click
 
-from lightning_sdk.cli.utils.studio_filesystem import parse_studio_path, resolve_studio
+from lightning_sdk.cli.utils.filesystem import parse_studio_path, resolve_studio
 
 
 @click.command("ls")

lightning_sdk/cli/studio/rm.py

@@ -3,7 +3,7 @@
 import click
 from rich.console import Console
 
-from lightning_sdk.cli.utils.studio_filesystem import parse_studio_path, resolve_studio
+from lightning_sdk.cli.utils.filesystem import parse_studio_path, resolve_studio
 from lightning_sdk.studio import Studio
 
 

lightning_sdk/cli/utils/{studio_filesystem.py → filesystem.py}

@@ -1,24 +1,30 @@
-from typing import Optional, TypedDict
+import os
+from typing import Any, Optional, TypedDict
 
 from lightning_sdk.cli.utils.owner_selection import OwnerMenu
 from lightning_sdk.cli.utils.studio_selection import StudiosMenu
 from lightning_sdk.cli.utils.teamspace_selection import TeamspacesMenu
 from lightning_sdk.studio import Studio
+from lightning_sdk.teamspace import Teamspace
 
 
-class StudioPathResult(TypedDict):
+class PathResult(TypedDict):
     owner: Optional[str]
     teamspace: Optional[str]
     studio: Optional[str]
     destination: Optional[str]
 
 
-def parse_studio_path(studio_path: str) -> StudioPathResult:
+def path_join(*args: Any) -> str:
+    return os.path.join(*args).replace("\\", "/")
+
+
+def parse_studio_path(studio_path: str) -> PathResult:
     path_string = studio_path.removeprefix("lit://")
     if not path_string:
         raise ValueError("Studio path cannot be empty after prefix")
 
-    result: StudioPathResult = {"owner": None, "teamspace": None, "studio": None, "destination": None}
+    result: PathResult = {"owner": None, "teamspace": None, "studio": None, "destination": None}
 
     if "/studios/" in path_string:
         prefix_part, suffix_part = path_string.split("/studios/", 1)
@@ -54,12 +60,49 @@ def parse_studio_path(studio_path: str) -> StudioPathResult:
     return result
 
 
-def resolve_studio(studio_name: Optional[str], teamspace: Optional[str], owner: Optional[str]) -> Studio:
+def parse_teamspace_uploads_path(teamspace_path: str) -> PathResult:
+    path_string = teamspace_path.removeprefix("lit://")
+    if not path_string:
+        raise ValueError("Teamspace path cannot be empty after prefix")
+
+    result: PathResult = {"owner": None, "teamspace": None, "studio": None, "destination": None}
+
+    if "/uploads/" in path_string:
+        prefix_part, suffix_part = path_string.split("/uploads/", 1)
+
+        # org and teamspace
+        if prefix_part:
+            org_ts_components = prefix_part.split("/")
+            if len(org_ts_components) == 2:
+                result["owner"], result["teamspace"] = org_ts_components
+            elif len(org_ts_components) == 1:
+                result["teamspace"] = org_ts_components[0]
+            else:
+                raise ValueError(f"Invalid format: '{prefix_part}'")
+
+        # studio and destination
+        path_parts = suffix_part.split("/")
+
+    else:
+        raise ValueError("Invalid teamspace uploads path: missing '/uploads/' segment")
+
+    if not path_parts:
+        raise ValueError("Invalid: Missing teamspace name.")
+
+    result["destination"] = suffix_part
+
+    return result
+
+
+def resolve_teamspace(teamspace: Optional[str], owner: Optional[str]) -> Teamspace:
     owner_menu = OwnerMenu()
     resolved_owner = owner_menu(owner=owner)
 
     teamspace_menu = TeamspacesMenu(resolved_owner)
-    resolved_teamspace = teamspace_menu(teamspace=teamspace)
+    return teamspace_menu(teamspace=teamspace)
+
 
+def resolve_studio(studio_name: Optional[str], teamspace: Optional[str], owner: Optional[str]) -> Studio:
+    resolved_teamspace = resolve_teamspace(teamspace, owner)
     studio_menu = StudiosMenu(resolved_teamspace)
     return studio_menu(studio=studio_name)

lightning_sdk/exceptions.py

@@ -1,6 +1,33 @@
+from typing import Any
+
+import click
+
+
 class OutOfCapacityError(RuntimeError):
     """Raised when the requested machine is not available in the selected cloud account."""
 
 
 class NotSupportedError(RuntimeError):
     """Raised when the requested machine is not supported in the selected cloud account."""
+
+
+class DeprecatedError(RuntimeError):
+    """Raised when a deprecated feature is used."""
+
+
+class DeprecatedCommand(click.Command):
+    """Custom exception for deprecated commands."""
+
+    def __init__(self, *args: Any, message: str, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.deprecated_message = message
+
+    def get_help(self, ctx: click.Context) -> str:
+        if self.deprecated_message:
+            raise DeprecatedError(self.deprecated_message)
+        return super().get_help(ctx)
+
+    def invoke(self, ctx: click.Context) -> Any:
+        if self.deprecated_message:
+            raise DeprecatedError(self.deprecated_message)
+        return super().invoke(ctx)