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

flwr/cli/auth_plugin/oidc_cli_plugin.py

@@ -15,26 +15,26 @@
 """Flower CLI account auth plugin for OIDC."""
 
 
-import json
 import time
+import webbrowser
 from collections.abc import Sequence
-from pathlib import Path
-from typing import Any
 
+import click
 import typer
 
-from flwr.common.constant import (
-    ACCESS_TOKEN_KEY,
-    AUTHN_TYPE_JSON_KEY,
-    REFRESH_TOKEN_KEY,
-    AuthnType,
+from flwr.cli.constant import (
+    ACCESS_TOKEN_STORE_KEY,
+    AUTHN_TYPE_STORE_KEY,
+    REFRESH_TOKEN_STORE_KEY,
 )
+from flwr.common.constant import ACCESS_TOKEN_KEY, REFRESH_TOKEN_KEY, AuthnType
 from flwr.common.typing import AccountAuthCredentials, AccountAuthLoginDetails
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     GetAuthTokensRequest,
     GetAuthTokensResponse,
 )
 from flwr.proto.control_pb2_grpc import ControlStub
+from flwr.supercore.credential_store import get_credential_store
 
 from .auth_plugin import CliAuthPlugin, LoginError
 
@@ -46,10 +46,11 @@ class OidcCliPlugin(CliAuthPlugin):
     access to Flower SuperLink.
     """
 
-    def __init__(self, credentials_path: Path):
+    def __init__(self, host: str):
         self.access_token: str | None = None
         self.refresh_token: str | None = None
-        self.credentials_path = credentials_path
+        self.host = host
+        self.store = get_credential_store()
 
     @staticmethod
     def login(
@@ -75,11 +76,17 @@ class OidcCliPlugin(CliAuthPlugin):
         LoginError
             If authentication times out.
         """
+        # Prompt user to login via browser
+        webbrowser.open(login_details.verification_uri_complete)
         typer.secho(
-            "Please log into your Flower account here: "
+            "A browser window has been opened for you to "
+            "log into your Flower account.\n"
+            "If it did not open automatically, use this URL:\n"
             f"{login_details.verification_uri_complete}",
             fg=typer.colors.BLUE,
         )
+
+        # Wait for user to complete login
         start_time = time.time()
         time.sleep(login_details.interval)
 
@@ -102,45 +109,38 @@ class OidcCliPlugin(CliAuthPlugin):
         raise LoginError("Process timed out.")
 
     def store_tokens(self, credentials: AccountAuthCredentials) -> None:
-        """Store authentication tokens to the `credentials_path`.
+        """Store authentication tokens to the credential store."""
+        host = self.host
+        # Retrieve tokens
+        access_token = credentials.access_token
+        refresh_token = credentials.refresh_token
 
-        The credentials, including tokens, will be saved as a JSON file
-        at `credentials_path`.
-        """
-        self.access_token = credentials.access_token
-        self.refresh_token = credentials.refresh_token
-        json_dict = {
-            AUTHN_TYPE_JSON_KEY: AuthnType.OIDC,
-            ACCESS_TOKEN_KEY: credentials.access_token,
-            REFRESH_TOKEN_KEY: credentials.refresh_token,
-        }
+        # Store tokens in the credential store
+        self.store.set(AUTHN_TYPE_STORE_KEY % host, AuthnType.OIDC.encode("utf-8"))
+        self.store.set(ACCESS_TOKEN_STORE_KEY % host, access_token.encode("utf-8"))
+        self.store.set(REFRESH_TOKEN_STORE_KEY % host, refresh_token.encode("utf-8"))
 
-        with open(self.credentials_path, "w", encoding="utf-8") as file:
-            json.dump(json_dict, file, indent=4)
+        # Update internal state
+        self.access_token = access_token
+        self.refresh_token = refresh_token
 
     def load_tokens(self) -> None:
