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

flwr/cli/supernode/register.py

@@ -15,26 +15,19 @@
 """Flower command line interface `supernode register` command."""
 
 
-import io
-import json
 from pathlib import Path
 from typing import Annotated
 
+import click
 import typer
 from cryptography.exceptions import UnsupportedAlgorithm
 from cryptography.hazmat.primitives import serialization
 from cryptography.hazmat.primitives.asymmetric import ec
-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.common.constant import FAB_CONFIG_FILE, CliOutputFormat
+from flwr.cli.config_migration import migrate
+from flwr.cli.flower_config import read_superlink_connection
+from flwr.common.constant import CliOutputFormat
 from flwr.common.exit import ExitCode, flwr_exit
-from flwr.common.logger import print_json_error, redirect_output, restore_output
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     RegisterNodeRequest,
     RegisterNodeResponse,
@@ -42,23 +35,25 @@ from flwr.proto.control_pb2 import (  # pylint: disable=E0611
 from flwr.proto.control_pb2_grpc import ControlStub
 from flwr.supercore.primitives.asymmetric import public_key_to_bytes, uses_nist_ec_curve
 
-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 register(  # pylint: disable=R0914
+    ctx: typer.Context,
     public_key: Annotated[
         Path,
         typer.Argument(
             help="Path to a P-384 (or any other NIST EC curve) public key file.",
         ),
     ],
-    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,
     output_format: Annotated[
         str,
@@ -70,69 +65,33 @@ def register(  # pylint: disable=R0914
     ] = CliOutputFormat.DEFAULT,
 ) -> None:
     """Add a SuperNode to the federation."""
-    suppress_output = output_format == CliOutputFormat.JSON
-    captured_output = io.StringIO()
-
     # Load public key
-    public_key_path = Path(public_key)
-    public_key_bytes = try_load_public_key(public_key_path)
+    public_key_bytes = try_load_public_key(public_key.expanduser())
 
-    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
-        )
-        exit_if_no_address(federation_config, "supernode register")
+    with cli_output_handler(output_format=output_format) as is_json:
+        # Migrate legacy usage if any
+        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)
-            stub = ControlStub(channel)  # pylint: disable=unused-variable # noqa: F841
+            channel = init_channel_from_connection(superlink_connection)
+            stub = ControlStub(channel)
 
             _register_node(
-                stub=stub, public_key=public_key_bytes, output_format=output_format
+                stub=stub,
+                public_key=public_key_bytes,
+                is_json=is_json,
             )
 
-        except ValueError as err:
-            typer.secho(
-                f"❌ {err}",
-                fg=typer.colors.RED,
-                bold=True,
-                err=True,
-            )
-            raise typer.Exit(code=1) from err
         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 _register_node(stub: ControlStub, public_key: bytes, output_format: str) -> None:
+def _register_node(stub: ControlStub, public_key: bytes, is_json: bool) -> None:
     """Register a node."""
     with flwr_cli_grpc_exc_handler():
         response: RegisterNodeResponse = stub.RegisterNode(
@@ -143,31 +102,23 @@ def _register_node(stub: ControlStub, public_key: bytes, output_format: str) ->
             f"✅ SuperNode {response.node_id} registered successfully.",
             fg=typer.colors.GREEN,
         )
