flwr 1.23.0__py3-none-any.whl → 1.25.0__py3-none-any.whl

flwr/cli/log.py

@@ -18,7 +18,7 @@
 import time
 from logging import DEBUG, ERROR, INFO
 from pathlib import Path
-from typing import Annotated, Any, Optional, cast
+from typing import Annotated, Any, cast
 
 import grpc
 import typer
@@ -39,13 +39,27 @@ from .utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
 
 
 class AllLogsRetrieved(BaseException):
-    """Raised when all logs are retrieved."""
+    """Exception raised when all available logs have been retrieved.
+
+    This exception is used internally to signal that the log stream has reached the end
+    and all logs have been successfully retrieved.
+    """
 
 
 def start_stream(
     run_id: int, channel: grpc.Channel, refresh_period: int = CONN_REFRESH_PERIOD
 ) -> None:
-    """Start log streaming for a given run ID."""
+    """Start log streaming for a given run ID.
+
+    Parameters
+    ----------
+    run_id : int
+        The unique identifier of the run to stream logs from.
+    channel : grpc.Channel
+        The gRPC channel for communication.
+    refresh_period : int (default: CONN_REFRESH_PERIOD)
+        Connection refresh period in seconds.
+    """
     stub = ControlStub(channel)
     after_timestamp = 0.0
     try:
@@ -111,7 +125,17 @@ def stream_logs(
 
 
 def print_logs(run_id: int, channel: grpc.Channel, timeout: int) -> None:
-    """Print logs from the beginning of a run."""
+    """Print logs from the beginning of a run.
+
+    Parameters
+    ----------
+    run_id : int
+        The unique identifier of the run to retrieve logs from.
+    channel : grpc.Channel
+        The gRPC channel for communication.
+    timeout : int
+        Timeout duration in seconds for the log retrieval request.
+    """
     stub = ControlStub(channel)
     req = StreamLogsRequest(run_id=run_id, after_timestamp=0.0)
 
@@ -143,11 +167,11 @@ def log(
         typer.Argument(help="Path of the Flower project to run"),
     ] = Path("."),
     federation: Annotated[
-        Optional[str],
+        str | None,
         typer.Argument(help="Name of the federation to run the app on"),
     ] = None,
     federation_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
@@ -161,11 +185,15 @@ def log(
         ),
     ] = True,
 ) -> None:
-    """Get logs from a Flower project run."""
+    """Get logs from a run.
+
+    Retrieve and display logs from a Flower run. Logs can be streamed in real-time (with
+    --stream) or printed once (with --show).
+    """
     typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
 
     pyproject_path = app / "pyproject.toml" 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
