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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flwr-nightly
-Version: 1.26.0.dev20260119
+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.dev20260119 → 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.dev20260119 → flwr_nightly-1.26.0.dev20260121}/py/flwr/cli/config_migration.py

@@ -57,44 +57,55 @@ CLI_NOTICE = (
 )
 
 
-def _is_legacy_usage(superlink: str, 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 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
 
     return False
 
 
-def _check_is_migratable(app: Path) -> None:
-    """Check if the given app path contains legacy TOML configuration."""
+def _is_migratable(app: Path) -> tuple[bool, str | None]:
+    """Check if the given app path contains legacy TOML configuration.
+
+    Parameters
+    ----------
+    app : Path
+        Path to the Flower App.
+
+    Returns
+    -------
+    tuple[bool, str | None]
+        Returns (True, None) if migratable, else (False, reason).
+    """
     toml_path = app / "pyproject.toml"
     if not toml_path.exists():
-        raise FileNotFoundError(f"No pyproject.toml found in '{app}'")
+        return False, f"No pyproject.toml found in '{app}'"
     config, errors, _ = load_and_validate(toml_path, check_module=False)
     if config is None:
-        raise ValueError(f"Failed to load TOML configuration: {toml_path}")
+        return False, f"Failed to load TOML configuration: {toml_path}"
     if errors:
-        raise ValueError(
-            f"Invalid TOML configuration found in '{toml_path}':\n"
-            + "\n".join(f"- {err}" for err in errors)
-        )
+        err_msg = f"Invalid TOML configuration found in '{toml_path}':\n"
+        err_msg += "\n".join(f"- {err}" for err in errors)
+        return False, err_msg
     try:
         _ = config["tool"]["flwr"]["federations"]
-        return
+        return True, None
     except KeyError:
-        raise ValueError(
-            f"No '[tool.flwr.federations]' section found in '{toml_path}'"
-        ) from None
+        return False, f"No '[tool.flwr.federations]' section found in '{toml_path}'"
 
 
 def _migrate_pyproject_toml_to_flower_config(
@@ -161,23 +172,82 @@ def _comment_out_legacy_toml_config(app: Path) -> None:
 
 
 def migrate(
-    app: Path,
-    toml_federation: str | None,
+    positional_arg_1: str | None,
+    args: list[str],
+    ignore_legacy_usage: bool = False,
 ) -> None:
-    """Migrate legacy TOML configuration to Flower config."""
+    """Migrate legacy TOML configuration to Flower config.
+
+    Migrates SuperLink connection settings from `[tool.flwr.federations]` in
+    pyproject.toml to the new Flower config format when legacy usage is detected
+    or the migration is applicable.
+
+    `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
+    ----------
+    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)
+        Set to `True` only for `flwr run` command to skip legacy usage check.
+
+    Raises
+    ------
+    click.UsageError
+        If more than one extra argument is provided.
+    click.ClickException
+        If legacy usage detected but migration fails.
+
+    Examples
+    --------
+    The following usages will trigger migration if applicable:
+    - `flwr <CMD> . my-federation`
+    - `flwr <CMD> ./my-app`
+    - `flwr <CMD>`
+
+    The following usages will NOT trigger migration:
+    - `flwr <CMD> named-conn`
+
+    Notes
+    -----
+    This function will NOT return when legacy usage is detected to force the user
+    to adapt to the new usage pattern after migration.
+    """
     # Initialize Flower config
     init_flwr_config()
 
-    # Print migration notice
-    typer.echo(CLI_NOTICE)
+    # Trigger the same typer error when detecting unexpected extra args
+    if len(args) > 1:
+        raise click.UsageError(f"Got unexpected extra arguments ({' '.join(args[1:])})")
 
-    # Check if migration is applicable
+    # Determine app path for migration
+    arg1 = positional_arg_1
+    app = Path(arg1) if arg1 else Path(".")
     app = app.resolve()
-    try:
-        _check_is_migratable(app)
-    except (FileNotFoundError, ValueError) as e:
-        raise click.ClickException(f"Cannot migrate configuration:\n{e}") from e
 
+    # Check if migration is applicable and if legacy usage is detected
+    is_migratable, reason = _is_migratable(app)
+    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:
+        typer.echo(CLI_NOTICE)
+
+    if not is_migratable:
+        # Raise error if legacy usage is detected but migration is not applicable
+        if is_legacy:
+            raise click.ClickException(
+                f"Cannot migrate configuration:\n{reason}. \nThis is expected if the "
+                "migration has been previously carried out. Use `--help` after your "
+                "command to see the new usage pattern."
+            )
+        return  # Nothing to migrate
+
+    # Perform migration
+    toml_federation = args[0] if len(args) == 1 else None
     try:
         migrated_conns, default_conn = _migrate_pyproject_toml_to_flower_config(
             app, toml_federation
@@ -197,30 +267,34 @@ def migrate(
             typer.secho(" (default)", fg=typer.colors.WHITE, nl=False)
         typer.echo()
 
-    # print usage
-    typer.secho("\nYou should now use the Flower CLI as follows:")
-    ctx = click.get_current_context()
-    typer.secho(ctx.get_usage() + "\n", bold=True)
-
     _comment_out_legacy_toml_config(app)
 
+    if is_legacy:
+        # print usage
+        typer.secho("\nYou should now use the Flower CLI as follows:")
+        ctx = click.get_current_context()
+        typer.secho(ctx.get_usage() + "\n", bold=True)
 
-def migrate_if_legacy_usage(
-    superlink: str,
-    args: list[str],
-) -> bool:
-    """Migrate legacy TOML configuration to Flower config if legacy usage is
-    detected."""
-    # Trigger the same typer error when detecting unexpected extra args
-    if len(args) > 1:
-        raise click.UsageError(f"Got unexpected extra arguments ({' '.join(args[1:])})")
+        # Abort if legacy usage is detected to force user to adapt to new usage
+        raise typer.Exit(code=1)
 
-    # Skip migration if no legacy usage is detected
-    if not _is_legacy_usage(superlink, args):
-        return False
 
-    migrate(
-        app=Path(superlink),
-        toml_federation=args[0] if len(args) == 1 else None,
+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,
     )
-    return True

{flwr_nightly-1.26.0.dev20260119 → flwr_nightly-1.26.0.dev20260121}/py/flwr/cli/flower_config.py

@@ -217,17 +217,17 @@ def serialize_superlink_connection(connection: SuperLinkConnection) -> dict[str,
     """
     # pylint: disable=protected-access
     conn_dict: dict[str, Any] = {
-        SuperLinkConnectionTomlKey.ADDRESS: connection._address,
-        SuperLinkConnectionTomlKey.ROOT_CERTIFICATES: connection._root_certificates,
+        SuperLinkConnectionTomlKey.ADDRESS: connection.address,
+        SuperLinkConnectionTomlKey.ROOT_CERTIFICATES: connection.root_certificates,
         SuperLinkConnectionTomlKey.INSECURE: connection._insecure,
         SuperLinkConnectionTomlKey.ENABLE_ACCOUNT_AUTH: connection._enable_account_auth,
-        SuperLinkConnectionTomlKey.FEDERATION: connection._federation,
+        SuperLinkConnectionTomlKey.FEDERATION: connection.federation,
     }
     # Remove None values
     conn_dict = {k: v for k, v in conn_dict.items() if v is not None}
 
-    if connection._options is not None:
-        options_dict = _serialize_simulation_options(connection._options)
+    if connection.options is not None:
+        options_dict = _serialize_simulation_options(connection.options)
         conn_dict[SuperLinkConnectionTomlKey.OPTIONS] = options_dict
 
     return conn_dict

{flwr_nightly-1.26.0.dev20260119 → 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.dev20260119 → 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.dev20260119 → 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(