-        if output_format == CliOutputFormat.JSON:
-            run_output = json.dumps(
+        if is_json:
+            print_json_to_stdout(
                 {
                     "success": True,
                     "node-id": response.node_id,
                 }
             )
-            restore_output()
-            Console().print_json(run_output)
     else:
-        typer.secho(
-            "❌ SuperNode couldn't be registered.", fg=typer.colors.RED, err=True
-        )
+        raise click.ClickException("SuperNode couldn't be registered.")
 
 
 def try_load_public_key(public_key_path: Path) -> bytes:
     """Try to load a public key from a file."""
     if not public_key_path.exists():
-        typer.secho(
-            f"❌ Public key file '{public_key_path}' does not exist.",
-            fg=typer.colors.RED,
-            bold=True,
-            err=True,
+        raise click.ClickException(
+            f"Public key file '{public_key_path}' does not exist."
         )
-        raise typer.Exit(code=1)
 
     with open(public_key_path, "rb") as key_file:
         try:

flwr/cli/supernode/unregister.py

@@ -15,42 +15,35 @@
 """Flower command line interface `supernode unregister` command."""
 
 
-import io
-import json
-from pathlib import Path
 from typing import Annotated
 
 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.common.constant import FAB_CONFIG_FILE, CliOutputFormat
-from flwr.common.logger import print_json_error, redirect_output, restore_output
+from flwr.cli.config_migration import migrate
+from flwr.cli.flower_config import read_superlink_connection
+from flwr.common.constant import CliOutputFormat
 from flwr.proto.control_pb2 import UnregisterNodeRequest  # 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 (
+    cli_output_handler,
+    flwr_cli_grpc_exc_handler,
+    init_channel_from_connection,
+    print_json_to_stdout,
+)
 
 
 def unregister(  # pylint: disable=R0914
+    ctx: typer.Context,
     node_id: Annotated[
         int,
         typer.Argument(
             help="ID of the SuperNode to remove.",
         ),
     ],
-    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,
     output_format: Annotated[
         str,
@@ -62,66 +55,29 @@ def unregister(  # pylint: disable=R0914
     ] = CliOutputFormat.DEFAULT,
 ) -> None:
     """Unregister a SuperNode from the federation."""
-    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
-        )
-        exit_if_no_address(federation_config, "supernode unregister")
+    with cli_output_handler(output_format=output_format) as is_json:
+        # Migrate legacy usage if any
+        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)
-            stub = ControlStub(channel)  # pylint: disable=unused-variable # noqa: F841
+            channel = init_channel_from_connection(superlink_connection)
+            stub = ControlStub(channel)
 
-            _unregister_node(stub=stub, node_id=node_id, output_format=output_format)
+            _unregister_node(stub=stub, node_id=node_id, is_json=is_json)
 
-        except ValueError as err:
-            typer.secho(
-                f"❌ {err}",
-                fg=typer.colors.RED,
-                bold=True,
-                err=True,
-            )
-            raise typer.Exit(code=1) from err
         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 _unregister_node(
     stub: ControlStub,
     node_id: int,
-    output_format: str,
+    is_json: bool,
 ) -> None:
     """Unregister a SuperNode from the federation."""
     with flwr_cli_grpc_exc_handler():