@@ -175,7 +203,7 @@ def log(
     try:
         _log_with_control_api(app, federation, federation_config, run_id, stream)
     except Exception as err:  # pylint: disable=broad-except
-        typer.secho(str(err), fg=typer.colors.RED, bold=True)
+        typer.secho(str(err), fg=typer.colors.RED, bold=True, err=True)
         raise typer.Exit(code=1) from None
 
 
@@ -186,6 +214,21 @@ def _log_with_control_api(
     run_id: int,
     stream: bool,
 ) -> None:
+    """Retrieve logs using the Control API.
+
+    Parameters
+    ----------
+    app : Path
+        Path to the Flower app directory.
+    federation : str
+        Name of the federation.
+    federation_config : dict[str, Any]
+        Federation configuration dictionary.
+    run_id : int
+        The unique identifier of the run to retrieve logs from.
+    stream : bool
+        If True, stream logs continuously; if False, print once.
+    """
     auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
     channel = init_channel(app, federation_config, auth_plugin)
 

flwr/cli/login/login.py

@@ -16,7 +16,7 @@
 
 
 from pathlib import Path
-from typing import Annotated, Optional
+from typing import Annotated
 
 import typer
 
@@ -50,11 +50,11 @@ def login(  # pylint: disable=R0914
         typer.Argument(help="Path of the Flower App to run."),
     ] = Path("."),
     federation: Annotated[
-        Optional[str],
+        str | None,
         typer.Argument(help="Name of the federation to login into."),
     ] = None,
     federation_config_overrides: Annotated[
-        Optional[list[str]],
+        list[str] | None,
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
@@ -65,7 +65,7 @@ def login(  # pylint: disable=R0914
     typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
 
     pyproject_path = app / "pyproject.toml" 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(
@@ -82,6 +82,7 @@ def login(  # pylint: disable=R0914
             "in the federation configuration.",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
     # Check if insecure flag is set to `True`
@@ -92,6 +93,7 @@ def login(  # pylint: disable=R0914
             "`true` in the federation configuration.",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1)
 
@@ -127,6 +129,7 @@ def login(  # pylint: disable=R0914
             f"❌ Login failed: {e.message}",
             fg=typer.colors.RED,
             bold=True,
+            err=True,
         )
         raise typer.Exit(code=1) from None
 

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, cast
+from typing import Annotated, cast
 
 import typer
 from rich.console import Console
@@ -33,21 +32,19 @@ 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 flwr.supercore.utils import humanize_bytes, humanize_duration
 
+from .run_utils import RunRow, format_runs
 from .utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
 
-_RunListType = tuple[int, str, str, str, str, str, str, str, str]
-
 
 def ls(  # pylint: disable=too-many-locals, too-many-branches, R0913, R0917
     ctx: typer.Context,
@@ -56,11 +53,11 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches, R0913, R0917
         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,
@@ -74,7 +71,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",
@@ -94,12 +91,11 @@ 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``.
     """
@@ -115,7 +111,7 @@ 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
@@ -143,7 +139,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()
@@ -157,6 +156,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:
@@ -164,156 +164,237 @@ 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
-        )
+def _get_status_style(status_text: str) -> str:
+    """Determine the display style/color for a status.
 
-        # 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
+    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_black", no_wrap=True
-    )
-    table.add_column(Text("FAB", justify="center"), style="bright_black")
+    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="bright_black")
-    table.add_column(Text("Running At", justify="center"), style="bright_black")
-    table.add_column(Text("Finished At", justify="center"), style="bright_black")
+    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}]",
+            humanize_duration(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]{humanize_duration(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)
+    table.add_row(
+        "Network traffic (inbound)",
+        f"[blue]{humanize_bytes(run.network_traffic_inbound)}[/blue]",
+    )
+    table.add_row(
+        "Network traffic (outbound)",
+        f"[blue]{humanize_bytes(run.network_traffic_outbound)}[/blue]",
+    )
+    table.add_row(
+        "Network Traffic (total)",
+        "[blue]"
+        f"{humanize_bytes(run.network_traffic_inbound + run.network_traffic_outbound)}"
+        "[/blue]",
+    )
+    table.add_row(
+        "Compute Time (ServerApp)",
+        f"[blue]{humanize_duration(run.compute_time_serverapp)}[/blue]",
+    )
+    table.add_row(
+        "Compute Time (ClientApp)",
+        f"[blue]{humanize_duration(run.compute_time_clientapp)}[/blue]",
+    )
+    table.add_row(
+        "Compute Time (total)",
+        "[blue]"
+        f"{humanize_duration(run.compute_time_serverapp + run.compute_time_clientapp)}"
+        "[/blue]",
+    )
+
+    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": f"{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,
+                "network-traffic": {
+                    "inbound-bytes": row.network_traffic_inbound,
+                    "outbound-bytes": row.network_traffic_outbound,
+                    "total-bytes": row.network_traffic_inbound
+                    + row.network_traffic_outbound,
+                },
+                "compute-time": {
+                    "serverapp-seconds": row.compute_time_serverapp,
+                    "clientapp-seconds": row.compute_time_clientapp,
+                    "total-seconds": row.compute_time_serverapp
+                    + row.compute_time_clientapp,
+                },
             }
         )
 
     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)