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

flwr/cli/run/run.py

@@ -16,23 +16,23 @@
 
 
 import hashlib
-import io
 import json
 import subprocess
 from pathlib import Path
-from typing import Annotated, Any, cast
+from typing import Annotated, Any
 
+import click
 import typer
-from rich.console import Console
 
 from flwr.cli.build import build_fab_from_disk, get_fab_filename
-from flwr.cli.config_utils import load as load_toml
-from flwr.cli.config_utils import (
-    load_and_validate,
-    process_loaded_project_config,
-    validate_federation_in_project_config,
-)
+from flwr.cli.config_migration import migrate, warn_if_federation_config_overrides
+from flwr.cli.config_utils import load_and_validate
 from flwr.cli.constant import FEDERATION_CONFIG_HELP_MESSAGE, RUN_CONFIG_HELP_MESSAGE
+from flwr.cli.flower_config import (
+    _serialize_simulation_options,
+    read_superlink_connection,
+)
+from flwr.cli.typing import SuperLinkConnection, SuperLinkSimulationOptions
 from flwr.common.config import (
     flatten_dict,
     get_metadata_from_config,
@@ -40,19 +40,18 @@ from flwr.common.config import (
     user_config_to_configrecord,
 )
 from flwr.common.constant import FAB_CONFIG_FILE, CliOutputFormat
-from flwr.common.logger import print_json_error, redirect_output, restore_output
 from flwr.common.serde import config_record_to_proto, fab_to_proto, user_config_to_proto
 from flwr.common.typing import Fab
 from flwr.proto.control_pb2 import StartRunRequest  # pylint: disable=E0611
 from flwr.proto.control_pb2_grpc import ControlStub
-from flwr.supercore.constant import NOOP_FEDERATION
+from flwr.supercore.utils import check_federation_format, parse_app_spec
 
 from ..log import start_stream
 from ..utils import (
+    cli_output_handler,
     flwr_cli_grpc_exc_handler,
-    init_channel,
-    load_cli_auth_plugin,
-    parse_app_spec,
+    init_channel_from_connection,
+    print_json_to_stdout,
 )
 
 CONN_REFRESH_PERIOD = 60  # Connection refresh period for log streaming (seconds)
@@ -64,9 +63,17 @@ def run(
         Path,
         typer.Argument(help="Path of the Flower App to run."),
     ] = Path("."),
+    superlink: Annotated[
+        str | None,
+        typer.Argument(help="Name of the SuperLink connection."),
+    ] = None,
     federation: Annotated[
         str | None,
-        typer.Argument(help="Name of the federation to run the app on."),
+        typer.Option(
+            "--federation",
+            help="The federation to submit the run to; must be in the "
+            "format `@<account>/<federation>`.",
+        ),
     ] = None,
     run_config_overrides: Annotated[
         list[str] | None,
@@ -81,6 +88,7 @@ def run(
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
+            hidden=True,
         ),
     ] = None,
     stream: Annotated[
@@ -101,88 +109,87 @@ def run(
     ] = CliOutputFormat.DEFAULT,
 ) -> None:
     """Run Flower App."""
-    suppress_output = output_format == CliOutputFormat.JSON
-    captured_output = io.StringIO()
-    try:
-        if suppress_output:
-            redirect_output(captured_output)
+    with cli_output_handler(output_format=output_format) as is_json:
+        # Warn `--federation-config` is ignored
+        warn_if_federation_config_overrides(federation_config_overrides)
+
+        # Migrate legacy usage if any
+        migrate(str(app), [], ignore_legacy_usage=True)
+
+        # Read superlink connection configuration
+        superlink_connection = read_superlink_connection(superlink)
 
         # Determine if app is remote
         app_spec = None
+        config: dict[str, Any] = {}
         if (app_str := str(app)).startswith("@"):
             # Validate app version and ID format
-            _ = parse_app_spec(app_str)
-            app_spec = app_str
-        is_remote_app = app_spec is not None
+            try:
+                _ = parse_app_spec(app_str)
+            except ValueError as e:
+                raise click.ClickException(str(e)) from e
 
-        typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
-
-        # Disable the validation for remote apps
-        pyproject_path = app / "pyproject.toml" if not is_remote_app else None
-        # `./pyproject.toml` will be loaded when `pyproject_path` is None
-        config, errors, warnings = load_and_validate(
-            pyproject_path, check_module=not is_remote_app
-        )
-        config = process_loaded_project_config(config, errors, warnings)
+            app_spec = app_str
 
-        federation, federation_config = validate_federation_in_project_config(
-            federation, config, federation_config_overrides
-        )
+        # Validate TOML configuration for local app
+        else:
+            app = app.expanduser().resolve()  # Resolve path to absolute
+            config, warnings = load_and_validate(app / FAB_CONFIG_FILE)
+            if warnings:
+                typer.secho(
+                    f"Flower App configuration warnings in '{app / FAB_CONFIG_FILE}':\n"
+                    + "\n".join([f"- {line}" for line in warnings]),
+                    fg=typer.colors.YELLOW,
+                    bold=True,
+                )
 
-        if "address" in federation_config:
+        if superlink_connection.address:
             _run_with_control_api(
                 app,
+                config,
                 federation,
-                federation_config,
+                superlink_connection,
                 run_config_overrides,
                 stream,
-                output_format,
+                is_json,
                 app_spec,
             )
         else:
             _run_without_control_api(
-                app, federation_config, run_config_overrides, federation
-            )
-    except (typer.Exit, Exception) as err:  # pylint: disable=broad-except
-        if suppress_output:
-            restore_output()
-            e_message = captured_output.getvalue()
-            print_json_error(e_message, err)
-        else:
-            typer.secho(
-                f"{err}",
-                fg=typer.colors.RED,
-                bold=True,
-                err=True,
+                app=app,
+                simulation_options=superlink_connection.options,  # type: ignore
+                config_overrides=run_config_overrides,
             )
-    finally:
-        if suppress_output:
-            restore_output()
-        captured_output.close()
 
 
 # pylint: disable-next=R0913, R0914, R0917
 def _run_with_control_api(
     app: Path,
-    federation: str,
-    federation_config: dict[str, Any],
+    config: dict[str, Any],
+    federation: str | None,
+    superlink_connection: SuperLinkConnection,
     config_overrides: list[str] | None,
     stream: bool,
-    output_format: str,
+    is_json: bool,
     app_spec: str | None,
 ) -> None:
     channel = None
     is_remote_app = app_spec is not None
+
+    # Determine federation to use
+    if federation:  # Override federation from CLI
+        check_federation_format(federation)
+    else:  # Use federation from SuperLink connection if set
+        federation = superlink_connection.federation or ""
+
     try:
-        auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
-        channel = init_channel(app, federation_config, auth_plugin)
+        channel = init_channel_from_connection(superlink_connection)
         stub = ControlStub(channel)
 
         # Build FAB if local app
         if not is_remote_app:
             fab_bytes = build_fab_from_disk(app)
             fab_hash = hashlib.sha256(fab_bytes).hexdigest()
-            config = cast(dict[str, Any], load_toml(app / FAB_CONFIG_FILE))
             fab_id, fab_version = get_metadata_from_config(config)
             fab = Fab(fab_hash, fab_bytes, {})
         # Skip FAB build if remote app
@@ -191,16 +198,19 @@ def _run_with_control_api(
             fab_id = fab_version = fab_hash = ""
             fab = Fab(fab_hash, b"", {})
 
-        real_federation: str = federation_config.get("federation", NOOP_FEDERATION)
-
         # Construct a `ConfigRecord` out of a flattened `UserConfig`
-        fed_config = flatten_dict(federation_config.get("options", {}))
-        c_record = user_config_to_configrecord(fed_config)
+        options = {}
+        if superlink_connection.options:
+            options = flatten_dict(
+                _serialize_simulation_options(superlink_connection.options)
+            )
+
+        c_record = user_config_to_configrecord(options)
 
         req = StartRunRequest(
             fab=fab_to_proto(fab),
             override_config=user_config_to_proto(parse_config_args(config_overrides)),
-            federation=real_federation,
+            federation=federation,
             federation_options=config_record_to_proto(c_record),
             app_spec=app_spec or "",
         )
@@ -212,22 +222,13 @@ def _run_with_control_api(
                 f"🎊 Successfully started run {res.run_id}", fg=typer.colors.GREEN
             )
         else:
-            if is_remote_app:
-                typer.secho(
-                    "❌ Failed to start run. Please check that the provided "
-                    "app identifier (@account_name/app_name) is correct.",
-                    fg=typer.colors.RED,
-                    err=True,
-                )
-            else:
-                typer.secho("❌ Failed to start run", fg=typer.colors.RED, err=True)
-            raise typer.Exit(code=1)
+            raise click.ClickException("Failed to start run")
 
-        if output_format == CliOutputFormat.JSON:
+        if is_json:
             # Only include FAB metadata if we actually built a local FAB
             payload: dict[str, Any] = {
                 "success": res.HasField("run_id"),
-                "run-id": res.run_id if res.HasField("run_id") else None,
+                "run-id": f"{res.run_id}" if res.HasField("run_id") else None,
             }
             if not is_remote_app:
                 payload.update(
@@ -239,8 +240,7 @@ def _run_with_control_api(
                         "fab-filename": get_fab_filename(config, fab_hash),
                     }
                 )
-            restore_output()
-            Console().print_json(json.dumps(payload))
+            print_json_to_stdout(payload)
 
         if stream:
             start_stream(res.run_id, channel, CONN_REFRESH_PERIOD)
@@ -251,26 +251,12 @@ def _run_with_control_api(
 
 def _run_without_control_api(
     app: Path | None,
-    federation_config: dict[str, Any],
+    simulation_options: SuperLinkSimulationOptions,
     config_overrides: list[str] | None,
-    federation: str,
 ) -> None:
-    try:
-        num_supernodes = federation_config["options"]["num-supernodes"]
-        verbose: bool | None = federation_config["options"].get("verbose")
-        backend_cfg = federation_config["options"].get("backend", {})
-    except KeyError as err:
-        typer.secho(
-            "❌ The project's `pyproject.toml` needs to declare the number of"
-            " SuperNodes in the simulation. To simulate 10 SuperNodes,"
-            " use the following notation:\n\n"
-            f"[tool.flwr.federations.{federation}]\n"
-            "options.num-supernodes = 10\n",
-            fg=typer.colors.RED,
-            bold=True,
-            err=True,
-        )
-        raise typer.Exit(code=1) from err
+
+    num_supernodes = simulation_options.num_supernodes
+    verbose = simulation_options.verbose or False
 
     command = [
         "flower-simulation",
@@ -280,9 +266,10 @@ def _run_without_control_api(
         f"{num_supernodes}",
     ]
 
-    if backend_cfg:
+    if simulation_options.backend:
         # Stringify as JSON
-        command.extend(["--backend-config", json.dumps(backend_cfg)])
+        backend_serial = _serialize_simulation_options(simulation_options)
+        command.extend(["--backend-config", json.dumps(backend_serial)])
 
     if verbose:
         command.extend(["--verbose"])

flwr/cli/run_utils.py

@@ -18,8 +18,8 @@
 from dataclasses import dataclass
 from datetime import datetime, timedelta
 
-from flwr.common.date import format_timedelta, isoformat8601_utc
 from flwr.common.typing import Run
+from flwr.supercore.date import isoformat8601_utc
 
 
 @dataclass
@@ -40,8 +40,8 @@ class RunRow:  # pylint: disable=too-many-instance-attributes
         The SHA-256 hash of the FAB.
     status_text : str
         The formatted status text.
-    elapsed : str
-        The formatted elapsed time.
+    elapsed : float
+        The elapsed time in seconds.
     pending_at : str
         Timestamp when run entered pending state.
     starting_at : str
@@ -50,6 +50,16 @@ class RunRow:  # pylint: disable=too-many-instance-attributes
         Timestamp when run entered running state.
     finished_at : str
         Timestamp when run finished.
+    network_traffic_inbound : int
+        The total inbound network traffic (in bytes) used during the run.
+        It includes the traffic from SuperNodes to SuperLink.
+    network_traffic_outbound : int
+        The total outbound network traffic (in bytes) used during the run.
+        It includes the traffic from SuperLink to SuperNodes.
+    compute_time_serverapp : float
+        The total compute time (in seconds) of the ServerApp during the run.
+    compute_time_clientapp : float
+        The total compute time (in seconds) of all ClientApps during the run.
     """
 
     run_id: int
@@ -58,11 +68,15 @@ class RunRow:  # pylint: disable=too-many-instance-attributes
     fab_version: str
     fab_hash: str
     status_text: str
-    elapsed: str
+    elapsed: float
     pending_at: str
     starting_at: str
     running_at: str
     finished_at: str
+    network_traffic_inbound: int
+    network_traffic_outbound: int
+    compute_time_serverapp: float
+    compute_time_clientapp: float
 
 
 def format_runs(runs: list[Run], now_isoformat: str) -> list[RunRow]:
@@ -120,11 +134,15 @@ def format_runs(runs: list[Run], now_isoformat: str) -> list[RunRow]:
             fab_version=run.fab_version,
             fab_hash=run.fab_hash,
             status_text=status_text,
-            elapsed=format_timedelta(elapsed_time),
+            elapsed=elapsed_time.total_seconds(),
             pending_at=_format_datetime(pending_at),
             starting_at=_format_datetime(starting_at),
             running_at=_format_datetime(running_at),
             finished_at=_format_datetime(finished_at),
+            network_traffic_inbound=run.bytes_recv,
+            network_traffic_outbound=run.bytes_sent,
+            compute_time_serverapp=elapsed_time.total_seconds(),
+            compute_time_clientapp=run.clientapp_runtime,
         )
         run_list.append(row)
     return run_list

flwr/cli/stop.py

@@ -15,50 +15,45 @@
 """Flower command line interface `stop` command."""
 
 
-import io
-import json
-from pathlib import Path
 from typing import Annotated
 
+import click
 import typer
-from rich.console import Console
 
-from flwr.cli.config_utils import (
-    exit_if_no_address,
-    load_and_validate,
-    process_loaded_project_config,
-    validate_federation_in_project_config,
-)
+from flwr.cli.config_migration import migrate, warn_if_federation_config_overrides
 from flwr.cli.constant import FEDERATION_CONFIG_HELP_MESSAGE
-from flwr.common.constant import FAB_CONFIG_FILE, CliOutputFormat
-from flwr.common.logger import print_json_error, redirect_output, restore_output
+from flwr.cli.flower_config import read_superlink_connection
+from flwr.common.constant import CliOutputFormat
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     StopRunRequest,
     StopRunResponse,
 )
 from flwr.proto.control_pb2_grpc import ControlStub
 
-from .utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
+from .utils import (
+    cli_output_handler,
+    flwr_cli_grpc_exc_handler,
+    init_channel_from_connection,
+    print_json_to_stdout,
+)
 
 
 def stop(  # pylint: disable=R0914
+    ctx: typer.Context,
     run_id: Annotated[  # pylint: disable=unused-argument
         int,
         typer.Argument(help="The Flower run ID to stop"),
     ],
-    app: Annotated[
-        Path,
-        typer.Argument(help="Path of the Flower project"),
-    ] = Path("."),
-    federation: Annotated[
+    superlink: Annotated[
         str | None,
-        typer.Argument(help="Name of the federation"),
+        typer.Argument(help="Name of the SuperLink connection."),
     ] = None,
     federation_config_overrides: Annotated[
         list[str] | None,
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
+            hidden=True,
         ),
     ] = None,
     output_format: Annotated[
@@ -75,61 +70,29 @@ def stop(  # pylint: disable=R0914
     This command stops a running Flower App execution by sending a stop request to the
     SuperLink via the Control API.
     """
-    suppress_output = output_format == CliOutputFormat.JSON
-    captured_output = io.StringIO()
-    try:
-        if suppress_output:
-            redirect_output(captured_output)
-
-        # Load and validate federation config
-        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(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, "stop")
+    with cli_output_handler(output_format=output_format) as is_json:
+        # Warn `--federation-config` is ignored
+        warn_if_federation_config_overrides(federation_config_overrides)
+
+        migrate(superlink, args=ctx.args)
+
+        # Read superlink connection configuration
+        superlink_connection = read_superlink_connection(superlink)
         channel = None
+
         try:
-            auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
-            channel = init_channel(app, federation_config, auth_plugin)
+            channel = init_channel_from_connection(superlink_connection)
             stub = ControlStub(channel)  # pylint: disable=unused-variable # noqa: F841
 
             typer.secho(f"✋ Stopping run ID {run_id}...", fg=typer.colors.GREEN)
-            _stop_run(stub=stub, run_id=run_id, output_format=output_format)
-
-        except ValueError as err:
-            typer.secho(
-                f"❌ {err}",
-                fg=typer.colors.RED,
-                bold=True,
-                err=True,
-            )
-            raise typer.Exit(code=1) from err
+            _stop_run(stub=stub, run_id=run_id, is_json=is_json)
+
         finally:
             if channel:
                 channel.close()
-    except (typer.Exit, Exception) as err:  # pylint: disable=broad-except
-        if suppress_output:
-            restore_output()
-            e_message = captured_output.getvalue()
-            print_json_error(e_message, err)
-        else:
-            typer.secho(
-                f"{err}",
-                fg=typer.colors.RED,
-                bold=True,
-                err=True,
-            )
-    finally:
-        if suppress_output:
-            restore_output()
-        captured_output.close()
 
 
-def _stop_run(stub: ControlStub, run_id: int, output_format: str) -> None:
+def _stop_run(stub: ControlStub, run_id: int, is_json: bool) -> None:
     """Stop a run and display the result.
 
     Parameters
@@ -138,23 +101,19 @@ def _stop_run(stub: ControlStub, run_id: int, output_format: str) -> None:
         The gRPC stub for Control API communication.
     run_id : int
         The unique identifier of the run to stop.
-    output_format : str
-        Output format ('default' or 'json').
+    is_json : bool
+        Whether JSON output format is requested.
     """
     with flwr_cli_grpc_exc_handler():
         response: StopRunResponse = stub.StopRun(request=StopRunRequest(run_id=run_id))
     if response.success:
         typer.secho(f"✅ Run {run_id} successfully stopped.", fg=typer.colors.GREEN)
-        if output_format == CliOutputFormat.JSON:
-            run_output = json.dumps(
+        if is_json:
+            print_json_to_stdout(
                 {
                     "success": True,
-                    "run-id": run_id,
+                    "run-id": f"{run_id}",
                 }
             )
-            restore_output()
-            Console().print_json(run_output)
     else:
-        typer.secho(
-            f"❌ Run {run_id} couldn't be stopped.", fg=typer.colors.RED, err=True
-        )
+        raise click.ClickException(f"Run {run_id} couldn't be stopped.")