@@ -129,12 +85,10 @@ def _unregister_node(
     typer.secho(
         f"✅ SuperNode {node_id} unregistered successfully.", fg=typer.colors.GREEN
     )
-    if output_format == CliOutputFormat.JSON:
-        run_output = json.dumps(
+    if is_json:
+        print_json_to_stdout(
             {
                 "success": True,
                 "node-id": node_id,
             }
         )
-        restore_output()
-        Console().print_json(run_output)

flwr/cli/typing.py

@@ -0,0 +1,200 @@
+# Copyright 2026 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Flower command line interface type definitions."""
+
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from flwr.cli.constant import (
+    DEFAULT_SIMULATION_BACKEND_NAME,
+    SuperLinkConnectionTomlKey,
+)
+from flwr.supercore.utils import check_federation_format
+
+_ERROR_MSG_FMT = "SuperLinkConnection.%s is None"
+
+
+@dataclass
+class SimulationClientResources:
+    """Resource configuration for the ClientApp."""
+
+    num_cpus: float | None = None
+    num_gpus: float | None = None
+
+    def __post_init__(self) -> None:
+        """Validate client resources configuration."""
+        if self.num_cpus is not None and not isinstance(self.num_cpus, (int, float)):
+            raise ValueError("client-resources.num-cpus must be a number (int/float).")
+        if self.num_gpus is not None and not isinstance(self.num_gpus, (int, float)):
+            raise ValueError("client-resources.num-gpus must be a number (int/float).")
+
+
+@dataclass
+class SimulationInitArgs:
+    """Initialization arguments for the simulation."""
+
+    num_cpus: int | None = None
+    num_gpus: int | None = None
+    logging_level: str | None = None
+    log_to_drive: bool | None = None
+
+    def __post_init__(self) -> None:
+        """Validate initialization arguments."""
+        if self.num_cpus is not None and not isinstance(self.num_cpus, int):
+            raise ValueError("init-args.num-cpus must be an integer.")
+        if self.num_gpus is not None and not isinstance(self.num_gpus, int):
+            raise ValueError("init-args.num-gpus must be an integer.")
+        if self.logging_level is not None and not isinstance(self.logging_level, str):
+            raise ValueError("init-args.logging-level must be a string.")
+        if self.log_to_drive is not None and not isinstance(self.log_to_drive, bool):
+            raise ValueError("init-args.log-to-drive must be a boolean.")
+
+
+@dataclass
+class SimulationBackendConfig:
+    """Backend configuration for the simulation."""
+
+    client_resources: SimulationClientResources | None = None
+    init_args: SimulationInitArgs | None = None
+    name: str = DEFAULT_SIMULATION_BACKEND_NAME
+
+    def __post_init__(self) -> None:
+        """Validate backend configuration."""
+        if not isinstance(self.name, str):
+            raise ValueError("backend.name must be a string.")
+
+
+@dataclass
+class SuperLinkSimulationOptions:
+    """Options for local simulation."""
+
+    num_supernodes: int
+    backend: SimulationBackendConfig | None = None
+    verbose: bool | None = None
+
+    def __post_init__(self) -> None:
+        """Validate simulation options."""
+        if not isinstance(self.num_supernodes, int):
+            raise ValueError(
+                "Invalid simulation options: num-supernodes must be an integer."
+            )
+        if self.verbose is not None and not isinstance(self.verbose, bool):
+            raise ValueError("Invalid simulation options: verbose must be a boolean.")
+
+
+@dataclass
+class SuperLinkConnection:
+    """SuperLink connection configuration for CLI commands.
+
+    Attributes
+    ----------
+    name : str
+         The name of the connection configuration.
+    address : str
+        The address of the SuperLink (Control API).
+    root_certificates : str
+         The absolute path to the root CA certificate file.
+    insecure : bool (default: False)
+         Whether to use an insecure channel. If True, the
+         connection will not use TLS encryption.
+    federation : str
+         The name of the federation to interface with.
+    options : SuperLinkSimulationOptions
+         Configuration options for the simulation runtime.
+    """
+
+    name: str
+    address: str | None = None
+    root_certificates: str | None = None
+    _insecure: bool | None = None
+    federation: str | None = None
+    options: SuperLinkSimulationOptions | None = None
+
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    def __init__(
+        self,
+        name: str,
+        address: str | None = None,
+        root_certificates: str | None = None,
+        insecure: bool | None = None,
+        federation: str | None = None,
+        options: SuperLinkSimulationOptions | None = None,
+    ) -> None:
+        self.name = name
+        self.address = address
+        self.root_certificates = root_certificates
+        self._insecure = insecure
+        self.federation = federation
+        self.options = options
+
+        self.__post_init__()
+
+    @property
+    def insecure(self) -> bool:
+        """Return the insecure flag or its default (False) if unset."""
+        if self._insecure is None:
+            return False
+        return self._insecure
+
+    def __post_init__(self) -> None:
+        """Validate SuperLink connection configuration."""
+        err_prefix = f"Invalid value for key '%s' in connection '{self.name}': "
+        if self.address is not None and not isinstance(self.address, str):
+            raise ValueError(
+                err_prefix % SuperLinkConnectionTomlKey.ADDRESS
+                + f"expected str, but got {type(self.address).__name__}."
+            )
+        if self.root_certificates is not None and not isinstance(
+            self.root_certificates, str
+        ):
+            raise ValueError(
+                err_prefix % SuperLinkConnectionTomlKey.ROOT_CERTIFICATES
+                + f"expected str, but got {type(self.root_certificates).__name__}."
+            )
+
+        # Ensure root certificates path is absolute
+        if self.root_certificates is not None:
+            if not Path(self.root_certificates).is_absolute():
+                raise ValueError(
+                    err_prefix % SuperLinkConnectionTomlKey.ROOT_CERTIFICATES
+                    + "expected absolute path, but got relative path "
+                    f"'{self.root_certificates}'."
+                )
+
+        if self._insecure is not None and not isinstance(self._insecure, bool):
+            raise ValueError(
+                err_prefix % SuperLinkConnectionTomlKey.INSECURE
+                + f"expected bool, but got {type(self._insecure).__name__}."
+            )
+
+        if self.federation is not None:
+            if not isinstance(self.federation, str):
+                raise ValueError(
+                    err_prefix % SuperLinkConnectionTomlKey.FEDERATION
+                    + f"expected str, but got {type(self.federation).__name__}."
+                )
+
+            # Check if the federation string is valid
+            check_federation_format(self.federation)
+
+        # The connection needs to have either an address or options (or both).
+        if self.address is None and self.options is None:
+            raise ValueError(
+                "Invalid SuperLink connection format: "
+                f"'{SuperLinkConnectionTomlKey.ADDRESS}' and/or "
+                f"'{SuperLinkConnectionTomlKey.OPTIONS}' key "
+                "need to be specified."
+            )