flwr 1.22.0__py3-none-any.whl → 1.24.0__py3-none-any.whl

flwr/cli/ls.py

@@ -17,9 +17,8 @@
 
 import io
 import json
-from datetime import datetime, timedelta
 from pathlib import Path
-from typing import Annotated, Optional
+from typing import Annotated, cast
 
 import typer
 from rich.console import Console
@@ -33,33 +32,31 @@ from flwr.cli.config_utils import (
     validate_federation_in_project_config,
 )
 from flwr.cli.constant import FEDERATION_CONFIG_HELP_MESSAGE
-from flwr.common.constant import FAB_CONFIG_FILE, CliOutputFormat, SubStatus
-from flwr.common.date import format_timedelta, isoformat8601_utc
+from flwr.common.constant import FAB_CONFIG_FILE, CliOutputFormat, Status, SubStatus
 from flwr.common.logger import print_json_error, redirect_output, restore_output
 from flwr.common.serde import run_from_proto
-from flwr.common.typing import Run
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     ListRunsRequest,
     ListRunsResponse,
 )
 from flwr.proto.control_pb2_grpc import ControlStub
 
-from .utils import flwr_cli_grpc_exc_handler, init_channel, try_obtain_cli_auth_plugin
-
-_RunListType = tuple[int, str, str, str, str, str, str, str, str]
+from .run_utils import RunRow, format_runs
+from .utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
 
 
 def ls(  # pylint: disable=too-many-locals, too-many-branches, R0913, R0917
+    ctx: typer.Context,
     app: Annotated[
         Path,
         typer.Argument(help="Path of the Flower project"),
     ] = Path("."),
     federation: Annotated[
-        Optional[str],
+        str | None,
         typer.Argument(help="Name of the federation"),
     ] = None,
     federation_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
@@ -73,7 +70,7 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches, R0913, R0917
         ),
     ] = False,
     run_id: Annotated[
-        Optional[int],
+        int | None,
         typer.Option(
             "--run-id",
             help="Specific run ID to display",
@@ -93,15 +90,17 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches, R0913, R0917
     The following details are displayed:
 
     - **Run ID:** Unique identifier for the run.
-    - **FAB:** Name of the FAB associated with the run (``{FAB_ID} (v{FAB_VERSION})``).
+    - **Federation:** The federation to which the run belongs.
+    - **App:** The App associated with the run (``<APP_ID>==<APP_VERSION>``).
     - **Status:** Current status of the run (pending, starting, running, finished).
     - **Elapsed:** Time elapsed since the run started (``HH:MM:SS``).
-    - **Created At:** Timestamp when the run was created.
-    - **Running At:** Timestamp when the run started running.
-    - **Finished At:** Timestamp when the run finished.
+    - **Status Changed @:** Timestamp of the most recent status change.
 
     All timestamps follow ISO 8601, UTC and are formatted as ``YYYY-MM-DD HH:MM:SSZ``.
     """
+    # Resolve command used (list or ls)
+    command_name = cast(str, ctx.command.name) if ctx.command else "list"
+
     suppress_output = output_format == CliOutputFormat.JSON
     captured_output = io.StringIO()
     try:
@@ -111,19 +110,19 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches, R0913, R0917
         typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
 
         pyproject_path = app / FAB_CONFIG_FILE if app else None
-        config, errors, warnings = load_and_validate(path=pyproject_path)
+        config, errors, warnings = load_and_validate(pyproject_path, check_module=False)
         config = process_loaded_project_config(config, errors, warnings)
         federation, federation_config = validate_federation_in_project_config(
             federation, config, federation_config_overrides
         )
-        exit_if_no_address(federation_config, "ls")
+        exit_if_no_address(federation_config, command_name)
         channel = None
         try:
             if runs and run_id is not None:
                 raise ValueError(
                     "The options '--runs' and '--run-id' are mutually exclusive."
                 )
-            auth_plugin = try_obtain_cli_auth_plugin(app, federation, federation_config)
+            auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
             channel = init_channel(app, federation_config, auth_plugin)
             stub = ControlStub(channel)
 
@@ -139,7 +138,10 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches, R0913, R0917
             if output_format == CliOutputFormat.JSON:
                 Console().print_json(_to_json(formatted_runs))
             else:
-                Console().print(_to_table(formatted_runs))
+                if run_id is not None:
+                    Console().print(_to_detail_table(formatted_runs[0]))
+                else:
+                    Console().print(_to_table(formatted_runs))
         finally:
             if channel:
                 channel.close()
@@ -153,6 +155,7 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches, R0913, R0917
                 f"{err}",
                 fg=typer.colors.RED,
                 bold=True,
+                err=True,
             )
     finally:
         if suppress_output:
@@ -160,156 +163,197 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches, R0913, R0917
         captured_output.close()
 
 
-def _format_runs(run_dict: dict[int, Run], now_isoformat: str) -> list[_RunListType]:
-    """Format runs to a list."""
-
-    def _format_datetime(dt: Optional[datetime]) -> str:
-        return isoformat8601_utc(dt).replace("T", " ") if dt else "N/A"
-
-    run_list: list[_RunListType] = []
-
-    # Add rows
-    for run in sorted(
-        run_dict.values(), key=lambda x: datetime.fromisoformat(x.pending_at)
-    ):
-        # Combine status and sub-status into a single string
-        if run.status.sub_status == "":
-            status_text = run.status.status
-        else:
-            status_text = f"{run.status.status}:{run.status.sub_status}"
-
-        # Convert isoformat to datetime
-        pending_at = datetime.fromisoformat(run.pending_at) if run.pending_at else None
-        running_at = datetime.fromisoformat(run.running_at) if run.running_at else None
-        finished_at = (
-            datetime.fromisoformat(run.finished_at) if run.finished_at else None
-        )
-
-        # Calculate elapsed time
-        elapsed_time = timedelta()
-        if running_at:
-            if finished_at:
-                end_time = finished_at
-            else:
-                end_time = datetime.fromisoformat(now_isoformat)
-            elapsed_time = end_time - running_at
-
-        run_list.append(
-            (
-                run.run_id,
-                run.fab_id,
-                run.fab_version,
-                run.fab_hash,
-                status_text,
-                format_timedelta(elapsed_time),
-                _format_datetime(pending_at),
-                _format_datetime(running_at),
-                _format_datetime(finished_at),
-            )
-        )
-    return run_list
+def _get_status_style(status_text: str) -> str:
+    """Determine the display style/color for a status.
 
+    Parameters
+    ----------
+    status_text : str
+        The status text to determine color for.
 
-def _to_table(run_list: list[_RunListType]) -> Table:
-    """Format the provided run list to a rich Table."""
+    Returns
+    -------
+    str
+        Color name for rich console styling (e.g., 'green', 'red', 'blue').
+    """
+    status = status_text.lower()
+    sub_status = status_text.rsplit(":", maxsplit=1)[-1]
+
+    if sub_status == SubStatus.COMPLETED:  # finished:completed
+        return "green"
+    if sub_status == SubStatus.FAILED:  # finished:failed
+        return "red"
+    if sub_status == SubStatus.STOPPED:  # finished:stopped
+        return "yellow"
+    if status in (Status.STARTING, Status.RUNNING):  # starting, running
+        return "blue"
+    return "bright_black"  # pending
+
+
+def _to_table(run_list: list[RunRow]) -> Table:
+    """Format the provided run list to a rich Table.
+
+    Parameters
+    ----------
+    run_list : list[RunRow]
+        List of run information to display.
+
+    Returns
+    -------
+    Table
+        Rich Table object with formatted run information.
+    """
     table = Table(header_style="bold cyan", show_lines=True)
 
     # Add columns
-    table.add_column(
-        Text("Run ID", justify="center"), style="bright_white", overflow="fold"
-    )
-    table.add_column(Text("FAB", justify="center"), style="dim white")
+    table.add_column(Text("Run ID", justify="center"), no_wrap=True)
+    table.add_column(Text("Federation", justify="center"))
+    table.add_column(Text("App", justify="center"))
     table.add_column(Text("Status", justify="center"))
     table.add_column(Text("Elapsed", justify="center"), style="blue")
-    table.add_column(Text("Created At", justify="center"), style="dim white")
-    table.add_column(Text("Running At", justify="center"), style="dim white")
-    table.add_column(Text("Finished At", justify="center"), style="dim white")
+    table.add_column(Text("Status Changed @", justify="center"))
 
     for row in run_list:
-        (
-            run_id,
-            fab_id,
-            fab_version,
-            _,
-            status_text,
-            elapsed,
-            created_at,
-            running_at,
-            finished_at,
-        ) = row
-        # Style the status based on its value
-        sub_status = status_text.rsplit(":", maxsplit=1)[-1]
-        if sub_status == SubStatus.COMPLETED:
-            status_style = "green"
-        elif sub_status == SubStatus.FAILED:
-            status_style = "red"
+        status_style = _get_status_style(row.status_text)
+
+        # Use the most recent timestamp
+        if row.finished_at != "N/A":
+            status_changed_at = row.finished_at
+        elif row.running_at != "N/A":
+            status_changed_at = row.running_at
+        elif row.starting_at != "N/A":
+            status_changed_at = row.starting_at
         else:
-            status_style = "yellow"
+            status_changed_at = row.pending_at
 
         formatted_row = (
-            f"[bold]{run_id}[/bold]",
-            f"{fab_id} (v{fab_version})",
-            f"[{status_style}]{status_text}[/{status_style}]",
-            elapsed,
-            created_at,
-            running_at,
-            finished_at,
+            f"[bold]{row.run_id}[/bold]",
+            row.federation,
+            f"@{row.fab_id}=={row.fab_version}",
+            f"[{status_style}]{row.status_text}[/{status_style}]",
+            row.elapsed,
+            status_changed_at,
         )
         table.add_row(*formatted_row)
 
     return table
 
 
-def _to_json(run_list: list[_RunListType]) -> str:
-    """Format run status list to a JSON formatted string."""
+def _to_detail_table(run: RunRow) -> Table:
+    """Format a single run's details in a vertical table layout.
+
+    Parameters
+    ----------
+    run : RunRow
+        The run information to display.
+
+    Returns
+    -------
+    Table
+        Rich Table object with detailed run information in vertical format.
+    """
+    status_style = _get_status_style(run.status_text)
+
+    # Create vertical table with field names on the left
+    table = Table(show_header=False, show_lines=False)
+    table.add_column("Field", style="bold cyan", no_wrap=True)
+    table.add_column("Value")
+
+    # Add rows with all details
+    table.add_row("Run ID", f"[bold]{run.run_id}[/bold]")
+    table.add_row("Federation", run.federation)
+    table.add_row("App", f"@{run.fab_id}=={run.fab_version}")
+    table.add_row("FAB Hash", f"{run.fab_hash[:8]}...{run.fab_hash[-8:]}")
+    table.add_row("Status", f"[{status_style}]{run.status_text}[/{status_style}]")
+    table.add_row("Elapsed", f"[blue]{run.elapsed}[/blue]")
+    table.add_row("Pending At", run.pending_at)
+    table.add_row("Starting At", run.starting_at)
+    table.add_row("Running At", run.running_at)
+    table.add_row("Finished At", run.finished_at)
+
+    return table
+
+
+def _to_json(run_list: list[RunRow]) -> str:
+    """Format run status list to a JSON formatted string.
+
+    Parameters
+    ----------
+    run_list : list[RunRow]
+        List of run information to serialize.
+
+    Returns
+    -------
+    str
+        JSON string containing formatted run information.
+    """
     runs_list = []
     for row in run_list:
-        (
-            run_id,
-            fab_id,
-            fab_version,
-            fab_hash,
-            status_text,
-            elapsed,
-            created_at,
-            running_at,
-            finished_at,
-        ) = row
         runs_list.append(
             {
-                "run-id": run_id,
-                "fab-id": fab_id,
-                "fab-name": fab_id.split("/")[-1],
-                "fab-version": fab_version,
-                "fab-hash": fab_hash[:8],
-                "status": status_text,
-                "elapsed": elapsed,
-                "created-at": created_at,
-                "running-at": running_at,
-                "finished-at": finished_at,
+                "run-id": row.run_id,
+                "federation": row.federation,
+                "fab-id": row.fab_id,
+                "fab-name": row.fab_id.split("/")[-1],
+                "fab-version": row.fab_version,
+                "fab-hash": row.fab_hash[:8],
+                "status": row.status_text,
+                "elapsed": row.elapsed,
+                "pending-at": row.pending_at,
+                "starting-at": row.starting_at,
+                "running-at": row.running_at,
+                "finished-at": row.finished_at,
             }
         )
 
     return json.dumps({"success": True, "runs": runs_list})
 
 
-def _list_runs(stub: ControlStub) -> list[_RunListType]:
-    """List all runs."""
+def _list_runs(stub: ControlStub) -> list[RunRow]:
+    """List all runs.
+
+    Parameters
+    ----------
+    stub : ControlStub
+        The gRPC stub for Control API communication.
+
+    Returns
+    -------
+    list[RunRow]
+        List of formatted run information for all runs.
+    """
     with flwr_cli_grpc_exc_handler():
         res: ListRunsResponse = stub.ListRuns(ListRunsRequest())
-    run_dict = {run_id: run_from_proto(proto) for run_id, proto in res.run_dict.items()}
+    runs = [run_from_proto(proto) for proto in res.run_dict.values()]
+
+    return format_runs(runs, res.now)
 
-    return _format_runs(run_dict, res.now)
 
+def _display_one_run(stub: ControlStub, run_id: int) -> list[RunRow]:
+    """Display information about a specific run.
 
-def _display_one_run(stub: ControlStub, run_id: int) -> list[_RunListType]:
-    """Display information about a specific run."""
+    Parameters
+    ----------
+    stub : ControlStub
+        The gRPC stub for Control API communication.
+    run_id : int
+        The unique identifier of the run to display.
+
+    Returns
+    -------
+    list[RunRow]
+        List containing the formatted run information (single item).
+
+    Raises
+    ------
+    ValueError
+        If the run_id is not found.
+    """
     with flwr_cli_grpc_exc_handler():
         res: ListRunsResponse = stub.ListRuns(ListRunsRequest(run_id=run_id))
     if not res.run_dict:
         # This won't be reached as an gRPC error is raised if run_id is invalid
         raise ValueError(f"Run ID {run_id} not found")
 
-    run_dict = {run_id: run_from_proto(proto) for run_id, proto in res.run_dict.items()}
-
-    return _format_runs(run_dict, res.now)
+    runs = [run_from_proto(proto) for proto in res.run_dict.values()]
+    return format_runs(runs, res.now)

flwr/cli/new/new.py

@@ -15,18 +15,25 @@
 """Flower command line interface `new` command."""
 
 
+import io
 import re
+import zipfile
 from enum import Enum
 from pathlib import Path
 from string import Template
-from typing import Annotated, Optional
+from typing import Annotated
 
+import requests
 import typer
 
+from flwr.supercore.constant import PLATFORM_API_URL
+
 from ..utils import (
     is_valid_project_name,
+    parse_app_spec,
     prompt_options,
     prompt_text,
+    request_download_link,
     sanitize_project_name,
 )
 
@@ -93,24 +100,186 @@ def render_and_create(file_path: Path, template: str, context: dict[str, str]) -
     create_file(file_path, content)
 
 
+def print_success_prompt(
+    package_name: str, llm_challenge_str: str | None = None
+) -> None:
+    """Print styled setup instructions for running a new Flower App after creation."""
+    prompt = typer.style(
+        "🎊 Flower App creation successful.\n\n"
+        "To run your Flower App, first install its dependencies:\n\n",
+        fg=typer.colors.GREEN,
+        bold=True,
+    )
+
+    _add = "	huggingface-cli login\n" if llm_challenge_str else ""
+
+    prompt += typer.style(
+        f"	cd {package_name} && pip install -e .\n" + _add + "\n",
+        fg=typer.colors.BRIGHT_CYAN,
+        bold=True,
+    )
+
+    prompt += typer.style(
+        "then, run the app:\n\n ",
+        fg=typer.colors.GREEN,
+        bold=True,
+    )
+
+    prompt += typer.style(
+        "\tflwr run .\n\n",
+        fg=typer.colors.BRIGHT_CYAN,
+        bold=True,
+    )
+
+    prompt += typer.style(
+        "💡 Check the README in your app directory to learn how to\n"
+        "customize it and how to run it using the Deployment Runtime.\n",
+        fg=typer.colors.GREEN,
+        bold=True,
+    )
+
+    print(prompt)
+
+
+# Security: prevent zip-slip
+def _safe_extract_zip(zf: zipfile.ZipFile, dest_dir: Path) -> None:
+    """Extract ZIP file into destination directory."""
+    dest_dir = dest_dir.resolve()
+
+    def _is_within_directory(base: Path, target: Path) -> bool:
+        try:
+            target.relative_to(base)
+            return True
+        except ValueError:
+            return False
+
+    for member in zf.infolist():
+        # Skip directory placeholders;
+        # ZipInfo can represent them as names ending with '/'.
+        if member.is_dir():
+            target_path = (dest_dir / member.filename).resolve()
+            if not _is_within_directory(dest_dir, target_path):
+                raise ValueError(f"Unsafe path in zip: {member.filename}")
+            target_path.mkdir(parents=True, exist_ok=True)
+            continue
+
+        # Files
+        target_path = (dest_dir / member.filename).resolve()
+        if not _is_within_directory(dest_dir, target_path):
+            raise ValueError(f"Unsafe path in zip: {member.filename}")
+
+        # Ensure parent exists
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Extract
+        with zf.open(member, "r") as src, open(target_path, "wb") as dst:
+            dst.write(src.read())
+
+
+def _download_zip_to_memory(presigned_url: str) -> io.BytesIO:
+    """Download ZIP file from Platform API to memory."""
+    try:
+        r = requests.get(presigned_url, timeout=60)
+        r.raise_for_status()
+    except requests.RequestException as e:
+        typer.secho(
+            f"ZIP download failed: {e}",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1) from e
+
+    buf = io.BytesIO(r.content)
+    # Validate it's a zip
+    if not zipfile.is_zipfile(buf):
+        typer.secho(
+            "Downloaded file is not a valid ZIP",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+    buf.seek(0)
+    return buf
+
+
+def download_remote_app_via_api(app_spec: str) -> None:
+    """Download App from Platform API."""
+    # Validate app version and ID format
+    app_id, app_version = parse_app_spec(app_spec)
+    app_name = app_id.split("/")[1]
+
+    project_dir = Path.cwd() / app_name
+    if project_dir.exists():
+        if not typer.confirm(
+            typer.style(
+                f"\n💬 {app_name} already exists, do you want to override it?",
+                fg=typer.colors.MAGENTA,
+                bold=True,
+            )
+        ):
+            return
+
+    print(
+        typer.style(
+            f"\n🔗 Requesting download link for {app_id}...",
+            fg=typer.colors.GREEN,
+            bold=True,
+        )
+    )
+    # Fetch ZIP downloading URL
+    url = f"{PLATFORM_API_URL}/hub/fetch-zip"
+    presigned_url = request_download_link(app_id, app_version, url, "zip_url")
+
+    print(
+        typer.style(
+            "⬇️  Downloading ZIP into memory...",
+            fg=typer.colors.GREEN,
+            bold=True,
+        )
+    )
+    zip_buf = _download_zip_to_memory(presigned_url)
+
+    print(
+        typer.style(
+            f"📦 Unpacking into {project_dir}...",
+            fg=typer.colors.GREEN,
+            bold=True,
+        )
+    )
+    with zipfile.ZipFile(zip_buf) as zf:
+        _safe_extract_zip(zf, Path.cwd())
+
+    print_success_prompt(app_name)
+
+
 # pylint: disable=too-many-locals,too-many-branches,too-many-statements
 def new(
     app_name: Annotated[
-        Optional[str],
-        typer.Argument(help="The name of the Flower App"),
+        str | None,
+        typer.Argument(
+            help="Flower app name. For remote apps, use the format "
+            "'@account_name/app_name' or '@account_name/app_name==x.y.z'. "
+            "Version is optional (defaults to latest)."
+        ),
     ] = None,
     framework: Annotated[
-        Optional[MlFramework],
+        MlFramework | None,
         typer.Option(case_sensitive=False, help="The ML framework to use"),
     ] = None,
     username: Annotated[
-        Optional[str],
+        str | None,
         typer.Option(case_sensitive=False, help="The Flower username of the author"),
     ] = None,
 ) -> None:
     """Create new Flower App."""
     if app_name is None:
         app_name = prompt_text("Please provide the app name")
+
+    # Download remote app
+    if app_name and app_name.startswith("@"):
+        download_remote_app_via_api(app_name)
+        return
+
     if not is_valid_project_name(app_name):
         app_name = prompt_text(
             "Please provide a name that only contains "
@@ -282,38 +451,4 @@ def new(
             context=context,
         )
 
-    prompt = typer.style(
-        "🎊 Flower App creation successful.\n\n"
-        "To run your Flower App, first install its dependencies:\n\n",
-        fg=typer.colors.GREEN,
-        bold=True,
-    )
-
-    _add = "	huggingface-cli login\n" if llm_challenge_str else ""
-
-    prompt += typer.style(
-        f"	cd {package_name} && pip install -e .\n" + _add + "\n",
-        fg=typer.colors.BRIGHT_CYAN,
-        bold=True,
-    )
-
-    prompt += typer.style(
-        "then, run the app:\n\n ",
-        fg=typer.colors.GREEN,
-        bold=True,
-    )
-
-    prompt += typer.style(
-        "\tflwr run .\n\n",
-        fg=typer.colors.BRIGHT_CYAN,
-        bold=True,
-    )
-
-    prompt += typer.style(
-        "💡 Check the README in your app directory to learn how to\n"
-        "customize it and how to run it using the Deployment Runtime.\n",
-        fg=typer.colors.GREEN,
-        bold=True,
-    )
-
-    print(prompt)
+    print_success_prompt(package_name, llm_challenge_str)