flwr-nightly 1.26.0.dev20260120__tar.gz → 1.26.0.dev20260121__tar.gz

{flwr_nightly-1.26.0.dev20260120 → flwr_nightly-1.26.0.dev20260121}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flwr-nightly
-Version: 1.26.0.dev20260120
+Version: 1.26.0.dev20260121
 Summary: Flower: A Friendly Federated AI Framework
 License: Apache-2.0
 Keywords: Artificial Intelligence,Federated AI,Federated Analytics,Federated Evaluation,Federated Learning,Flower,Machine Learning

{flwr_nightly-1.26.0.dev20260120 → flwr_nightly-1.26.0.dev20260121}/py/flwr/cli/app.py

@@ -14,6 +14,9 @@
 # ==============================================================================
 """Flower command line interface."""
 
+
+from typing import Any, TypedDict
+
 import typer
 from typer.main import get_command
 
@@ -37,6 +40,15 @@ from .supernode import ls as supernode_list
 from .supernode import register as supernode_register
 from .supernode import unregister as supernode_unregister
 
+
+class CommandKwargs(TypedDict):
+    """Keywords for typer command to make mypy happy."""
+
+    context_settings: dict[str, Any]
+
+
+ALLOW_EXTRAS: CommandKwargs = {"context_settings": {"allow_extra_args": True}}
+
 app = typer.Typer(
     help=typer.style(
         "flwr is the Flower command line interface.",
@@ -51,12 +63,12 @@ app.command()(new)
 app.command()(run)
 app.command()(build)
 app.command()(install)
-app.command()(log)
-app.command("list")(ls)
-app.command(hidden=True)(ls)
-app.command()(stop)
+app.command(**ALLOW_EXTRAS)(log)
+app.command("list", **ALLOW_EXTRAS)(ls)
+app.command(hidden=True, **ALLOW_EXTRAS)(ls)
+app.command(**ALLOW_EXTRAS)(stop)
 app.command()(login)
-app.command()(pull)
+app.command(**ALLOW_EXTRAS)(pull)
 
 # Create supernode command group
 supernode_app = typer.Typer(help="Manage SuperNodes")

{flwr_nightly-1.26.0.dev20260120 → flwr_nightly-1.26.0.dev20260121}/py/flwr/cli/config_migration.py

@@ -57,21 +57,21 @@ CLI_NOTICE = (
 )
 
 
-def _is_legacy_usage(superlink: str | None, args: list[str]) -> bool:
+def _is_legacy_usage(positional_arg_1: str | None, args: list[str]) -> bool:
     """Check if legacy usage is detected in the given arguments."""
-    if superlink is None:
+    if positional_arg_1 is None:
         return False
 
     # If one and only one extra argument is given, assume legacy usage
     if len(args) == 1:
         return True
 
-    # If the `superlink` looks like a path, assume legacy usage
-    pth = Path(superlink)
-    if pth.is_absolute() or len(pth.parts) > 1 or superlink in (".", ".."):
+    # If the first positional argument looks like a path, assume legacy usage
+    pth = Path(positional_arg_1)
+    if pth.is_absolute() or len(pth.parts) > 1 or positional_arg_1 in (".", ".."):
         return True
 
-    # Lastly, check if a pyproject.toml file exists at the given superlink
+    # Lastly, check if a pyproject.toml file exists at the given path
     if (pth / "pyproject.toml").exists():
         return True
 
@@ -172,7 +172,7 @@ def _comment_out_legacy_toml_config(app: Path) -> None:
 
 
 def migrate(
-    superlink: str | None,
+    positional_arg_1: str | None,
     args: list[str],
     ignore_legacy_usage: bool = False,
 ) -> None:
@@ -182,13 +182,13 @@ def migrate(
     pyproject.toml to the new Flower config format when legacy usage is detected
     or the migration is applicable.
 
-    `flwr run` should call `migrate(superlink, [], ignore_legacy_usage=True)` to skip
+    `flwr run` should call `migrate(app, [], ignore_legacy_usage=True)` to skip
     legacy usage check. Other CLI commands should call `migrate(superlink, ctx.args)`.
 
     Parameters
     ----------
-    superlink : str | None
-        Value of the `[SUPERLINK]` argument provided to the CLI command.
+    positional_arg_1 : str | None
+        The first positional argument.
     args : list[str]
         Additional arguments. In legacy usage, this is the TOML federation name.
     ignore_legacy_usage : bool (default: False)
@@ -224,12 +224,13 @@ def migrate(
         raise click.UsageError(f"Got unexpected extra arguments ({' '.join(args[1:])})")
 
     # Determine app path for migration
-    app = Path(superlink) if superlink else Path(".")
+    arg1 = positional_arg_1
+    app = Path(arg1) if arg1 else Path(".")
     app = app.resolve()
 
     # Check if migration is applicable and if legacy usage is detected
     is_migratable, reason = _is_migratable(app)
-    is_legacy = _is_legacy_usage(superlink, args) if not ignore_legacy_usage else False
+    is_legacy = _is_legacy_usage(arg1, args) if not ignore_legacy_usage else False
 
     # Print notice once if legacy usage detected or migration is applicable
     if is_legacy or is_migratable:
@@ -276,3 +277,24 @@ def migrate(
 
         # Abort if legacy usage is detected to force user to adapt to new usage
         raise typer.Exit(code=1)
+
+
+def warn_if_federation_config_overrides(
+    federation_config_overrides: list[str] | None,
+) -> None:
+    """Warn if federation config overrides are provided.
+
+    Parameters
+    ----------
+    federation_config_overrides : list[str] | None
+        List of federation config override strings.
+    """
+    if federation_config_overrides is None:
+        return
+
+    typer.secho(
+        "⚠️ Warning: `--federation-config` option is deprecated and will be ignored.\n"
+        "Use Flower configuration files to set SuperLink connections.",
+        fg=typer.colors.YELLOW,
+        bold=True,
+    )

{flwr_nightly-1.26.0.dev20260120 → flwr_nightly-1.26.0.dev20260121}/py/flwr/cli/log.py

@@ -17,25 +17,21 @@
 
 import time
 from logging import DEBUG, ERROR, INFO
-from pathlib import Path
-from typing import Annotated, Any, cast
+from typing import Annotated, cast
 
 import grpc
 import typer
 
-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.cli.flower_config import read_superlink_connection
+from flwr.cli.typing import SuperLinkConnection
 from flwr.common.constant import CONN_RECONNECT_INTERVAL, CONN_REFRESH_PERIOD
 from flwr.common.logger import log as logger
 from flwr.proto.control_pb2 import StreamLogsRequest  # pylint: disable=E0611
 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 flwr_cli_grpc_exc_handler, init_channel_from_connection
 
 
 class AllLogsRetrieved(BaseException):
@@ -158,23 +154,21 @@ def print_logs(run_id: int, channel: grpc.Channel, timeout: int) -> None:
 
 
 def log(
+    ctx: typer.Context,
     run_id: Annotated[
         int,
         typer.Argument(help="The Flower run ID to query"),
     ],
-    app: Annotated[
-        Path,
-        typer.Argument(help="Path of the Flower project to run"),
-    ] = Path("."),
-    federation: Annotated[
+    superlink: Annotated[
         str | None,
-        typer.Argument(help="Name of the federation to run the app on"),
+        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,
     stream: Annotated[
@@ -190,27 +184,24 @@ def log(
     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)
+    # Warn `--federation-config` is ignored
+    warn_if_federation_config_overrides(federation_config_overrides)
 
-    pyproject_path = app / "pyproject.toml" 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, "log")
+    # Migrate legacy usage if any
+    migrate(superlink, args=ctx.args)
+
+    # Read superlink connection configuration
+    superlink_connection = read_superlink_connection(superlink)
 
     try:
-        _log_with_control_api(app, federation, federation_config, run_id, stream)
+        _log_with_control_api(superlink_connection, run_id, stream)
     except Exception as err:  # pylint: disable=broad-except
         typer.secho(str(err), fg=typer.colors.RED, bold=True, err=True)
         raise typer.Exit(code=1) from None
 
 
 def _log_with_control_api(
-    app: Path,
-    federation: str,
-    federation_config: dict[str, Any],
+    superlink_connection: SuperLinkConnection,
     run_id: int,
     stream: bool,
 ) -> None:
@@ -218,19 +209,14 @@ def _log_with_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.
+    superlink_connection : SuperLinkConnection
+        Superlink connection configuration.
     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)
+    channel = init_channel_from_connection(superlink_connection)
 
     if stream:
         start_stream(run_id, channel, CONN_REFRESH_PERIOD)

{flwr_nightly-1.26.0.dev20260120 → flwr_nightly-1.26.0.dev20260121}/py/flwr/cli/ls.py

@@ -17,22 +17,17 @@
 
 import io
 import json
-from pathlib import Path
-from typing import Annotated, cast
+from typing import Annotated
 
 import typer
 from rich.console import Console
 from rich.table import Table
 from rich.text import Text
 
-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, Status, SubStatus
+from flwr.cli.flower_config import read_superlink_connection
+from flwr.common.constant import 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.proto.control_pb2 import (  # pylint: disable=E0611
@@ -43,24 +38,21 @@ 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
+from .utils import flwr_cli_grpc_exc_handler, init_channel_from_connection
 
 
 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[
+    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,
     runs: Annotated[
@@ -99,32 +91,29 @@ def ls(  # pylint: disable=too-many-locals, too-many-branches, R0913, R0917
 
     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()
+
+    if suppress_output:
+        redirect_output(captured_output)
+
+    # Warn `--federation-config` is ignored
+    warn_if_federation_config_overrides(federation_config_overrides)
+
+    # Migrate legacy usage if any
+    migrate(superlink, args=ctx.args)
+
+    # Read superlink connection configuration
+    superlink_connection = read_superlink_connection(superlink)
+    channel = None
+
     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, 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 = 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)
 
             # Display information about a specific run ID

{flwr_nightly-1.26.0.dev20260120 → flwr_nightly-1.26.0.dev20260121}/py/flwr/cli/pull.py

@@ -15,46 +15,38 @@
 """Flower command line interface `pull` command."""
 
 
-from pathlib import Path
 from typing import Annotated
 
 import typer
 
-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
+from flwr.cli.flower_config import read_superlink_connection
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     PullArtifactsRequest,
     PullArtifactsResponse,
 )
 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 flwr_cli_grpc_exc_handler, init_channel_from_connection
 
 
 def pull(  # pylint: disable=R0914
+    ctx: typer.Context,
     run_id: Annotated[
         int,
         typer.Argument(help="Run ID to pull artifacts from."),
     ],
-    app: Annotated[
-        Path,
-        typer.Argument(help="Path of the Flower App to run."),
-    ] = 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,
 ) -> None:
@@ -63,20 +55,17 @@ def pull(  # pylint: disable=R0914
     Retrieve a download URL for artifacts generated during a completed Flower run. The
     artifacts can then be downloaded from the provided URL.
     """
-    typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
+    # Warn `--federation-config` is ignored
+    warn_if_federation_config_overrides(federation_config_overrides)
+
+    # Migrate legacy usage if any
+    migrate(superlink, args=ctx.args)
 
-    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, "pull")
+    # 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)
         with flwr_cli_grpc_exc_handler():
             res: PullArtifactsResponse = stub.PullArtifacts(

{flwr_nightly-1.26.0.dev20260120 → flwr_nightly-1.26.0.dev20260121}/py/flwr/cli/run/run.py

@@ -26,15 +26,15 @@ import typer
 from rich.console import Console
 
 from flwr.cli.build import build_fab_from_disk, get_fab_filename
+from flwr.cli.config_migration import migrate, warn_if_federation_config_overrides
 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.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,
     parse_config_args,
     user_config_to_configrecord,
@@ -49,7 +49,7 @@ from flwr.supercore.constant import NOOP_FEDERATION
 from flwr.supercore.utils import parse_app_spec
 
 from ..log import start_stream
-from ..utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
+from ..utils import flwr_cli_grpc_exc_handler, init_channel_from_connection
 
 CONN_REFRESH_PERIOD = 60  # Connection refresh period for log streaming (seconds)
 
@@ -60,9 +60,9 @@ def run(
         Path,
         typer.Argument(help="Path of the Flower App to run."),
     ] = Path("."),
-    federation: Annotated[
+    superlink: Annotated[
         str | None,
-        typer.Argument(help="Name of the federation to run the app on."),
+        typer.Argument(help="Name of the SuperLink connection."),
     ] = None,
     run_config_overrides: Annotated[
         list[str] | None,
@@ -77,6 +77,7 @@ def run(
         typer.Option(
             "--federation-config",
             help=FEDERATION_CONFIG_HELP_MESSAGE,
+            hidden=True,
         ),
     ] = None,
     stream: Annotated[
@@ -99,9 +100,20 @@ def run(
     """Run Flower App."""
     suppress_output = output_format == CliOutputFormat.JSON
     captured_output = io.StringIO()
+
+    if suppress_output:
+        redirect_output(captured_output)
+
+    # 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)
+
     try:
-        if suppress_output:
-            redirect_output(captured_output)
 
         # Determine if app is remote
         app_spec = None
@@ -116,27 +128,11 @@ def run(
             app_spec = app_str
             # Set `app` to current directory for credential storage
             app = Path(".")
-        is_remote_app = app_spec is not None
-
-        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)
-
-        federation, federation_config = validate_federation_in_project_config(
-            federation, config, federation_config_overrides
-        )
-
-        if "address" in federation_config:
+        if superlink_connection.address:
             _run_with_control_api(
                 app,
-                federation,
-                federation_config,
+                superlink_connection,
                 run_config_overrides,
                 stream,
                 output_format,
@@ -144,7 +140,9 @@ def run(
             )
         else:
             _run_without_control_api(
-                app, federation_config, run_config_overrides, federation
+                app=app,
+                simulation_options=superlink_connection.options,  # type: ignore
+                config_overrides=run_config_overrides,
             )
     except (typer.Exit, Exception) as err:  # pylint: disable=broad-except
         if suppress_output:
@@ -167,8 +165,7 @@ def run(
 # pylint: disable-next=R0913, R0914, R0917
 def _run_with_control_api(
     app: Path,
-    federation: str,
-    federation_config: dict[str, Any],
+    superlink_connection: SuperLinkConnection,
     config_overrides: list[str] | None,
     stream: bool,
     output_format: str,
@@ -177,8 +174,7 @@ def _run_with_control_api(
     channel = None
     is_remote_app = app_spec is not 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)
 
         # Build FAB if local app
@@ -194,16 +190,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)
+        federation: str = superlink_connection.federation or 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 = _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 "",
         )
@@ -246,26 +245,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 = False  # bool | None = superlink_connection.options.verbose
 
     command = [
         "flower-simulation",
@@ -275,9 +260,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"])