-        """Load authentication tokens from the `credentials_path`."""
-        with open(self.credentials_path, encoding="utf-8") as file:
-            json_dict: dict[str, Any] = json.load(file)
-            access_token = json_dict.get(ACCESS_TOKEN_KEY)
-            refresh_token = json_dict.get(REFRESH_TOKEN_KEY)
+        """Load authentication tokens from the credential store."""
+        access_token_bytes = self.store.get(ACCESS_TOKEN_STORE_KEY % self.host)
+        refresh_token_bytes = self.store.get(REFRESH_TOKEN_STORE_KEY % self.host)
 
-        if isinstance(access_token, str) and isinstance(refresh_token, str):
-            self.access_token = access_token
-            self.refresh_token = refresh_token
+        if access_token_bytes is not None and refresh_token_bytes is not None:
+            self.access_token = access_token_bytes.decode("utf-8")
+            self.refresh_token = refresh_token_bytes.decode("utf-8")
 
     def write_tokens_to_metadata(
         self, metadata: Sequence[tuple[str, str | bytes]]
     ) -> Sequence[tuple[str, str | bytes]]:
         """Write authentication tokens to the provided metadata."""
         if self.access_token is None or self.refresh_token is None:
-            typer.secho(
-                "❌ Missing authentication tokens. Please login first.",
-                fg=typer.colors.RED,
-                bold=True,
-                err=True,
+            raise click.ClickException(
+                "Missing authentication tokens. Please login first."
             )
-            raise typer.Exit(code=1)
 
         return list(metadata) + [
             (ACCESS_TOKEN_KEY, self.access_token),

flwr/cli/build.py

@@ -21,6 +21,7 @@ from io import BytesIO
 from pathlib import Path
 from typing import Annotated, Any
 
+import click
 import pathspec
 import tomli
 import tomli_w
@@ -70,7 +71,7 @@ def get_fab_filename(config: dict[str, Any], fab_hash: str) -> str:
     Parameters
     ----------
     config : dict[str, Any]
-        The project configuration dictionary.
+        The Flower App configuration dictionary.
     fab_hash : str
         The SHA-256 hash of the FAB file.
 
@@ -105,43 +106,29 @@ def build(
     if app is None:
         app = Path.cwd()
 
-    app = app.resolve()
+    app = app.expanduser().resolve()
     if not app.is_dir():
-        typer.secho(
-            f"❌ The path {app} is not a valid path to a Flower app.",
-            fg=typer.colors.RED,
-            bold=True,
-            err=True,
+        raise click.ClickException(
+            f"The path {app} is not a valid path to a Flower app."
         )
-        raise typer.Exit(code=1)
 
     if not is_valid_project_name(app.name):
-        typer.secho(
-            f"❌ The project name {app.name} is invalid, "
-            "a valid project name must start with a letter, "
-            "and can only contain letters, digits, and hyphens.",
-            fg=typer.colors.RED,
-            bold=True,
-            err=True,
+        raise click.ClickException(
+            f"The Flower App name {app.name} is invalid, "
+            "a valid app name must start with a letter, "
+            "and can only contain letters, digits, and hyphens."
         )
-        raise typer.Exit(code=1)
 
-    config, errors, warnings = load_and_validate(app / "pyproject.toml")
-    if config is None:
-        typer.secho(
-            "Project configuration could not be loaded.\npyproject.toml is invalid:\n"
-            + "\n".join([f"- {line}" for line in errors]),
-            fg=typer.colors.RED,
-            bold=True,
-            err=True,
-        )
-        raise typer.Exit(code=1)
+    try:
+        config, warnings = load_and_validate(app / "pyproject.toml")
+    except ValueError as e:
+        raise click.ClickException(str(e)) from None
 
     if warnings:
         typer.secho(
-            "Project configuration is missing the following "
+            "Flower App configuration (pyproject.toml) is missing the following "
             "recommended properties:\n" + "\n".join([f"- {line}" for line in warnings]),
-            fg=typer.colors.RED,
+            fg=typer.colors.YELLOW,
             bold=True,
         )
 

flwr/cli/config/__init__.py

@@ -0,0 +1,21 @@
+# 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 `config` command."""
+
+from .ls import ls as ls
+
+__all__ = [
+    "ls",
+]

flwr/cli/config/ls.py

@@ -0,0 +1,71 @@
+# 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 `config list` command."""
+
+
+from typing import Annotated
+
+import typer
+
+from flwr.common.constant import CliOutputFormat
+
+from ..constant import SuperLinkConnectionTomlKey
+from ..flower_config import read_flower_config
+from ..utils import cli_output_handler, print_json_to_stdout
+
+
+def ls(
+    output_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            case_sensitive=False,
+            help="Format output using 'default' view or 'json'",
+        ),
+    ] = CliOutputFormat.DEFAULT,
+) -> None:
+    """List all SuperLink connections (alias: ls)."""
+    with cli_output_handler(output_format=output_format) as is_json:
+        # Load Flower Config
+        config, config_path = read_flower_config()
+
+        # Get `superlink` tables
+        superlink_connections = config.get(SuperLinkConnectionTomlKey.SUPERLINK, {})
+
+        # Get default, then pop from dict
+        default = superlink_connections.pop(SuperLinkConnectionTomlKey.DEFAULT, None)
+
+        connection_names = list(superlink_connections.keys())
+
+        if is_json:
+            conn = {
+                SuperLinkConnectionTomlKey.SUPERLINK: connection_names,
+                SuperLinkConnectionTomlKey.DEFAULT: default,
+            }
+            print_json_to_stdout(conn)
+        else:
+            typer.secho("Flower Config file: ", fg=typer.colors.BLUE, nl=False)
+            typer.secho(f"{config_path}", fg=typer.colors.GREEN)
+            typer.secho("SuperLink connections:", fg=typer.colors.BLUE)
+            # List SuperLink connections and highlight default
+            for k in connection_names:
+                typer.secho(f"  {k}", fg=typer.colors.GREEN, nl=False)
+                if k == default:
+                    typer.secho(
+                        f" ({SuperLinkConnectionTomlKey.DEFAULT})",
+                        fg=typer.colors.WHITE,
+                        nl=False,
+                    )
+                typer.echo()

flwr/cli/config_migration.py

@@ -0,0 +1,297 @@
+# 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.
+# ==============================================================================
+"""Utilities for migrating old TOML configurations to Flower config."""
+
+
+import re
+from pathlib import Path
+from typing import Any
+
+import click
+import typer
+
+from .config_utils import load_and_validate, validate_federation_in_project_config
+from .flower_config import (
+    init_flwr_config,
+    parse_superlink_connection,
+    set_default_superlink_connection,
+    write_superlink_connection,
+)
+
+CONFIG_MIGRATION_NOTICE = """
+#######################################################################
+# CONFIGURATION MIGRATION NOTICE:
+#
+# What was previously called "federation config" for SuperLink
+# connections in pyproject.toml has been renamed and moved.
+#
+# These settings are now **SuperLink connection configuration**
+# and are defined in the Flower configuration file.
+#
+# The entries below are commented out intentionally and are kept
+# only as a migration reference.
+#
+# Docs: https://flower.ai/docs/framework/ref-flower-configuration.html
+#######################################################################
+
+"""
+
+CLI_NOTICE = (
+    typer.style("\n🌸 Heads up from Flower!\n\n", fg=typer.colors.MAGENTA, bold=True)
+    + "We detected legacy usage of this command that relies on connection\n"
+    + "settings from your pyproject.toml.\n\n"
+    + "Flower will migrate any relevant settings to the new Flower config.\n\n"
+    + "Learn more: https://flower.ai/docs/framework/ref-flower-configuration.html\n"
+)
+
+
+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 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 path
+    if (pth / "pyproject.toml").exists():
+        return True
+
+    return False
+
+
+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():
+        return False, f"No pyproject.toml found in '{app}'"
+
+    try:
+        config, _ = load_and_validate(toml_path, check_module=False)
+    except ValueError as e:
+        return False, str(e)
+
+    try:
+        _ = config["tool"]["flwr"]["federations"]
+        return True, None
+    except KeyError:
+        return False, f"No '[tool.flwr.federations]' section found in '{toml_path}'"
+
+
+def _migrate_pyproject_toml_to_flower_config(
+    app: Path, toml_federation: str | None
+) -> tuple[list[str], str | None]:
+    """Migrate old TOML configuration to Flower config."""
+    # Load and validate the old TOML configuration
+    toml_path = app / "pyproject.toml"
+    config, _ = load_and_validate(toml_path, check_module=False)
+    validate_federation_in_project_config(toml_federation, config)
+
+    # Construct SuperLinkConnection
+    toml_federations: dict[str, Any] = config["tool"]["flwr"]["federations"]
+    migrated_conn_names: list[str] = []
+    for name, toml_fed_config in toml_federations.items():
+        if isinstance(toml_fed_config, dict):
+            # Resolve relative root-certificates path
+            if cert_path := toml_fed_config.get("root-certificates"):
+                if not Path(cert_path).is_absolute():
+                    toml_fed_config["root-certificates"] = str(
+                        (app / cert_path).expanduser().resolve()
+                    )
+            # Parse and write SuperLink connection
+            conn = parse_superlink_connection(toml_fed_config, name)
+            write_superlink_connection(conn)
+            migrated_conn_names.append(name)
+
+    # Set default federation if applicable
+    default_toml_federation: str | None = toml_federations.get("default")
+    if default_toml_federation in toml_federations:
+        set_default_superlink_connection(default_toml_federation)
+
+    return migrated_conn_names, default_toml_federation
+
+
+def _comment_out_legacy_toml_config(app: Path) -> None:
+    """Comment out legacy TOML configuration in pyproject.toml."""
+    # Read pyproject.toml lines
+    toml_path = app / "pyproject.toml"
+    lines = toml_path.read_text(encoding="utf-8").splitlines(keepends=True)
+    section_pattern = re.compile(r"\s*\[(.*)\]")
+
+    # Comment out the [tool.flwr.federations] section
+    notice_added = False
+    in_federation_section = False
+    with toml_path.open("w", encoding="utf-8") as f:
+        for line in lines:
+            # Detect section headers
+            if match := section_pattern.match(line):
+                section = match.group(1)
+                in_federation_section = section.startswith("tool.flwr.federations")
+
+            # Comment out lines in the federation section
+            if in_federation_section:
+                if not notice_added:
+                    f.write(CONFIG_MIGRATION_NOTICE)
+                    notice_added = True
+                # Preserve empty lines and comment out others
+                f.write(f"# {line}" if line.strip() != "" else line)
+            else:
+                f.write(line)
+
+
+def migrate(
+    positional_arg_1: str | None,
+    args: list[str],
+    ignore_legacy_usage: bool = False,
+) -> None:
+    """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()
+
+    # 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:])})")
+
+    # Determine app path for migration
+    arg1 = positional_arg_1
+    app = Path(arg1) if arg1 else Path(".")
+    app = app.expanduser().resolve()
+
+    # 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
+        )
+    except Exception as e:
+        raise click.ClickException(
+            f"Failed to migrate legacy TOML configuration to Flower config:\n{e!r}"
+        ) from e
+
+    typer.secho("✅ Migration completed successfully!\n", fg=typer.colors.GREEN)
+
+    # Print migrated connections
+    typer.secho("Migrated SuperLink connections:", fg=typer.colors.BLUE)
+    for conn_name in migrated_conns:
+        typer.secho(f"  {conn_name}", fg=typer.colors.GREEN, nl=False)
+        if conn_name == default_conn:
+            typer.secho(" (default)", fg=typer.colors.WHITE, nl=False)
+        typer.echo()
+
+    _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)
+
+        # 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,
+    )